Hook Configuration

µC/HTTP-server offers multiple hook functions during the processing of a HTTP transaction.Those hooks allow the HTTP server to be personalize according to your application requirements. The hook configuration is part of the HTTP server Instance configuration and must be included in the HTTPs_CFG object (see section Parameters Configuration).

See section Hook Functions to see at what point of the process each hook is called by the server stack.

Configuration Structure

const  HTTPs_HOOK_CFG  HTTPs_HookCfg = {
	&HTTPs_OnInstanceInit,		/* .OnInstanceInitHook  */
	&HTTPs_OnReqHdrRx,			/* .OnReqHdrRxHook      */
	&HTTPs_OnReq,				/* .OnReqHook           */
	&HTTPs_OnReqBodyRx,			/* .OnReqBodyRxHook     */
	&HTTPs_OnReqRdySignal,  	/* .OnReqRdySignalHook  */
	&HTTPs_OnReqRdyPoll,    	/* .OnReqRdyPollHook    */
	&HTTPs_OnRespHdrTx,     	/* .OnRespHdrTxHook     */
	&HTTPs_OnRespToken,     	/* .OnRespTokenHook     */
	&HTTPs_OnRespChunk,     	/* .OnRespChunkHook     */
	&HTTPs_OnTransComplete, 	/* .OnTransCompleteHook */
	&HTTPs_OnErr,           	/* .OnErrHook           */
    &HTTPs_OnErrFileGet,    	/* .OnErrFileGetHook    */
	&HTTPs_OnConnClose      	/* .OnConnCloseHook     */
};

Fields Description

Structure Field	Type	Description	Possible Values
OnInstanceInitHook	Function pointer	When the instance is created, an hook function can be called to initialize connection objects used by the instance (see Hook Functions page to see when this function is called). If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See Connection Objects Initialization for further details.	SHOULD be a callback function pointer
OnReqHdrRxHook	Function pointer	Configure request header field receive callback function. Each time a header field other than the default one is received, a hook function is called allowing to choose which header field(s) to keep for further processing. If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See Receive Request Header Field for further details.	SHOULD be a callback function pointer
OnReqHook	Function pointer	Configure request hook function. For each new incoming request a hook function can be called by the HTTP server to authenticate the request and accept or reject it. At this point the Start Line and the HTTP headers of the request have been parsed. The data received can be access in the HTTPs_CONN object. This function has also the right to modified some of the parameters of the HTTP transaction inside the HTTPs_CONN object. If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See Connection Request for further details.	SHOULD be a callback function pointer
OnReqBodyRxHook	Function pointer	Configure request body data received hook function. For some applications, it is required to parse itself the data as soon as received and not let the HTTP server core do it. It that case, this hook function allows the application to retrieve the received data directly. If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See On Request Body Received Hook for further details.	SHOULD be a callback function pointer
OnReqRdySignalHook	Function pointer	Configure request ready signal hook function. The Signal hook function occurs after the request has been parse completely (header + body). In the case of a POST request containing a form, all the data have been saved in the CGI key-value pairs block. The list of CGI data is available in the HTTPs_CONN object. The callback function SHOULD not be blocking and SHOULD return quickly. A time consuming function will block the processing of the other connections and reduce the HTTP server performance. In case the CGI data processing is time consuming, the Poll hook function SHOULD be enable to allow the server to periodically verify if the upper application has finished the CGI data processing. If the CGI form feature is not enabled, this field is not used and can be set as DEF_NULL. See Request Ready Signal Hook for further details.	SHOULD be a callback function pointer.
OnReqRdyPollHook	Function pointer	Configure request ready poll hook function. The Poll hook function SHOULD be enable in case the request data processing require lots of time. It allows the HTTP server to periodically poll the upper application and verify if the request data processing has finished. If the Poll feature is not required, this field SHOULD be set as DEF_NULL. See Request Ready Poll Hook for further details.	SHOULD be a callback function pointer.
OnRespHdrTxHook	Function pointer	Configure response header field transmit hook function. Before an HTTP response message is sent, a hook function is called allowing to add header field(s) to the message before it is sent. If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See Add Response Header Field for further details.	SHOULD be a callback function pointer
OnRespTokenHook	Function pointer	Configure response dynamic token replacement hook function . The hook function is called by the HTTP server when a token is found. Basically, the callback function must filled a buffer with the value to be sent instead of the token. If the header feature is not enabled, this field is not used and can be set as DEF_NULL. See Get Token Value for further information.	SHOULD be a callback function pointer.
OnRespChunkHook	Function Pointer	Configure response chunked data hook function. The hook function must be set up when the application needs to send data in chunked transfer encoding. In that case, the HTTP server core will called the hook when the response body is being built. If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See On Response Chunk Hook for further details.	SHOULD be a callback function pointer
OnTransCompleteHook	Function Pointer	Configure HTTP Transaction complete hook function. This hook function is called after a HTTP transaction has been completed. When the persistent connection mode is enabled, it is possible that the application needs to free some memory objects related to a transaction and this hook function is there for that. If the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See On Transaction Complete Hook for further details.	SHOULD be a callback function pointer
OnErrHook	Function pointer	Configure error hook function. When an internal error occurred during the processing of a transaction an hook function can be called to change the behavior such as the status code and the page returned. I f the hook is not required by the upper application, it can be set as DEF_NULL and no function will be called. See Connection Error for further details.	SHOULD be a callback function pointer
OnErrFileGetHook	Function pointer	Configure Get error file hook function. Get error file hook can be called every time an error has occurred when processing a transaction, i.e. status code is not equal to 'OK'. This function can set the web page that should be transmit instead of the default error page defined in http-s_cfg.h. If set to DEF_NULL the default error page will be used for every error. See Get Error Document for further details.	SHOULD be a callback function pointer
OnConnCloseHook	Function pointer	Configure Connection close hook function. Once a connection is closed a hook function can be called to let know the upper application that a connection is not yet active. This hook function could be used to free some previously allocated memory.If the hook is not required by the upper application. It can be set as DEF_NULL and no function will be called. See Connection Close for further details.	SHOULD be a callback function pointer