================
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