IotHttpsClient_InitializeRequest

Initializes the request by adding a formatted Request-Line to the start of HTTPS request header buffer.

IotHttpsReturnCode_t IotHttpsClient_InitializeRequest( IotHttpsRequestHandle_t * pReqHandle,
                                                       IotHttpsRequestInfo_t * pReqInfo );

This function will initialize the HTTP request context by setting where to write the next headers to the start of the configured header buffer in IotHttpsRequestInfo_t.userBuffer.

The Request-Line will be added to the start of the headers space in IotHttpsRequestInfo_t.userBuffer. The header space follows the request context in the user buffer. See requestUserBufferMinimumSize for more information on sizing the IotHttpsRequestInfo_t.userBuffer so that this function does not fail.

The Request-Line generated is of the following format:

method path version\r\n

Example:

GET /path/to/item.file?possible_query HTTP/1.1\r\n

The initial required headers are also added to the IotHttpsRequestInfo_t.userBuffer. These headers are User-Agent and Host. The User-Agent value is configured in iot_config.h using IOT_HTTPS_USER_AGENT. The Host value is the DNS resolvable server address.

Parameters

[out]	pReqHandle	- request handle representing the internal request context is returned. NULL if the function failed.
[in]	pReqInfo	- HTTPS request information.

Returns

One of the following:

• IOT_HTTPS_OK if the Request-Line was successfully added to the header space in IotHttpsRequestInfo_t.userBuffer.
• IOT_HTTPS_INSUFFICIENT_MEMORY if the Request-Line generated exceeds IotHttpsUserBuffer_t.bufferLen in IotHttpsRequestInfo_t.userBuffer.
• IOT_HTTPS_INVALID_PARAMETER for NULL parameters.
• IOT_HTTPS_INTERNAL_ERROR for library internal errors.

Example

// An initialized network interface.
IotNetworkInterface_t* pNetworkInterface;
 
// Parameters to HTTPS Client request initialization.
IotHttpsRequestInfo_t reqInfo = IOT_HTTPS_REQUEST_INFO_INITIALIZER;
IotHttpsRequestHandle_t reqHandle = IOT_HTTPS_REQUEST_HANDLE_INITIALIZER;
IotHttpsSyncInfo_t syncInfo = IOT_HTTPS_SYNC_INFO_INITIALIZER;
// Leave some room for extra headers.
uint32_t userBufferSize = requestUserBufferMinimumSize + 256;
uint8_t* pRequestUserBuffer = (uint8_t*)malloc(userBufferSize);
 
// Set the synchronous information.
syncInfo.pBody = PREDEFINED_BODY_BUFFER;
syncInfo.bodyLen = PREDEFINED_BODY_BUFFER_LEN;
 
// Set the request configuration information.
reqInfo.pPath = "/path_to_item?query_maybe";
reqInfo.pPathLen = strlen("/path_to_item?query_maybe");
reqInfo.method = IOT_HTTPS_METHOD_GET;
reqInfo.pHost = "www.amazon.com";
reqInfo.hostLen = strlen("www.amazon.com");
reqInfo.isNonPersistent = false;
reqInfo.userBuffer.pBuffer = pRequestUserBuffer;
reqInfo.userBuffer.bufferLen = userBufferSize;
reqInfo.isAsync = false;
reqInfo.pSyncInfo = &syncInfo;
 
IotHttpsReturnCode_t returnCode = IotHttpsClient_InitializeRequest(&reqHandle, &reqInfo);
if( returnCode == IOT_HTTPS_OK )
{
     // Handle the error.
}