IotHttpsClient_AddHeader

Add a header to the current HTTPS request represented by reqHandle.

IotHttpsReturnCode_t IotHttpsClient_AddHeader( IotHttpsRequestHandle_t reqHandle,
                                               char * pName,
                                               uint32_t nameLen,
                                               char * pValue,
                                               uint32_t valueLen );

The header line is appended to the request header buffer space in IotHttpsRequestInfo_t.userBuffer. Please see requestUserBufferMinimumSize for information about sizing the IotHttpsRequestInfo_t.userBuffer so that this function does not fail.

Header lines are appended in the following format:

header_field_name: header_value\r\n"

Example:

Range: bytes=1024-2047\r\n

The last header line must be followed by a "\r\n" to separate the last header line from the entity body. These 2 characters are accounted for in requestUserBufferMinimumSize.

The remaining length, after the header is added, is printed to the system configured standard debug output when IOT_LOG_LEVEL_HTTPS is set to IOT_LOG_DEBUG in iot_config.h.

For an asynchronous request, this function can be invoked before the request is sent with IotHttpsClient_SendAsync, or during IotHttpsClientCallbacks_t.appendHeaderCallback. It is recommended to invoke this function in IotHttpsClientCallbacks_t.appendHeaderCallback.

Asynchronous Example

void _applicationDefined_appendHeaderCallback(void * pPrivData, IotHttpsRequestHandle_t reqHandle)
{
     ...
     char date_in_iso8601[17] = { 0 };
     GET_DATE_IN_ISO8601(date_in_iso8601);
     const char amz_date_header[] = "x-amz-date";
     uint32_t amz_date_header_length = strlen(amz_date_header);
     IotHttpsClient_AddHeader(reqHandle, amz_date_header, amz_date_header_length, date_in_iso8601, strlen(date_in_iso8601));
     ...
}

For a synchronous request, if extra headers are desired to be added, this function must be invoked before IotHttpsClient_SendSync. Synchronous Example

...
char date_in_iso8601[17] = { 0 };
GET_DATE_IN_ISO8601(date_in_iso8601);
const char amz_date_header[] = "x-amz-date";
uint32_t amz_date_header_length = strlen(amz_date_header);
IotHttpsClient_AddHeader(reqHandle, amz_date_header, amz_date_header_length, date_in_iso8601, strlen(date_in_iso8601));
...
IotHttpsClient_SendSync(connHandle, reqHandle, &respHandle, &respInfo, timeout);
...

The following header fields are automatically added to the request header buffer and must NOT be added again with this routine:

• Connection: - This header is added to the request when the headers are being sent on the network.
• User-agent: - This header is added during IotHttpsClient_InitializeRequest
• Host: - This header is added during IotHttpsClient_InitializeRequest
• Content-Length: - This header is added to the request when the headers are being sent on the network.

The reqHandle is not thread safe. If two threads have the same reqHandle and attempt to add headers at the same time, garbage strings may be written to the reqHandle.

Parameters

[in]	reqHandle	- HTTPS request to write the header line to.
[in]	pName	- String header field name to write.
[in]	nameLen	- The length of the header name to write.
[in]	pValue	- https header value buffer pointer. Do not include token name.
[in]	valueLen	- length of header value to write.

Returns

One of the following:

• IOT_HTTPS_OK if the header line was successfully added to the header space in IotHttpsRequestInfo_t.userBuffer.
• IOT_HTTPS_INSUFFICIENT_MEMORY if the header line cannot fit into the header buffer.
• IOT_HTTPS_INVALID_PARAMETER for NULL parameters or if an attempt to add automatically added headers is made.