The Header Field feature allows the µC/HTTP-server to receive and transmit additional HTTP headers than the one already processed internally by the HTTP server core.
The below header fields are already taken care of by the µC/HTTP-server stack and must therefore not be added or processed by the application:
- Host
- Content-Type
- Content-Length
- Transfer-Encoding
- Connection
- Location
See section HTTP HTTP Header Fields Recognized for a list of all the header field recognized by the µC/HTTP-server product.
To learn more on the HTTP header concepts, see section Headers.
Configuration
For the HTTP server to support processing of additional headers, two types of configuration must be set up: the compile-time and the run-time configuration. Also, some hook functions must be defined to allow the upper application to use this feature.
The Header Field feature is divided in two independent parts: the reception and the transmission. Each part has its own configuration as it will be shown below.
The reception is associated with HTTP header fields received in HTTP requests and the transmission is associated with HTTP header fields to send in HTTP responses.
Compile-time Configuration
Two configuration macros are available for the Header Field feature, one for the reception and one for the transmission: HTTPs_CFG_HDR_RX_EN and HTTPs_CFG_HDR_TX_EN. Each can be enabled and disabled separately.
See section Header Field Configuration for more details.
Run-time Configuration
The run-time configuration for the Header Field feature has defined two structure: HTTPs_HDR_RX_CFG and HTTPs_HDR_TX_CFG. If your application wishes to save headers received in HTTP requests, it must declare an HTTPs_HDR_RX_CFG object and include a pointer to this object in the HTTP server instance configuration HTTPs_CFG object where the HdrRxCfgPtr parameter is defined. The same must be done with an HTTPs_HDR_TX_CFG object if your application wishes to add headers to HTTP responses. The HdrTxCfgPtr parameter of the HTTPs_CFG object must therefore be defined.
See section HTTP Header Configuration for additional details.
Hook Function
The general HTTP Server Instance configuration structure (HTTPs_CFG) contains a pointer to an HTTPs_HOOK_CFG object. This object indexes all the hook functions required by your application.
For additional details on the configuration of hook functions, see section Hook Configuration.
To visualize when each hook function is called by the HTTP server core, see section Hook Functions.
In reception, the hook OnReqHdrRxHook can be used to set which header field the application wishes to keep.
In transmission, the hook OnRespHdrTxHook can be used to add header field to the header list that the server will used to construct the HTTP response to send.
Usage
Reception
Once a HTTP request is received by the HTTP server, the server will call, if defined, the OnReqHdrRxHook for each header fields received. The upper application must implement this hook to return status "YES" when the header field must be saved and "NO" otherwise.
Transmission
When the server is constructing an HTTP response to send, it will call the hook function OnRespHdrTxHook when adding headers to the response. In this hook, the upper application can add header fields to the HTTP headers list by using the API function HTTPs_RespHdrGet. This function will found an Header Field block available in the pool and add it to the list. The upper application just need to fill the block fields afterwards.