1================ 2Plugin Interface 3================ 4 5------------ 6Module: 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 22Description 23=========== 24 25Plugins allow you to enhance the functionality of lighttpd without 26changing the core of the webserver. They can be loaded at startup time 27and can change virtually any aspect of the behaviour of the webserver. 28 29Plugin Entry Points 30------------------- 31 32lighttpd has 16 hooks which are used in different states of the 33execution of the request: 34 35Serverwide 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 49Connectionwide hooks 50```````````````````` 51 52Most of these hooks are called in ``http_response_prepare()`` after some 53fields 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 79Plugin Interface 80---------------- 81 82\*_plugin_init 83`````````````` 84 85Every plugin has a uniquely-named function which is called after the 86plugin is loaded. It is used to set up the ``plugin`` structure with 87some useful data: 88 89- name of the plugin ``name`` 90- all hooks 91 92The 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 94of the internal plugin data. 95 96:returns: 97 0 (not handled) 98 99init 100```` 101 102The first real call of a plugin function is the init hook which is used 103to 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 109cleanup 110``````` 111 112The cleanup hook is called just before the plugin is unloaded. It is meant 113to free all buffers allocated in ``init`` or somewhere else in the plugin 114which are still not freed and to close all handles which were opened and 115are not closed yet. 116 117:returns: 118 HANDLER_GO_ON if ok (not handled) 119 120set_defaults 121```````````` 122 123set_defaults is your entry point into the configfile parsing. It should 124pass a list of options to ``config_insert_values`` and check if 125the plugin configuration is valid. If it is not valid yet, it should 126set 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 133connection_reset 134```````````````` 135 136called at the end of each request 137 138:returns: 139 HANDLER_GO_ON if ok 140 141 HANDLER_ERROR on error 142 143handle_trigger 144`````````````` 145 146called once a second 147 148:returns: 149 HANDLER_GO_ON if ok 150 151 HANDLER_ERROR on error 152 153handle_sighup 154````````````` 155 156called if a SIGHUP is received (cycling logfiles, ...) 157 158:returns: 159 HANDLER_GO_ON if ok 160 161 HANDLER_ERROR on error 162 163handle_uri_raw 164`````````````` 165 166called 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 174handle_uri_clean 175```````````````` 176 177called 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 185handle_docroot 186`````````````` 187 188called 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 196handle_subrequest_start 197``````````````````````` 198 199called 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 207handle_subrequest 208````````````````` 209 210called 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 218handle_physical_path 219```````````````````` 220 221called 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 230handle_request_done 231``````````````````` 232 233called at the end of the request (logging, statistics, ...) 234 235:returns: 236 HANDLER_GO_ON if ok 237 238 HANDLER_ERROR on error 239 240handle_connection_close 241``````````````````````` 242 243called if the connection is terminated 244 245:returns: 246 HANDLER_GO_ON if ok 247 248 HANDLER_ERROR on error 249 250handle_joblist 251`````````````` 252 253called 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 261