HTTPS Client API Reference
HTTPS Client v1.0.0 library
IotHttpsClient_InitializeRequest

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

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:

Example

// An initialized network interface.
IotNetworkInterface_t* pNetworkInterface;
// Parameters to HTTPS Client request initialization.
// 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.
}
IotHttpsRequestInfo_t::pPath
const char * pPath
The absolute path to the HTTP request object.
Definition: iot_https_types.h:810
IotHttpsRequestInfo_t::userBuffer
IotHttpsUserBuffer_t userBuffer
Application owned buffer for storing the request headers and internal request context.
Definition: iot_https_types.h:854
IotHttpsSyncInfo_t
HTTPS Client synchronous request information.
Definition: iot_https_types.h:669
IotHttpsSyncInfo_t::bodyLen
uint32_t bodyLen
The length of the HTTP message body.
Definition: iot_https_types.h:684
IotHttpsRequestInfo_t::hostLen
uint32_t hostLen
Host address length.
Definition: iot_https_types.h:829
IOT_HTTPS_SYNC_INFO_INITIALIZER
#define IOT_HTTPS_SYNC_INFO_INITIALIZER
Initializer for IotHttpsSyncInfo_t.
Definition: iot_https_types.h:203
IotHttpsRequestInfo_t::method
IotHttpsMethod_t method
On of the HTTP method tokens defined in IotHttpsMethod_t.
Definition: iot_https_types.h:819
IotHttpsRequestHandle_t
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:267
IotHttpsClient_InitializeRequest
IotHttpsReturnCode_t IotHttpsClient_InitializeRequest(IotHttpsRequestHandle_t *pReqHandle, IotHttpsRequestInfo_t *pReqInfo)
Initializes the request by adding a formatted Request-Line to the start of HTTPS request header buffe...
Definition: iot_https_client.c:2703
IotHttpsUserBuffer_t::pBuffer
uint8_t * pBuffer
Application provided buffer pointer.
Definition: iot_https_types.h:653
IotHttpsSyncInfo_t::pBody
uint8_t * pBody
Definition: iot_https_types.h:683
IotHttpsRequestInfo_t::isNonPersistent
bool isNonPersistent
Flag denoting if the connection should be non-persistent.
Definition: iot_https_types.h:844
IOT_HTTPS_REQUEST_INFO_INITIALIZER
#define IOT_HTTPS_REQUEST_INFO_INITIALIZER
Initializer for IotHttpsRequestInfo_t.
Definition: iot_https_types.h:209
IotNetworkInterface_t
requestUserBufferMinimumSize
const uint32_t requestUserBufferMinimumSize
The minimum user buffer size for the HTTP request context and headers.
Definition: iot_https_client.c:106
IOT_HTTPS_OK
Returned for a successful operation.
Definition: iot_https_types.h:301
IOT_HTTPS_REQUEST_HANDLE_INITIALIZER
#define IOT_HTTPS_REQUEST_HANDLE_INITIALIZER
Initializer for IotHttpsRequestHandle_t.
Definition: iot_https_types.h:197
IotHttpsReturnCode_t
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:296
IotHttpsRequestInfo_t::isAsync
bool isAsync
Indicator if this request is sync or async.
Definition: iot_https_types.h:861
IotHttpsRequestInfo_t::pHost
const char * pHost
Host address this request is intended for, e.g., "awsamazon.com".
Definition: iot_https_types.h:828
IotHttpsRequestInfo_t::pSyncInfo
IotHttpsSyncInfo_t * pSyncInfo
Information specifically for synchronous requests.
Definition: iot_https_types.h:872
IotHttpsRequestInfo_t
HTTP request configuration.
Definition: iot_https_types.h:797
IotHttpsUserBuffer_t::bufferLen
uint32_t bufferLen
The length of the application provided buffer.
Definition: iot_https_types.h:654