FreeRTOS: HTTPS Client
HTTPS Client v1.0.0 library
Return to main page ↑
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:

Example

// An initialized network interface.
IotNetworkInterface_t* pNetworkInterface;
// Parameters to HTTPS Client connect.
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.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.
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
@ IOT_HTTPS_OK
Returned for a successful operation.
Definition: iot_https_types.h:298
struct _httpsConnection * IotHttpsConnectionHandle_t
Opaque handle of an HTTP connection.
Definition: iot_https_types.h:248
IotHttpsReturnCode_t IotHttpsClient_Connect(IotHttpsConnectionHandle_t *pConnHandle, IotHttpsConnectionInfo_t *pConnInfo)
Explicitly connect to the HTTPS server given the connection configuration pConnConfig.
Definition: iot_https_client.c:2589
IotHttpsReturnCode_t IotHttpsClient_Disconnect(IotHttpsConnectionHandle_t connHandle)
Disconnect from the HTTPS server given the connection handle connHandle.
Definition: iot_https_client.c:2629
#define IOT_HTTPS_CONNECTION_INFO_INITIALIZER
Initializer for IotHttpsConnectionInfo_t.
Definition: iot_https_types.h:202
#define IOT_HTTPS_CONNECTION_HANDLE_INITIALIZER
Initializer for IotHttpsConnectionHandle_t.
Definition: iot_https_types.h:190
const uint32_t connectionUserBufferMinimumSize
The minimum user buffer size for the HTTP connection context and headers.
Definition: iot_https_client.c:138
HTTP connection configuration.
Definition: iot_https_types.h:721
const char * pPrivateKey
Client private key store for this connection.
Definition: iot_https_types.h:754
char * pAlpnProtocols
String of all the ALPN protocols separated by commas needed for this connection.
Definition: iot_https_types.h:763
uint32_t clientCertLen
Client certificate store size.
Definition: iot_https_types.h:752
uint32_t caCertLen
Server trusted certificate store size.
Definition: iot_https_types.h:749
IotHttpsUserBuffer_t userBuffer
User buffer to store the internal connection context.
Definition: iot_https_types.h:772
uint32_t addressLen
remote address length.
Definition: iot_https_types.h:728
uint16_t port
Remote port number.
Definition: iot_https_types.h:730
uint32_t flags
Flags to configure the HTTPS connection.
Definition: iot_https_types.h:739
IOT_HTTPS_NETWORK_INTERFACE_TYPE pNetworkInterface
The IOT network abstraction interface.
Definition: iot_https_types.h:781
uint32_t privateKeyLen
Client private key store size.
Definition: iot_https_types.h:755
const char * pClientCert
Client certificate store for this connection.
Definition: iot_https_types.h:751
const char * pAddress
Remote server address that is DNS discoverable.
Definition: iot_https_types.h:727
const char * pCaCert
Server trusted certificate store for this connection.
Definition: iot_https_types.h:748
uint32_t bufferLen
The length of the application provided buffer.
Definition: iot_https_types.h:652
uint8_t * pBuffer
Application provided buffer pointer.
Definition: iot_https_types.h:651

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

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

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.
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
@ IOT_HTTPS_OK
Returned for a successful operation.
Definition: iot_https_types.h:298
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:263
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:2731
#define IOT_HTTPS_REQUEST_INFO_INITIALIZER
Initializer for IotHttpsRequestInfo_t.
Definition: iot_https_types.h:204
#define IOT_HTTPS_REQUEST_HANDLE_INITIALIZER
Initializer for IotHttpsRequestHandle_t.
Definition: iot_https_types.h:192
#define IOT_HTTPS_SYNC_INFO_INITIALIZER
Initializer for IotHttpsSyncInfo_t.
Definition: iot_https_types.h:198
const uint32_t requestUserBufferMinimumSize
The minimum user buffer size for the HTTP request context and headers.
Definition: iot_https_client.c:118
HTTP request configuration.
Definition: iot_https_types.h:796
const char * pHost
Host address this request is intended for, e.g., "awsamazon.com".
Definition: iot_https_types.h:826
bool isAsync
Indicator if this request is sync or async.
Definition: iot_https_types.h:859
uint32_t hostLen
Host address length.
Definition: iot_https_types.h:827
IotHttpsUserBuffer_t userBuffer
Application owned buffer for storing the request headers and internal request context.
Definition: iot_https_types.h:852
const char * pPath
The absolute path to the HTTP request object.
Definition: iot_https_types.h:808
IotHttpsMethod_t method
On of the HTTP method tokens defined in IotHttpsMethod_t.
Definition: iot_https_types.h:817
bool isNonPersistent
Flag denoting if the connection should be non-persistent.
Definition: iot_https_types.h:842
IotHttpsSyncInfo_t * pSyncInfo
Information specifically for synchronous requests.
Definition: iot_https_types.h:870
HTTPS Client synchronous request information.
Definition: iot_https_types.h:668
uint32_t bodyLen
The length of the HTTP message body.
Definition: iot_https_types.h:682
uint8_t * pBody
Definition: iot_https_types.h:681
uint32_t bufferLen
The length of the application provided buffer.
Definition: iot_https_types.h:652
uint8_t * pBuffer
Application provided buffer pointer.
Definition: iot_https_types.h:651

◆ 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));
...
}
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:263
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.
Definition: iot_https_client.c:2884

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);
...
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:263
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.
Definition: iot_https_client.c:2884

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:

◆ 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);
...
}
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:263
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.
Definition: iot_https_client.c:3061
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:

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

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

◆ 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)
{
}
...
}
void _applicationDefined_writeCallback(void * pPrivData, IotHttpsRequestHandle_t reqHandle)
{
if( application_data_get(writeBuffer, writeBufferLen) == GEN_TOKEN_FAIL)
{
}
...
}
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:263
IotHttpsReturnCode_t IotHttpsClient_CancelRequestAsync(IotHttpsRequestHandle_t reqHandle)
Cancel an Asynchronous request.
Definition: iot_https_client.c:3175
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)
{
}
...
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:280
IotHttpsReturnCode_t IotHttpsClient_CancelResponseAsync(IotHttpsResponseHandle_t respHandle)
Cancel an Asynchronous response.
Definition: iot_https_client.c:3188
Parameters
[in]respHandle- Response handle associated with the response.
Returns
One of the following:

◆ 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.
}
...
IotHttpsReturnCode_t IotHttpsClient_ReadResponseStatus(IotHttpsResponseHandle_t respHandle, uint16_t *pStatus)
Retrieve the HTTPS response status.
Definition: iot_https_client.c:3249

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.
}
...
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:280
Parameters
[in]respHandle- Unique handle representing the HTTPS response.
[out]pStatus- Integer status returned by the server.
Returns
One of the following:

◆ 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);
...
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:280
IotHttpsReturnCode_t IotHttpsClient_ReadContentLength(IotHttpsResponseHandle_t respHandle, uint32_t *pContentLength)
Retrieve the HTTPS response content length.
Definition: iot_https_client.c:3368

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);
...
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:280
IotHttpsReturnCode_t IotHttpsClient_ReadContentLength(IotHttpsResponseHandle_t respHandle, uint32_t *pContentLength)
Retrieve the HTTPS response content length.
Definition: iot_https_client.c:3368
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:

◆ 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));
...
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:280
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.
Definition: iot_https_client.c:3268

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);
...
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:280
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.
Definition: iot_https_client.c:3268
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:

◆ 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);
...
}
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:294
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:263
IotHttpsReturnCode_t IotHttpsClient_ReadResponseBody(IotHttpsResponseHandle_t respHandle, uint8_t *pBuf, uint32_t *pLen)
Read the HTTPS response body from the network.
Definition: iot_https_client.c:3113

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: