iot_https_client.h File Reference

User-facing functions of the FreeRTOS HTTPS Client library. More...

#include "iot_config.h"
#include "types/iot_https_types.h"

Go to the source code of this file.

Functions
IotHttpsReturnCode_t	IotHttpsClient_Init (void)
	One-time initialization of the IoT HTTPS Client library. More...
void	IotHttpsClient_Cleanup (void)
	One time clean up of the IoT HTTPS Client library. More...
IotHttpsReturnCode_t	IotHttpsClient_Connect (IotHttpsConnectionHandle_t *pConnHandle, IotHttpsConnectionInfo_t *pConnInfo)
	Explicitly connect to the HTTPS server given the connection configuration pConnConfig. More...
IotHttpsReturnCode_t	IotHttpsClient_Disconnect (IotHttpsConnectionHandle_t connHandle)
	Disconnect from the HTTPS server given the connection handle connHandle. More...
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 buffer. More...
IotHttpsReturnCode_t	IotHttpsClient_AddHeader (IotHttpsRequestHandle_t reqHandle, char *pName, uint32_t nameLen, char *pValue, uint32_t valueLen)
	Add a header to the current HTTPS request represented by reqHandle. More...
IotHttpsReturnCode_t	IotHttpsClient_WriteRequestBody (IotHttpsRequestHandle_t reqHandle, uint8_t *pBuf, uint32_t len, int isComplete)
	Writes the request body to the network for the request represented by reqHandle. More...
IotHttpsReturnCode_t	IotHttpsClient_SendSync (IotHttpsConnectionHandle_t connHandle, IotHttpsRequestHandle_t reqHandle, IotHttpsResponseHandle_t *pRespHandle, IotHttpsResponseInfo_t *pRespInfo, uint32_t timeoutMs)
	Synchronous send of the HTTPS request. More...
IotHttpsReturnCode_t	IotHttpsClient_SendAsync (IotHttpsConnectionHandle_t connHandle, IotHttpsRequestHandle_t reqHandle, IotHttpsResponseHandle_t *pRespHandle, IotHttpsResponseInfo_t *pRespInfo)
	Asynchronous send of the the HTTPS request. More...
IotHttpsReturnCode_t	IotHttpsClient_CancelRequestAsync (IotHttpsRequestHandle_t reqHandle)
	Cancel an Asynchronous request. More...
IotHttpsReturnCode_t	IotHttpsClient_CancelResponseAsync (IotHttpsResponseHandle_t respHandle)
	Cancel an Asynchronous response. More...
IotHttpsReturnCode_t	IotHttpsClient_ReadResponseStatus (IotHttpsResponseHandle_t respHandle, uint16_t *pStatus)
	Retrieve the HTTPS response status. More...
IotHttpsReturnCode_t	IotHttpsClient_ReadContentLength (IotHttpsResponseHandle_t respHandle, uint32_t *pContentLength)
	Retrieve the HTTPS response content length. More...
IotHttpsReturnCode_t	IotHttpsClient_ReadHeader (IotHttpsResponseHandle_t respHandle, char *pName, uint32_t nameLen, char *pValue, uint32_t valueLen)
	Retrieve the header of interest from the response represented by respHandle. More...
IotHttpsReturnCode_t	IotHttpsClient_ReadResponseBody (IotHttpsResponseHandle_t respHandle, uint8_t *pBuf, uint32_t *pLen)
	Read the HTTPS response body from the network. More...

Detailed Description

User-facing functions of the FreeRTOS HTTPS Client library.

Function Documentation

IotHttpsClient_Init()

IotHttpsReturnCode_t IotHttpsClient_Init

(

void

)

One-time initialization of the IoT HTTPS Client library.

This must be called once before calling any API.

Warning

No thread safety guarantees are provided for this function.

Returns

One of the following:

• IOT_HTTPS_OK if the HTTPS library is successfully initialized.

See also

IotHttpsClient_Cleanup

IotHttpsClient_Cleanup()

void IotHttpsClient_Cleanup

(

void

)

One time clean up of the IoT HTTPS Client library.

This function frees resources taken in in IotHttpsClient_Init. It should be called after all HTTPS Connections have been close. HTTPS Connections are represented by IotHttpsConnectionHandle_t and returned by IotHttpsClient_Connect. After this function returns IotHttpsClient_Init must be called again to use this library.

Warning

No thread safety guarantees are provided for this function.

IotHttpsClient_Connect()

IotHttpsReturnCode_t IotHttpsClient_Connect	(	IotHttpsConnectionHandle_t *	pConnHandle,
		IotHttpsConnectionInfo_t *	pConnInfo
	)

Explicitly connect to the HTTPS server given the connection configuration pConnConfig.

This routine blocks until the connection is complete.

This function opens a new HTTPS connection with the server specified in IotHttpsConnectionInfo_t.pAddress. The connection is established by default on top of TLS over TCP. If the application wants to connect over TCP only, then it must add the IOT_HTTPS_IS_NON_TLS_FLAG to IotHttpsConnectionInfo_t.flags. This is done at the application's own risk.

When the the last HTTP request sent on the connection is specified as persistent and we want to close the connection, IotHttpsClient_Disconnect must always be called on the valid IotHttpsConnectionHandle_t. For more information about persistent HTTP connections please see IotHttpsRequestInfo_t.isNonPersistent.

If the application receives a IOT_HTTPS_NETWORK_ERROR from IotHttpsClient_SendSync or IotHttpsClient_SendAsync, on a persistent request, then the connection will be closed. The application can call this this function again to reestablish the connection.

If pConnHandle passed in is valid and represents a previously opened connection, this function will disconnect, then reconnect. Before calling this function make sure that all outstanding requests on the connection have completed. Outstanding requests are completed when IotHttpsClient_SendSync has returned or when IotHttpsClientCallbacks_t.responseCompleteCallback has been invoked for requests scheduled with IotHttpsClient_SendAsync.

Keep in mind that many HTTP servers will close a connection, if it does not receive any requests, after a certain amount of time. Many web servers may close the connection after 30-60 seconds. The state of pConnHandle will still be in a connected state if this happens. If the server closed the connection, then the next request on the connection will fail to send with a network error and the connection will move to a closed state.

Also keep in mind that some HTTP servers do not accept persistent requests. Some HTTP servers will ignore that the request contains the "Connection: keep-alive" header and close the connection immediately after sending the response. If this happens, then the next request on the connection will fail to send with a network error and the connection will close.

To know if the connection was closed by the server, debug logging can be turned on to view the network error code received. Debug logging is configured when IOT_LOG_LEVEL_HTTPS is set to IOT_LOG_DEBUG in iot_config.h.

IotHttpsConnectionInfo_t.userBuffer is used to store the internal context and therefore, multiple threads calling this function simultaneously must ensure to use different IotHttpsConnectionInfo_t objects.

See connectionUserBufferMinimumSize for information about the user buffer configured in IotHttpsConnectionInfo_t.userBuffer needed to create a valid connection handle.

Parameters

[out]	pConnHandle	- Handle returned representing the open connection. NULL if the function failed.
[in]	pConnInfo	- Configurations for the HTTPS connection.

Returns

One of the following:

• IOT_HTTPS_OK if the connection was successful.
• IOT_HTTPS_CONNECTION_ERROR if the connection failed.
• IOT_HTTPS_INVALID_PARAMETER if NULL parameters were passed in.
• IOT_HTTPS_INTERNAL_ERROR if there was an error creating resources for the connection context.

Example

// An initialized network interface.
IotNetworkInterface_t* pNetworkInterface;
 
// Parameters to HTTPS Client connect.
IotHttpsConnectionInfo_t connInfo = IOT_HTTPS_CONNECTION_INFO_INITIALIZER;
IotHttpsConnectionHandle_t connHandle = IOT_HTTPS_CONNECTION_HANDLE_INITIALIZER;
uint8_t* pConnUserBuffer = (uint8_t*)malloc(connectionUserBufferMinimumSize);
 
// Set the connection configuration information.
connInfo.pAddress = "www.amazon.com";
connInfo.addressLen = strlen("www.amazon.com");
connInfo.port = 443;
connInfo.flags = 0;
connInfo.pAlpnProtocols = "alpnproto0,alpnproto1"
connInfo.pCaCert = HTTPS_TRUSTED_ROOT_CA; // defined elsewhere
connInfo.caCertLen = sizeof( HTTPS_TRUSTED_ROOT_CA );
connInfo.userBuffer.pBuffer = pConnUserBuffer;
connInfo.userBuffer.bufferLen = connectionUserBufferMinimumSize;
connInfo.pClientCert = TLS_CLIENT_CERT;
connInfo.clientCertLen = sizeof( TLS_CLIENT_CERT );
connInfo.pPrivateKey = TLS_CLIENT_PRIV_KEY;
connInfo.privateKeyLen = sizeof( TLS_CLIENT_PRIV_KEY );
connInfo.pNetworkInterface = pNetworkInterface;
 
IotHttpsReturnCode_t returnCode = IotHttpsClient_Connect(&connHandle, &connInfo);
if( returnCode == IOT_HTTPS_OK )
{
     // Do something with the HTTPS connection...
 
     // Clean up and close the HTTPS connection once it's no longer needed.
     IotHttpsClient_Disconnect(connHandle);
}

IotHttpsClient_Disconnect()

IotHttpsReturnCode_t IotHttpsClient_Disconnect

(

IotHttpsConnectionHandle_t

connHandle

)

Disconnect from the HTTPS server given the connection handle connHandle.

This routine blocks until the disconnect is complete. If the connection handle is not valid, the behavior is undefined. If the connection handle is already disconnected then this routine will return IOT_HTTPS_OK.

When the HTTP request is specified as persistent and we want to close the connection, this API must always be called on the valid IotHttpsConnectionHandle_t. For more information about persistent HTTP connections please see IotHttpsRequestInfo_t.isNonPersistent.

When the HTTP request is specified as non-persistent, by setting IotHttpsRequestInfo_t.isNonPersistent to true, then this function will be called automatically on the valid IotHttpsConnectionHandle_t after receiving the response. There is no need to call this function in case of a non-persistent request.

This will put the internal connection state in IotHttpsConnectionHandle_t to disconnected.

If the application receives a IOT_HTTPS_NETWORK_ERROR from IotHttpsClient_SendSync or IotHttpsClient_SendAsync, on a persistent request, that does not always mean the connection has been disconnected. This function MUST be called to close the connection and clean up connection resources taken by IotHttpsConnectionHandle_t.

This function will cancel all pending requests on the connection. If a request currently being sent on the connection, then this function will disconnect the connection, but it will not free network connection resource and will return with IOT_HTTPS_BUSY. The application may call this function again later to try again.

Multiple threads must not call this function for the same IotHttpsConnectionHandle_t. Multiple threads can call this function for different IotHttpsConnectionHandle_t. Make sure that all request/responses have finished on the connection before calling this API. Outstanding requests are completed when IotHttpsClient_SendSync has returned or when IotHttpsClientCallbacks_t.responseCompleteCallback has been invoked for requests scheduled with IotHttpsClient_SendAsync.

Parameters

[in]

connHandle

- Valid handle representing an open connection.

Returns

One of the following:

• IOT_HTTPS_OK if the disconnect was successful
• IOT_HTTPS_INVALID_PARAMETER if NULL parameters were passed in.
• IOT_HTTPS_BUSY if the connection is in use and cannot be destroyed.

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 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:

• 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.
}

IotHttpsClient_AddHeader()

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

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

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.

IotHttpsClient_WriteRequestBody()

IotHttpsReturnCode_t IotHttpsClient_WriteRequestBody	(	IotHttpsRequestHandle_t	reqHandle,
		uint8_t *	pBuf,
		uint32_t	len,
		int	isComplete
	)

Writes the request body to the network for the request represented by reqHandle.

This function is intended to be used by an asynchronous request. It must be called within the IotHttpsClientCallbacks_t.writeCallback.

In HTTP/1.1 the headers are sent on the network first before any body can be sent. The auto-generated header Content-Length is taken from the len parameter and sent first before the data in parameter pBuf is sent. This library does not support Transfer-Encoding: chunked or other requests where the Content-Length is unknown, so this function cannot be called more than once in IotHttpsClientCallbacks_t.writeCallback for an HTTP/1.1 request.

isComplete must always be set to 1 in this current version of the HTTPS client library.

If there are network errors in sending the HTTP headers, then the IotHttpsClientCallbacks_t.errorCallback will be invoked following a return from the IotHttpsClientCallbacks_t.writeCallback.

Example Asynchronous Code

void applicationDefined_writeCallback(void * pPrivData, IotHttpsRequestHandle_t reqHandle)
{
     ...
     char * writeData[1024];
     IotHttpsClient_WriteRequestBody(reqHandle, writeData, 1024, 1);
     ...
}

Parameters

[in]	reqHandle	- identifier of the connection.
[in]	pBuf	- client write data buffer pointer.
[in]	len	- length of data to write.
[in]	isComplete	- This parameter parameter must be set to 1.

Returns

one of the following:

• IOT_HTTPS_OK if write successfully, failure code otherwise.
• IOT_HTTPS_MESSAGE_FINISHED if this function is called a second time with the same reqHandle.
• IOT_HTTPS_NOT_SUPPORTED if isComplete is set to 0.
• IOT_HTTPS_INVALID_PARAMETER if this API is used for a synchronous request.
• IOT_HTTPS_NETWORK_ERROR if there was an error sending the headers or body on the network.
• Please see IotHttpsReturnCode_t for other failure codes.

IotHttpsClient_SendSync()

IotHttpsReturnCode_t IotHttpsClient_SendSync	(	IotHttpsConnectionHandle_t	connHandle,
		IotHttpsRequestHandle_t	reqHandle,
		IotHttpsResponseHandle_t *	pRespHandle,
		IotHttpsResponseInfo_t *	pRespInfo,
		uint32_t	timeoutMs
	)

Synchronous send of the HTTPS request.

This function blocks waiting for the entirety of sending the request and receiving the response.

If IotHttpsRequestInfo_t.isNonPersistent is set to true, then the connection will disconnect, close, and clean all taken resources automatically after receiving the first response.

See connectionUserBufferMinimumSize for information about the user buffer configured in IotHttpsConnectionInfo_t.userBuffer needed to create a valid connection handle.

To retrieve the response body applications must directly refer IotHttpsSyncInfo_t.pBody configured in IotHttpsRequestInfo_t.u.

If the response body does not fit in the configured IotHttpsSyncInfo_t.pBody, then this function will return with error IOT_HTTPS_MESSAGE_TOO_LARGE. To avoid this issue, the application needs to determine beforehand how large the file to download is. This can be done with a HEAD request first, then extracting the "Content-Length" with IotHttpsClient_ReadContentLength. This could also be done with a GET request with the header "Range: bytes=0-0", then extracting the "Content-Range" with IotHttpsClient_ReadHeader. Keep in mind that not all HTTP servers support Partial Content responses.

Once a the file size is known, the application can initialize the request with a large enough buffer or the application can make a partial content request with the header "Range: bytes=N-M", where N is the starting byte requested and M is the ending byte requested.

The response headers as received from the network will be stored in the header buffer space in IotHttpsResponseInfo_t.userBuffer. If the configured IotHttpsResponseInfo_t.userBuffer is too small to fit the headers received, then headers that don't fit will be thrown away. Please see responseUserBufferMinimumSize for information about sizing the IotHttpsResponseInfo_t.userBuffer. To receive feedback on headers discarded, debug logging must be turned on in iot_config.h by setting IOT_LOG_LEVEL_HTTPS to IOT_LOG_DEBUG.

Multiple threads must not call this function for the same IotHttpsRequestHandle_t. Multiple threads can call this function for a different IotHttpsRequestHandle_t, even on the same IotHttpsConnectionHandle_t. An application must wait util a request is fully sent, before scheduling it again. A request is fully sent when this function has returned.

Parameters

[in]	connHandle	- Handle from an HTTPS connection created with IotHttpsClient_Connect.
[in]	reqHandle	- Handle from a request created with IotHttpsClient_InitializeRequest.
[out]	pRespHandle	- HTTPS response handle resulting from a successful send and receive.
[in]	pRespInfo	- HTTP response configuration information.
[in]	timeoutMs	- Timeout waiting for the sync request to finish. Set this to 0 to wait forever.

Returns

One of the following:

• IOT_HTTPS_OK if the request was sent and the response was received successfully.
• IOT_HTTPS_MESSAGE_TOO_LARGE if the response cannot fit in the configured struct IotHttpsRequestHandle.userBuffer.pBuffer and struct IotHttpsRequestHandle.u.pSyncInfo.pRespData.
• IOT_HTTPS_CONNECTION_ERROR if the connection failed.
• IOT_HTTPS_INVALID_PARAMETER if there are NULL parameters or the request is asynchronous.
• IOT_HTTPS_NETWORK_ERROR if there was an error sending the data on the network.
• IOT_HTTPS_PARSING_ERROR if there was an error parsing the HTTP response.
• IOT_HTTPS_TIMEOUT_ERROR if the timeoutMs is reached when waiting for a response to the request.

IotHttpsClient_SendAsync()

IotHttpsReturnCode_t IotHttpsClient_SendAsync	(	IotHttpsConnectionHandle_t	connHandle,
		IotHttpsRequestHandle_t	reqHandle,
		IotHttpsResponseHandle_t *	pRespHandle,
		IotHttpsResponseInfo_t *	pRespInfo
	)

Asynchronous send of the the HTTPS request.

This function will invoke, as needed, each of the non-NULL callbacks configured in IotHttpsAsyncInfo_t.callbacks when the scheduled asynchronous request is progress. Please see IotHttpsClientCallbacks_t for information on each of the callbacks.

After this API is executed, the scheduled async response will store the response headers as received from the network, in the header buffer space configured in IotHttpsResponseInfo_t.userBuffer. If the configured IotHttpsResponseInfo_t.userBuffer is too small to fit the headers received, then headers that don't fit will be thrown away. Please see responseUserBufferMinimumSize for information about sizing the IotHttpsResponseInfo_t.userBuffer.

If IotHttpsRequestInfo_t.isNonPersistent is set to true, then the connection will disconnect, close, and clean all taken resources automatically after receiving the first response.

See connectionUserBufferMinimumSize for information about the user buffer configured in IotHttpsConnectionInfo_t.userBuffer needed to create a valid connection handle.

A IotHttpsRequestHandle_t cannot be schedule again or reused until the request has finished sending. The request has safely finished sending once IotHttpsClientCallbacks_t.readReadyCallback is invoked. After the IotHttpsClientCallbacks_t.readReadyCallback is invoked the IotHttpsRequestInfo_t.userBuffer can freed, modified, or reused.

Parameters

[in]	connHandle	- Handle from an HTTPS connection.
[in]	reqHandle	- Handle from a request created with IotHttpsClient_initialize_request.
[out]	pRespHandle	- HTTPS response handle.
[in]	pRespInfo	- HTTP response configuration information.

Returns

One of the following:

• IOT_HTTPS_OK if the request was sent and the response was received successfully.
• IOT_HTTPS_MESSAGE_TOO_LARGE if the response cannot fit in the configured IotHttpsRequestHandle_t.response_message.headers and IotHttpsRequestHandle_t.response_message.body.
• IOT_HTTPS_CONNECTION_ERROR if the connection failed.
• IOT_HTTPS_FATAL if there was a grave error with the last async job finishing.
• IOT_HTTPS_ASYNC_SCHEDULING_ERROR if there was an error scheduling the asynchronous request.
• IOT_HTTPS_INTERNAL_ERROR if there was an internal error with starting an asynchronous request servicing task.
• IOT_HTTPS_INVALID_PARAMETER if there were NULL parameters or the request passed in was a synchronous type.

IotHttpsClient_CancelRequestAsync()

IotHttpsReturnCode_t IotHttpsClient_CancelRequestAsync

(

IotHttpsRequestHandle_t

reqHandle

)

Cancel an Asynchronous request.

This will stop an asynchronous request. When an asynchronous request is stopped it will not proceed to do any of the following: send headers, send body, receive headers, or receive body. This depends on where in the process the request is. For example, if the request is cancelled after sending the headers, then it will not attempt tp send the body. A cancelled return code will be returned to the application.

If this is called before the scheduled asynchronous request actually runs, then request will not be sent. If this is called during any of the asynchronous callbacks, then the library will stop processing the request when the callback returns. This is useful for any error conditions, found during the asynchronous callbacks, where the application wants to stop the rest of the request processing.

If the asynchronous request stops processing, the buffers in IotHttpsRequestInfo_t.userBuffer can be safely freed, modified, or reused, only once IotHttpsClientCallbacks_t.readReadyCallback is invoked.

Example Asynchronous Code

void _applicationDefined_appendHeaderCallback(void * pPrivData, IotHttpsRequestHandle_t reqHandle)
{
     char token[MAX_TOKEN_LENGTH] = { 0 }
     int len = MAX_TOKEN_LENGTH;
     int status = gen_auth_token(token, &len);
     if( status == GEN_TOKEN_FAIL)
     {
         IotHttpsClient_CancelRequestAsync(reqHandle);
     }
     ...
}
 
void _applicationDefined_writeCallback(void * pPrivData, IotHttpsRequestHandle_t reqHandle)
{
     if( application_data_get(writeBuffer, writeBufferLen) == GEN_TOKEN_FAIL)
     {
         IotHttpsClient_CancelRequestAsync(reqHandle);
     }
     ...
}

Parameters

[in]

reqHandle

- Request handle associated with the request.

Returns

One of the following:

• IOT_HTTPS_OK if the request was successfully cancelled.

IotHttpsClient_CancelResponseAsync()

IotHttpsReturnCode_t IotHttpsClient_CancelResponseAsync

(

IotHttpsResponseHandle_t

respHandle

)

Cancel an Asynchronous response.

This will stop an asynchronous response. When an asynchronous response is stopped it will not proceed to do any of the following: send headers, send body, receive headers, or receive body. This depends on where in the process the response is. For example, if the response is cancelled after receiving the headers, then it will not attempt tp receive the body. A cancelled return code will be returned to the application.

If this is called during ANY of the asynchronous callbacks, then the library will stop processing the response when the callback returns. This is useful for any error conditions, found during the asynchronous callbacks, where the application wants to stop the rest of the response processing.

If the asynchronous response stops processing, the buffers configured in IotHttpsResponseInfo_t.userBuffer can be freed, modified, or reused only after the IotHttpsClientCallbacks_t.responseCompleteCallback in invoked.

Example Asynchronous Code

void applicationDefined_readReadyCallback(void * pPrivData, IotHttpsResponseHandle_t respHandle, IotHttpsReturnCode_t rc, uint16_t status)
{
     ...
     if (status != IOT_HTTPS_STATUS_OK)
     {
         IotHttpsClient_CancelResponseAsync(NULL, respHandle);
     }
     ...
}

Parameters

[in]

respHandle

- Response handle associated with the response.

Returns

One of the following:

• IOT_HTTPS_OK if the response was successfully cancelled.

IotHttpsClient_ReadResponseStatus()

IotHttpsReturnCode_t IotHttpsClient_ReadResponseStatus	(	IotHttpsResponseHandle_t	respHandle,
		uint16_t *	pStatus
	)

Retrieve the HTTPS response status.

The HTTP response status code is contained in the Status-Line of the response header buffer configured in IotHttpsResponseInfo_t.userBuffer. It is the first line of a standard HTTP response message. If the response Status-Line could not fit into IotHttpsResponseInfo_t.userBuffer, then this function will return an error code. Please see responseUserBufferMinimumSize for information about sizing the IotHttpsResponseInfo_t.userBuffer.

This routine can be used for both a synchronous and asynchronous response.

Example Synchronous Code

...
IotHttpsClient_SendSync(connHandle, reqHandle, &respHandle, &respInfo, timeout);
uint16_t status = 0;
IotHttpsClient_ReadResponseStatus(respHandle, &status);
if (status != IOT_HTTPS_STATUS_OK)
{
    // Handle server response status.
}
...

For an asynchronous response the response status is the status parameter in IotHttpsClientCallbacks_t.readReadyCallback and IotHttpsClientCallbacks_t.responseCompleteCallback. The application should refer to that instead of using this function. Example Asynchronous Code

void applicationDefined_readReadyCallback(void * pPrivData, IotHttpsResponseHandle_t respHandle, IotHttpsReturnCode_t rc, uint16_t status)
{
     ...
     if (status != IOT_HTTPS_STATUS_OK)
     {
         // Handle error server response status.
     }
     ...
}

Parameters

[in]	respHandle	- Unique handle representing the HTTPS response.
[out]	pStatus	- Integer status returned by the server.

Returns

One of the following:

• IOT_HTTPS_OK if the response status was successfully read into *status.
• IOT_HTTPS_INVALID_PARAMETER for NULL parameters.
• IOT_HTTPS_NOT_FOUND if the HTTP response status was not found in the header buffer.

IotHttpsClient_ReadContentLength()

IotHttpsReturnCode_t IotHttpsClient_ReadContentLength	(	IotHttpsResponseHandle_t	respHandle,
		uint32_t *	pContentLength
	)

Retrieve the HTTPS response content length.

If the "Content-Length" header is available in IotHttpsResponseInfo_t.userBuffer, this routine extracts that value. In some cases the "Content-Length" header is not available. This could be because the server sent a multi-part encoded response (For example, "Transfer-Encoding: chunked") or the "Content-Length" header was far down in the list of response headers and could not fit into the header buffer configured in IotHttpsResponseInfo_t.userBuffer. Please see responseUserBufferMinimumSize for information about sizing the IotHttpsResponseInfo_t.userBuffer.

In the asynchronous request process, the Content-Length is not available until the IotHttpsClientCallbacks_t.readReadyCallback. Before the IotHttpsClientCallbacks_t.readReadyCallback is invoked, the headers are read into as much as can fit in in the header buffer space of IotHttpsResponseInfo_t.userBuffer. Example Asynchronous Code

void applicationDefined_readReadyCallback(void * pPrivData, IotHttpsResponseHandle_t respHandle, IotHttpsReturnCode_t rc, uint16_t status)
{
     uint8_t * readBuffer = NULL;
     uint32_t contentLength = 0;
     IotHttpsClient_ReadContentLength(respHandle, &contentLength);
     readBuffer = (uint8_t*)malloc(contentLength);
     ...
}

In a synchronous request process, the Content-Length is available after IotHttpsClient_SendSync has returned successfully. Example Synchronous Code

...
IotHttpsClient_SendSync(connHandle, reqHandle, &respHandle, &respInfo, timeout);
uint32_t contentLength = 0;
IotHttpsClient_ReadContentLength(respHandle, &contentLength);
printf("Content-Length: %u", (unsigned int)contentLength);
...

Parameters

[in]	respHandle	- Unique handle representing the HTTPS response.
[out]	pContentLength	- Integer content length from the Content-Length header from the server. If the content length is not found this will be 0.

Returns

One of the following:

• IOT_HTTPS_OK if the response body Content-Length was successfully read into contentLength.
• IOT_HTTPS_NOT_FOUND if the Content-Length header was not found in the header buffer.
• IOT_HTTPS_INVALID_PARAMETER if NULL parameters are passed in.

IotHttpsClient_ReadHeader()

IotHttpsReturnCode_t IotHttpsClient_ReadHeader	(	IotHttpsResponseHandle_t	respHandle,
		char *	pName,
		uint32_t	nameLen,
		char *	pValue,
		uint32_t	valueLen
	)

Retrieve the header of interest from the response represented by respHandle.

The response headers as received from the network will be stored in the header buffer space in IotHttpsResponseInfo_t.userBuffer. If the configured IotHttpsResponseInfo_t.userBuffer is too small to fit the headers received, then headers that don't fit will be thrown away. Please see responseUserBufferMinimumSize for information about sizing the IotHttpsResponseInfo_t.userBuffer.

This routine parses the formatted HTTPS header lines in the header buffer for the header field name specified. If the header is not available, then IOT_HTTPS_NOT_FOUND is returned.

