Return to plugins.txt CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated

1.4.33

    1: ================
    2: Plugin Interface
    3: ================
    4: 
    5: ------------
    6: Module: core
    7: ------------
    8: 
    9: :Author: Jan Kneschke
   10: :Date: $Date: 2013/10/14 10:32:48 $
   11: :Revision: $Revision: 1.1.1.1 $
   12: 
   13: :abstract:
   14:   The plugin interface is an integral part of lighttpd which
   15:   provides a flexible way to add specific functionality to lighttpd.
   16: 
   17: .. meta::
   18:   :keywords: lighttpd, plugins
   19: 
   20: .. contents:: Table of Contents
   21: 
   22: Description
   23: ===========
   24: 
   25: Plugins allow you to enhance the functionality of lighttpd without
   26: changing the core of the webserver. They can be loaded at startup time
   27: and can change virtually any aspect of the behaviour of the webserver.
   28: 
   29: Plugin Entry Points
   30: -------------------
   31: 
   32: lighttpd has 16 hooks which are used in different states of the
   33: execution of the request:
   34: 
   35: Serverwide hooks
   36: ````````````````
   37: 
   38: :init_:
   39:   called when the plugin is loaded
   40: :cleanup_:
   41:   called when the plugin is unloaded
   42: :set_defaults_:
   43:   called when the configuration has to be processed
   44: :handle_trigger_:
   45:   called once a second
   46: :handle_sighup_:
   47:   called when the server received a SIGHUP
   48: 
   49: Connectionwide hooks
   50: ````````````````````
   51: 
   52: Most of these hooks are called in ``http_response_prepare()`` after some
   53: fields in the connection structure are set.
   54: 
   55: :handle_uri_raw_:
   56:   called after uri.path_raw, uri.authority and uri.scheme are set
   57: :handle_uri_clean_:
   58:   called after uri.path (a clean URI without .. and %20) is set
   59: :handle_docroot_:
   60:   called at the end of the logical path handle to get a docroot
   61: :handle_subrequest_start_:
   62:   called if the physical path is set up and checked
   63: :handle_subrequest_:
   64:   called at the end of ``http_response_prepare()``
   65: :handle_physical_path_:
   66:   called after the physical path is created and no other handler is
   67:   found for this request
   68: :handle_request_done_:
   69:   called when the request is done
   70: :handle_connection_close_:
   71:   called if the connection has to be closed
   72: :handle_joblist_:
   73:   called after the connection_state_engine is left again and plugin
   74:   internal handles have to be called
   75: :connection_reset_:
   76:   called if the connection structure has to be cleaned up
   77: 
   78: 
   79: Plugin Interface
   80: ----------------
   81: 
   82: \*_plugin_init
   83: ``````````````
   84: 
   85: Every plugin has a uniquely-named function which is called after the
   86: plugin is loaded. It is used to set up the ``plugin`` structure with
   87: some useful data:
   88: 
   89: - name of the plugin ``name``
   90: - all hooks
   91: 
   92: The field ``data`` and ``lib`` should not be touched in the init function.
   93: ``lib`` is the library handler from dlopen and ``data`` will be the storage
   94: of the internal plugin data.
   95: 
   96: :returns:
   97:   0 (not handled)
   98: 
   99: init
  100: ````
  101: 
  102: The first real call of a plugin function is the init hook which is used
  103: to set up the internal plugin data. The internal plugin is assigned the
  104: ``data`` field mentioned in the \*_plugin_init description.
  105: 
  106: :returns:
  107:   a pointer to the internal plugin data.
  108: 
  109: cleanup
  110: ```````
  111: 
  112: The cleanup hook is called just before the plugin is unloaded. It is meant
  113: to free all buffers allocated in ``init`` or somewhere else in the plugin
  114: which are still not freed and to close all handles which were opened and
  115: are not closed yet.
  116: 
  117: :returns:
  118:   HANDLER_GO_ON if ok (not handled)
  119: 
  120: set_defaults
  121: ````````````
  122: 
  123: set_defaults is your entry point into the configfile parsing. It should
  124: pass a list of options to ``config_insert_values`` and check if
  125: the plugin configuration is valid. If it is not valid yet, it should
  126: set useful defaults or return with HANDLER_ERROR and an error message.
  127: 
  128: :returns:
  129:   HANDLER_GO_ON if ok
  130: 
  131:   HANDLER_ERROR will terminate lighttpd
  132: 
  133: connection_reset
  134: ````````````````
  135: 
  136: called at the end of each request
  137: 
  138: :returns:
  139:   HANDLER_GO_ON if ok
  140: 
  141:   HANDLER_ERROR on error
  142: 
  143: handle_trigger
  144: ``````````````
  145: 
  146: called once a second
  147: 
  148: :returns:
  149:   HANDLER_GO_ON if ok
  150: 
  151:   HANDLER_ERROR on error
  152: 
  153: handle_sighup
  154: `````````````
  155: 
  156: called if a SIGHUP is received (cycling logfiles, ...)
  157: 
  158: :returns:
  159:   HANDLER_GO_ON if ok
  160: 
  161:   HANDLER_ERROR on error
  162: 
  163: handle_uri_raw
  164: ``````````````
  165: 
  166: called after uri_raw is set
  167: 
  168: :returns:
  169:   HANDLER_GO_ON if ok
  170:   HANDLER_FINISHED if the final output is prepared
  171: 
  172:   HANDLER_ERROR on error
  173: 
  174: handle_uri_clean
  175: ````````````````
  176: 
  177: called after uri.path is set
  178: 
  179: :returns:
  180:   HANDLER_GO_ON if ok
  181:   HANDLER_FINISHED if the final output is prepared
  182: 
  183:   HANDLER_ERROR on error
  184: 
  185: handle_docroot
  186: ``````````````
  187: 
  188: called when a docroot is needed
  189: 
  190: :returns:
  191:   HANDLER_GO_ON if ok
  192:   HANDLER_FINISHED if the final output is prepared
  193: 
  194:   HANDLER_ERROR on error
  195: 
  196: handle_subrequest_start
  197: ```````````````````````
  198: 
  199: called after physical.path is set
  200: 
  201: :returns:
  202:   HANDLER_GO_ON if ok
  203:   HANDLER_FINISHED if the final output is prepared
  204: 
  205:   HANDLER_ERROR on error
  206: 
  207: handle_subrequest
  208: `````````````````
  209: 
  210: called if subrequest_start requested a COMEBACK or a WAIT_FOR_EVENT
  211: 
  212: :returns:
  213:   HANDLER_GO_ON if ok
  214:   HANDLER_FINISHED if the final output is prepared
  215: 
  216:   HANDLER_ERROR on error
  217: 
  218: handle_physical_path
  219: ````````````````````
  220: 
  221: called after physical.path is set
  222: 
  223: :returns:
  224:   HANDLER_GO_ON if ok
  225:   HANDLER_FINISHED if the final output is prepared
  226: 
  227:   HANDLER_ERROR on error
  228: 
  229: 
  230: handle_request_done
  231: ```````````````````
  232: 
  233: called at the end of the request (logging, statistics, ...)
  234: 
  235: :returns:
  236:   HANDLER_GO_ON if ok
  237: 
  238:   HANDLER_ERROR on error
  239: 
  240: handle_connection_close
  241: ```````````````````````
  242: 
  243: called if the connection is terminated
  244: 
  245: :returns:
  246:   HANDLER_GO_ON if ok
  247: 
  248:   HANDLER_ERROR on error
  249: 
  250: handle_joblist
  251: ``````````````
  252: 
  253: called if the state of the connection has changed
  254: 
  255: :returns:
  256:   HANDLER_GO_ON if ok
  257: 
  258:   HANDLER_ERROR on error
  259: 
  260: