Control Structures

Many hook functions receive pointers to control structures which can be used by upper layer to change the behavior of the server and for debugging purpose.

HTTPs_INSTANCE

The instance control structure should be only used for debugging purpose. The upper application MUST not modify this structure, it must only read data except for the DataPtr field. Here is a list of variables of interest:

HTTPs_CONN

The connection control structure may be used to change the behavior on a particular HTTP transaction occurring on a connection and for connection processing and debugging purpose.

Fields to Read

Those are the relevant connection fields that can be read inside the hook functions by the application. They can, among others things, be used to demultiplex a connection:

ClientAddr

Contains the IP address and port of the client.

SockID

Contains the socket ID used to receive and transmit data.

Method

This field contains the method of the request received:

HTTP_METHOD_GET
HTTP_METHOD_POST
HTTP_METHOD_HEAD
HTTP_METHOD_PUT
HTTP_METHOD_DELETE

ReqContentType

If the HTTP request has a body, this field will contains the content type of the body.

QueryStrListPtr

This field is the head of the list of key-value pairs received inside a Query String if one was present after the request URL.

HdrListPtr

This field is the head of the list of header fields received inside the HTTP request.

FormDataListPtr

This field is the head of the list of key-value pairs received in a form inside a POST request.

NULL, if no key-value pairs was received.

Fields to Read/Write

The following is a list of field that can be modified via some hook functions:

StatusCode

HTTP status code of the connection. When change the web server transmit the response (status code and status phrase) following the status code of the connection. See section HTTP Status Codes Recognized for a list of Status Code recognized by the µC/HTTP-server stack.

PathPtr

At the request level, this field contains the path to the resource received in the HTTP request URL. It can be used for comparison inside hooks to do some operations according to the URL received.

At the response level, if the resource is a file (see RespBodyDataType field), this field will be used to fetch the file from the File System whose location is indicated by the PathPtr. This file will then be copied in the response body. This field will also be used to construct the location header if necessary.

Before the response level, the upper application can modify the PathPtr contents via the hook functions if its needs to modify the file to send in the response. If the resource to send back in the response is not a file, the field can still be used to set the path of the resource in case a location header needs to be sent also.

The pointer MUST NOT be change at any moments. Only the buffer contents pointed by PathPtr can be modified to write a new string.

DataPtr

In the case where the resource to send in the response is a file contain in a FS (RespBodyDataType == FILE), this field is used by the server to store the file data to transmit. Therefore, It MUST NOT be modified by the application.

In the case where the resource to send in the response is static data located in memory (RespBodyDataType == STATIC DATA), this field MUST be set by the application via the hook functions. It should be set the point to the data to send. 

In the case where the resource to send is also data located in memory (RespBodyDataType == STATIC DATA) but that must be sent in Chunked Transfer Encoding with the Chunk Hook, the DataPtr MUST be be set to NULL by the application via the hooks functions. That way the Chunk Hook will be called later.

DataLen

In the case where the resource to send is a file contain in a FS  (RespBodyDataType == FILE), this field will be used by the server to store the length of the file. Therefore, it MUST NOT be modified by the application via the hook functions. 

In the case where the resource to send is static data located in memory (RespBodyDataType == STATIC DATA) and that the DataPtr was set to the memory address of the data, the DataLen field MUST be set to the data length by the application.

When transferring data via the Chunk Hook because the DataPtr was previously set to NULL, the DataLen field is not taken into account by the server.

RespContentType

This field will contains the content type of the response body.

If a file (that is in a File System) is to be sent and the RespContentType field is set to "Unknown", the server will parse the file extension to set the Content Type. Therefore, the application could set the field via the hook functions, but doesn't need to in the case of a file.

If static data is to be sent (RespBodyDataType == STATIC DATA), this field MUST absolutely be set by the application via the hook functions.

RespBodyDataType

This field set the type of data of the response body. Three types are available:

• • HTTPs_BODY_DATA_TYPE_FILE:               When data body is from a file that was store in a File System.
  • HTTPs_BODY_DATA_TYPE_STATIC_DATA: When data body is from memory allocation or is sent via Chunk Hook.
• • HTTPs_BODY_DATA_TYPE_NONE:               When no body will be sent with the response.

By default this field is set to HTTPs_BODY_DATA_TYPE_FILE for GET and HEAD methods and to HTTPs_BODY_DATA_TYPE_NONE for POST, DELETE and PUT method. The field can be modified by the application via the hook functions.

ConnDataPtr

This parameter is available for the upper application to store memory location for connection processing across all hook functions.