Return to plugins.txt CVS log | Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated |
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: