Annotation of embedaddon/lighttpd/doc/outdated/plugins.txt, revision 1.1.1.1
1.1 misho 1: ================
2: Plugin Interface
3: ================
4:
5: ------------
6: Module: core
7: ------------
8:
9: :Author: Jan Kneschke
10: :Date: $Date: 2004/08/01 07:01:29 $
11: :Revision: $Revision: 1.1 $
12:
13: :abstract:
14: The plugin interface is an integral part of lighttpd which
15: provides a flexible way to add specific functionality to lighttpd.
16:
17: .. meta::
18: :keywords: lighttpd, plugins
19:
20: .. contents:: Table of Contents
21:
22: Description
23: ===========
24:
25: Plugins allow you to enhance the functionality of lighttpd without
26: changing the core of the webserver. They can be loaded at startup time
27: and can change virtually any aspect of the behaviour of the webserver.
28:
29: Plugin Entry Points
30: -------------------
31:
32: lighttpd has 16 hooks which are used in different states of the
33: execution of the request:
34:
35: Serverwide hooks
36: ````````````````
37:
38: :init_:
39: called when the plugin is loaded
40: :cleanup_:
41: called when the plugin is unloaded
42: :set_defaults_:
43: called when the configuration has to be processed
44: :handle_trigger_:
45: called once a second
46: :handle_sighup_:
47: called when the server received a SIGHUP
48:
49: Connectionwide hooks
50: ````````````````````
51:
52: Most of these hooks are called in ``http_response_prepare()`` after some
53: fields in the connection structure are set.
54:
55: :handle_uri_raw_:
56: called after uri.path_raw, uri.authority and uri.scheme are set
57: :handle_uri_clean_:
58: called after uri.path (a clean URI without .. and %20) is set
59: :handle_docroot_:
60: called at the end of the logical path handle to get a docroot
61: :handle_subrequest_start_:
62: called if the physical path is set up and checked
63: :handle_subrequest_:
64: called at the end of ``http_response_prepare()``
65: :handle_physical_path_:
66: called after the physical path is created and no other handler is
67: found for this request
68: :handle_request_done_:
69: called when the request is done
70: :handle_connection_close_:
71: called if the connection has to be closed
72: :handle_joblist_:
73: called after the connection_state_engine is left again and plugin
74: internal handles have to be called
75: :connection_reset_:
76: called if the connection structure has to be cleaned up
77:
78:
79: Plugin Interface
80: ----------------
81:
82: \*_plugin_init
83: ``````````````
84:
85: Every plugin has a uniquely-named function which is called after the
86: plugin is loaded. It is used to set up the ``plugin`` structure with
87: some useful data:
88:
89: - name of the plugin ``name``
90: - all hooks
91:
92: The field ``data`` and ``lib`` should not be touched in the init function.
93: ``lib`` is the library handler from dlopen and ``data`` will be the storage
94: of the internal plugin data.
95:
96: :returns:
97: 0 (not handled)
98:
99: init
100: ````
101:
102: The first real call of a plugin function is the init hook which is used
103: to set up the internal plugin data. The internal plugin is assigned the
104: ``data`` field mentioned in the \*_plugin_init description.
105:
106: :returns:
107: a pointer to the internal plugin data.
108:
109: cleanup
110: ```````
111:
112: The cleanup hook is called just before the plugin is unloaded. It is meant
113: to free all buffers allocated in ``init`` or somewhere else in the plugin
114: which are still not freed and to close all handles which were opened and
115: are not closed yet.
116:
117: :returns:
118: HANDLER_GO_ON if ok (not handled)
119:
120: set_defaults
121: ````````````
122:
123: set_defaults is your entry point into the configfile parsing. It should
124: pass a list of options to ``config_insert_values`` and check if
125: the plugin configuration is valid. If it is not valid yet, it should
126: set useful defaults or return with HANDLER_ERROR and an error message.
127:
128: :returns:
129: HANDLER_GO_ON if ok
130:
131: HANDLER_ERROR will terminate lighttpd
132:
133: connection_reset
134: ````````````````
135:
136: called at the end of each request
137:
138: :returns:
139: HANDLER_GO_ON if ok
140:
141: HANDLER_ERROR on error
142:
143: handle_trigger
144: ``````````````
145:
146: called once a second
147:
148: :returns:
149: HANDLER_GO_ON if ok
150:
151: HANDLER_ERROR on error
152:
153: handle_sighup
154: `````````````
155:
156: called if a SIGHUP is received (cycling logfiles, ...)
157:
158: :returns:
159: HANDLER_GO_ON if ok
160:
161: HANDLER_ERROR on error
162:
163: handle_uri_raw
164: ``````````````
165:
166: called after uri_raw is set
167:
168: :returns:
169: HANDLER_GO_ON if ok
170: HANDLER_FINISHED if the final output is prepared
171:
172: HANDLER_ERROR on error
173:
174: handle_uri_clean
175: ````````````````
176:
177: called after uri.path is set
178:
179: :returns:
180: HANDLER_GO_ON if ok
181: HANDLER_FINISHED if the final output is prepared
182:
183: HANDLER_ERROR on error
184:
185: handle_docroot
186: ``````````````
187:
188: called when a docroot is needed
189:
190: :returns:
191: HANDLER_GO_ON if ok
192: HANDLER_FINISHED if the final output is prepared
193:
194: HANDLER_ERROR on error
195:
196: handle_subrequest_start
197: ```````````````````````
198:
199: called after physical.path is set
200:
201: :returns:
202: HANDLER_GO_ON if ok
203: HANDLER_FINISHED if the final output is prepared
204:
205: HANDLER_ERROR on error
206:
207: handle_subrequest
208: `````````````````
209:
210: called if subrequest_start requested a COMEBACK or a WAIT_FOR_EVENT
211:
212: :returns:
213: HANDLER_GO_ON if ok
214: HANDLER_FINISHED if the final output is prepared
215:
216: HANDLER_ERROR on error
217:
218: handle_physical_path
219: ````````````````````
220:
221: called after physical.path is set
222:
223: :returns:
224: HANDLER_GO_ON if ok
225: HANDLER_FINISHED if the final output is prepared
226:
227: HANDLER_ERROR on error
228:
229:
230: handle_request_done
231: ```````````````````
232:
233: called at the end of the request (logging, statistics, ...)
234:
235: :returns:
236: HANDLER_GO_ON if ok
237:
238: HANDLER_ERROR on error
239:
240: handle_connection_close
241: ```````````````````````
242:
243: called if the connection is terminated
244:
245: :returns:
246: HANDLER_GO_ON if ok
247:
248: HANDLER_ERROR on error
249:
250: handle_joblist
251: ``````````````
252:
253: called if the state of the connection has changed
254:
255: :returns:
256: HANDLER_GO_ON if ok
257:
258: HANDLER_ERROR on error
259:
260:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to plugins.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated