Docs InternalPlugins » History » Revision 9
Revision 8 (Anonymous, 2008-01-05 10:52) → Revision 9/10 (stbuehler, 2009-02-17 14:00)
h1. [[TracNav(DocsToc)]] <pre> #!rst ================ Plugin Interface ================ {{>toc}} h2. ------------ Module: core ------------ .. meta:: :keywords: lighttpd, plugins .. contents:: Table of Contents Description =========== Plugins allow you to enhance the functionality of lighttpd without changing the core of the webserver. They can be loaded at startup time and can change virtually any aspect of the behaviour of the webserver. h2. Plugin Entry Points ------------------- Lighttpd lighttpd has 16 hooks which are used in different states of the execution of the request: h3. Serverwide hooks ```````````````` * [[lighttpd:Docs:InternalPlugins#init|init]] :init_: called when the plugin is loaded * [[lighttpd:Docs:InternalPlugins#cleanup|cleanup]] :cleanup_: called when the plugin is unloaded * [[lighttpd:Docs:InternalPlugins#set_defaults|set_defaults]] :set_defaults_: called when the configuration has to be processed * [[lighttpd:Docs:InternalPlugins#handle_trigger|handle_trigger]] :handle_trigger_: called once a second * [[lighttpd:Docs:InternalPlugins#handle_sighup|handle_sighup]] :handle_sighup_: called when the server received a SIGHUP h3. Connectionwide hooks ```````````````````` Most of these hooks are called in @http_response_prepare()@ ``http_response_prepare()`` after some fields in the connection structure are set. * [[lighttpd:Docs:InternalPlugins#handle_uri_raw|handle_uri_raw]] handle_uri_raw_: called after uri.path_raw, uri.authority and uri.scheme are set * [[lighttpd:Docs:InternalPlugins#handle_uri_clean|handle_uri_clean]] handle_uri_clean_: called after uri.path (a clean URI without .. and %20) is set * [[lighttpd:Docs:InternalPlugins#handle_docroot|handle_docroot]] handle_docroot_: called at the end of the logical path handle to get a docroot * [[lighttpd:Docs:InternalPlugins#handle_subrequest_start|handle_subrequest_start]] handle_subrequest_start_: called if the physical path is set up and checked * [[lighttpd:Docs:InternalPlugins#handle_subrequest|handle_subrequest]] handle_subrequest_: called at the end of @http_response_prepare()@ * [[lighttpd:Docs:InternalPlugins#handle_physical_path|handle_physical_path]] ``http_response_prepare()`` handle_physical_path_: called after the physical path is created and no other handler is found for this request * [[lighttpd:Docs:InternalPlugins#handle_request_done|handle_request_done]] handle_request_done_: called when the request is done * [[lighttpd:Docs:InternalPlugins#handle_connection_close|handle_connection_close]] handle_connection_close_: called if the connection has to be closed * [[lighttpd:Docs:InternalPlugins#handle_joblist|handle_joblist]] handle_joblist_: called after the connection_state_engine is left again and plugin internal handles have to be called * [[lighttpd:Docs:InternalPlugins#connection_reset|connection_reset]] connection_reset_: called if the connection structure has to be cleaned up h2. Plugin Interface ---------------- h3. *_plugin_init \*_plugin_init `````````````` Every plugin has a uniquely-named function which is called after the plugin is loaded. It is used to set up the ``plugin`` structure with some useful data: * - name of the plugin @name@ ``name`` * - all hooks The field @data@ ``data`` and qlib@ ``lib`` should not be touched in the init function. @lib@ ``lib`` is the library handler from dlopen and @data@ ``data`` will be the storage of the internal plugin data. _returns_: :returns: 0 (not handled) h3. init ```` The first real call of a plugin function is the init hook which is used to set up the internal plugin data. The internal plugin is assigned the ``data`` field mentioned in the *_plugin_init \*_plugin_init description. _returns_: :returns: a pointer to the internal plugin data. h3. cleanup ``````` The cleanup hook is called just before the plugin is unloaded. It is meant to free all buffers allocated in ``init`` or somewhere else in the plugin which are still not freed and to close all handles which were opened and are not closed yet. _returns_: :returns: HANDLER_GO_ON if ok (not handled) h3. set_defaults ```````````` set_defaults is your entry point into the configfile parsing. It should pass a list of options to ``config_insert_values`` and check if the plugin configuration is valid. If it is not valid yet, it should set useful defaults or return with HANDLER_ERROR and an error message. _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR will terminate lighttpd h3. connection_reset ```````````````` called at the end of each request _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR on error h3. handle_trigger `````````````` called once a second _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR on error h3. handle_sighup ````````````` called if a SIGHUP is received (cycling logfiles, ...) _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR on error h3. handle_uri_raw `````````````` called after uri_raw is set _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_FINISHED if the final output is prepared * HANDLER_ERROR on error h3. handle_uri_clean ```````````````` called after uri.path is set _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_FINISHED if the final output is prepared * HANDLER_ERROR on error h3. handle_docroot `````````````` called when a docroot is needed _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_FINISHED if the final output is prepared * HANDLER_ERROR on error h3. handle_subrequest_start ``````````````````````` called after physical.path is set _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_FINISHED if the final output is prepared * HANDLER_ERROR on error h3. handle_subrequest ````````````````` called if subrequest_start requested a COMEBACK or a WAIT_FOR_EVENT _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_FINISHED if the final output is prepared * HANDLER_ERROR on error h3. handle_physical_path ```````````````````` called after physical.path is set _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_FINISHED if the final output is prepared * HANDLER_ERROR on error h3. handle_request_done ``````````````````` called at the end of the request (logging, statistics, ...) _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR on error h3. handle_connection_close ``````````````````````` called if the connection is terminated _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR on error h3. handle_joblist `````````````` called if the state of the connection has changed _returns_: * :returns: HANDLER_GO_ON if ok * HANDLER_ERROR on error </pre>