[svn-inject] Installing original source of lighttpd

1 files changed, 260 insertions, 0 deletions

diff --git a/doc/plugins.txt b/doc/plugins.txt
new file mode 100644
index 0000000..8a755fe
--- /dev/null
+++ b/doc/plugins.txt
@@ -0,0 +1,260 @@
+================
+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
+  
+