261 lines
5.4 KiB
Plaintext
261 lines
5.4 KiB
Plaintext
================
|
|
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
|
|
|
|
|