lighttpd 1.4.x https://www.lighttpd.net/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
lighttpd1.4/doc/plugins.txt

260 lines
5.4 KiB

================
Plugin Interface
================
------------
Module: core
------------
:Author: Jan Kneschke
:Date: $Date: 2004/08/01 07:01:29 $
:Revision: $Revision: 1.1 $
:abstract:
The plugin interface is the integral part of lighttpd provide
a flexible way to add specific functionality to lighttpd.
.. meta::
:keywords: lighttpd, plugins
.. contents:: Table of Contents
Description
===========
Plugins allow you to enhance to functionality of lighttpd without
changing the core of the webserver. They can be loaded at startup-time
and can change hardly any aspect of the behaviour of the webserver.
Plugin Entry Points
-------------------
lighttpd has 16 hooks which are used in different states of the
execution of the request:
Serverwide hooks
````````````````
:init_:
called when the plugin is loaded
:cleanup_:
called when the plugin is unloaded
:set_defaults_:
called when the configuration has to be processed
:handle_trigger_:
called once a second
:handle_sighup_:
called when the server received a SIGHUP
Connectionwide hooks
````````````````````
Most of these hooks are call in ``http_response_prepare()`` after some
field in the connection structure are set.
:handle_uri_raw_:
called after uri.path_raw, uri.authority and uri.scheme are set
:handle_uri_clean_:
called after uri.path (a clean uri without .. and %20) is set
:handle_docroot_:
called at the end of the logical path handle to get a docroot
:handle_subrequest_start_:
called if the physical path is setup and checked
:handle_subrequest_:
called at the end of ``http_response_prepare()``
:handle_physical_path_:
called after the physical path is created and no other handler is
found for this request
:handle_request_done_:
called when the request is done
:handle_connection_close_:
called if the connection has to be closed
:handle_joblist_:
called after the connection_state_engine is left again and plugin
internal handles have to be called
:connection_reset_:
called if the connection structure has to be cleaned up
Plugin Interface
----------------
\*_plugin_init
``````````````
Every plugin has a uniquely named function which is called after the
plugin is loaded. It is used to setup the ``plugin`` structure with
some usefull data:
- name of the plugin ``name``
- all hooks
The field ``data`` and ``lib`` should not be touched in the init function.
``lib`` is the library handler from dlopen and ``data`` will be the storage
of the internal plugin data.
:returns:
0 (not handled)
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 description.
:returns:
a pointer to the internal plugin data.
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:
HANDLER_GO_ON if ok (not handled)
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 usefull defaults or return with HANDLER_ERROR and an error message.
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR will terminated lighttpd
connection_reset
````````````````
called at the end of each request
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR on error
handle_trigger
``````````````
called once a second
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR on error
handle_sighup
`````````````
called if a SIGHUP is received (cycling logfiles, ...)
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR on error
handle_uri_raw
``````````````
called after uri_raw is set
:returns:
HANDLER_GO_ON if ok
HANDLER_FINISHED if the final output is prepared
HANDLER_ERROR on error
handle_uri_clean
````````````````
called after uri.path is set
:returns:
HANDLER_GO_ON if ok
HANDLER_FINISHED if the final output is prepared
HANDLER_ERROR on error
handle_docroot
``````````````
called when a docroot is needed
:returns:
HANDLER_GO_ON if ok
HANDLER_FINISHED if the final output is prepared
HANDLER_ERROR on error
handle_subrequest_start
```````````````````````
called after physical.path is set
:returns:
HANDLER_GO_ON if ok
HANDLER_FINISHED if the final output is prepared
HANDLER_ERROR on error
handle_subrequest
`````````````````
called if subrequest_start requested a COMEBACK or a WAIT_FOR_EVENT
:returns:
HANDLER_GO_ON if ok
HANDLER_FINISHED if the final output is prepared
HANDLER_ERROR on error
handle_physical_path
````````````````````
called after physical.path is set
:returns:
HANDLER_GO_ON if ok
HANDLER_FINISHED if the final output is prepared
HANDLER_ERROR on error
handle_request_done
```````````````````
called at the end of the request (logging, statistics, ...)
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR on error
handle_connection_close
```````````````````````
called if the connection is terminated
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR on error
handle_joblist
``````````````
called if the state of the connection has changed
:returns:
HANDLER_GO_ON if ok
HANDLER_ERROR on error