For an asynchronous response, this routine is to be called during the IotHttpsClientCallbacks_t.readReadyCallback. Before the IotHttpsClientCallbacks_t.readReadyCallback is invoked, the headers are read into as much as can fit in in the header buffer space of IotHttpsResponseInfo_t.userBuffer. Example Asynchronous Code

void applicationDefined_readReadyCallback(void * pPrivData, IotHttpsResponseHandle_t respHandle, IotHttpsReturnCode_t rc, uint16_t status)
{
     ...
     char valueBuf[64];
     const char contentTypeName[] = "Content-Type";
     uint32_t contentTypeNmeLength = strlen(contentTypeName);
     IotHttpsClient_ReadHeader(respHandle, contentTypeName, contentTypeNameLength, valueBuf, sizeof(valueBuf));
     ...
}

For a syncrhonous response, this routine is to be called after IotHttpsClient_SendSync has returned successfully. Example Synchronous Code

...
IotHttpsClient_SendSync(&connHandle, reqHandle, &respHandle, &respInfo, timeout);
char valueBuf[10];
const char contentTypeName[] = "Content-Type";
uint32_t contentTypeNmeLength = strlen(contentTypeName);
IotHttpsClient_ReadHeader(respHandle, contentTypeName, contentTypeNmeLength, valueBuf, sizeof(valueBuf));
uint32_t length = strtoul(valueBuf, NULL, 10);
...

Parameters

[in]	respHandle	- Unique handle representing the HTTPS response.
[in]	pName	- HTTPS Header field name we want the value of. This must be NULL terminated.
[in]	nameLen	- The length of the name string.
[out]	pValue	- Buffer to hold the HTTPS field's value. The returned value will be NULL terminated and therfore the buffer must be large enough to hold the terminating NULL character.
[in]	valueLen	- The length of the value buffer.

Returns

One of the following:

• IOT_HTTPS_OK if the header's corresponding value was read into *pValue.
• IOT_HTTPS_NOT_FOUND if the header value was not found.
• IOT_HTTPS_INVALID_PARAMETER if the respHandle is not valid, there is no response saved or the handle does not exist.
• IOT_HTTPS_INSUFFICIENT_MEMORY if the value is too large to fit into *pValue.

IotHttpsClient_ReadResponseBody()

IotHttpsReturnCode_t IotHttpsClient_ReadResponseBody	(	IotHttpsResponseHandle_t	respHandle,
		uint8_t *	pBuf,
		uint32_t *	pLen
	)

Read the HTTPS response body from the network.

This is intended to be used with an asynchronous response, this is to be invoked during the IotHttpsClientCallbacks_t.readReadyCallback to read data directly from the network into pBuf. Example Asynchronous Code

void applicationDefined_readReadyCallback(void * pPrivData, IotHttpsRequestHandle_t handle, IotHttpsReturnCode_t rc, uint16_t status)
{
     ...
     char * myBuf = STORE_ADDRESS;
     uint32_t len = STORE_READ_SIZE;
     IotHttpsClient_ReadResponseBody(handle, myBuf, &len);
     ...
}

For a syncrhonous response, to retrieve the response body applications must directly refer to the memory configured to receive the response body: IotHttpsSyncInfo_t.pBody in IotHttpsResponseInfo_t.pSyncInfo. Otherwise this function will return an IOT_HTTPS_INVALID_PARAMETER error code. This function is intended to read the response entity body from the network and the synchronous response process handles all of that in IotHttpsClient_SendSync.

Parameters

[in]	respHandle	- Unique handle representing the HTTPS response.
[out]	pBuf	- Pointer to the response body memory location. This is not a char* because the body may have binary data.
[in,out]	pLen	- The length of the response to read. This should not exceed the size of the buffer that we are reading into. This will be replace with the amount of data read upon return.

Returns

One of the following:

• IOT_HTTPS_OK if the response body was successfully retrieved.
• IOT_HTTPS_INVALID_PARAMETER if there are NULL parameters or if the response is a synchronous type.
• IOT_HTTPS_NETWORK_ERROR if there was an error sending the data on the network.
• IOT_HTTPS_PARSING_ERROR if there was an error parsing the HTTP response.