iot_https_client.c File Reference

Implementation of the user-facing functions of the FreeRTOS HTTPS Client library. More...

#include "iot_config.h"
#include "private/iot_https_internal.h"

Macros
#define	HTTPS_PARTIAL_REQUEST_LINE   HTTPS_CONNECT_METHOD " " HTTPS_EMPTY_PATH " " HTTPS_PROTOCOL_VERSION
	Partial HTTPS request first line. More...
#define	HTTPS_USER_AGENT_HEADER_LINE   HTTPS_USER_AGENT_HEADER HTTPS_HEADER_FIELD_SEPARATOR IOT_HTTPS_USER_AGENT HTTPS_END_OF_HEADER_LINES_INDICATOR
	The User-Agent header line string. More...
#define	HTTPS_PARTIAL_HOST_HEADER_LINE   HTTPS_HOST_HEADER HTTPS_HEADER_FIELD_SEPARATOR HTTPS_END_OF_HEADER_LINES_INDICATOR
	The Host header line with the field only and not the value. More...
#define	HTTPS_CONNECTION_KEEP_ALIVE_HEADER_LINE   HTTPS_CONNECTION_HEADER HTTPS_HEADER_FIELD_SEPARATOR HTTPS_CONNECTION_KEEP_ALIVE_HEADER_VALUE HTTPS_END_OF_HEADER_LINES_INDICATOR
	String literal for "Connection: keep-alive\r\n". More...
#define	HTTPS_CONNECTION_CLOSE_HEADER_LINE   HTTPS_CONNECTION_HEADER HTTPS_HEADER_FIELD_SEPARATOR HTTPS_CONNECTION_CLOSE_HEADER_VALUE HTTPS_END_OF_HEADER_LINES_INDICATOR
	String literal for "Connection: close\r\n".
#define	HTTPS_CONNECTION_KEEP_ALIVE_HEADER_LINE_LENGTH   ( 24 )
	The length of the "Connection: keep-alive\r\n" header. More...
#define	KEEP_PARSING   ( ( int ) 0 )
	Indicator in the http-parser callback to keep parsing when the function returns. More...
#define	STOP_PARSING   ( ( int ) 1 )
	Indicator in the http-parser callback to stop parsing when the function returns.

Functions
static int	_httpParserOnMessageBeginCallback (http_parser *pHttpParser)
	Callback from http-parser to indicate the start of the HTTP response message is reached. More...
static int	_httpParserOnStatusCallback (http_parser *pHttpParser, const char *pLoc, size_t length)
	Callback from http-parser to indicate it found the HTTP response status code. More...
static int	_httpParserOnHeaderFieldCallback (http_parser *pHttpParser, const char *pLoc, size_t length)
	Callback from http-parser to indicate it found an HTTP response header field. More...
static int	_httpParserOnHeaderValueCallback (http_parser *pHttpParser, const char *pLoc, size_t length)
	Callback from http-parser to indicate it found an HTTP response header value. More...
static int	_httpParserOnHeadersCompleteCallback (http_parser *pHttpParser)
	Callback from http-parser to indicate it reached the end of the headers in the HTTP response message. More...
static int	_httpParserOnBodyCallback (http_parser *pHttpParser, const char *pLoc, size_t length)
	Callback from http-parser to indicate it found HTTP response body. More...
static int	_httpParserOnMessageCompleteCallback (http_parser *pHttpParser)
	Callback from http-parser to indicate it reached the end of the HTTP response message. More...
static int	_httpParserOnChunkHeaderCallback (http_parser *pHttpParser)
	Callback from http-parser to indicate it found an HTTP Transfer-Encoding: chunked header. More...
static int	_httpParserOnChunkCompleteCallback (http_parser *pHttpParser)
	Callback from http-parser to indicate it reached the end of an HTTP response message "chunk". More...
static void	_networkReceiveCallback (void *pNetworkConnection, void *pReceiveContext)
	Network receive callback for the HTTPS Client library. More...
static IotHttpsReturnCode_t	_createHttpsConnection (IotHttpsConnectionHandle_t *pConnHandle, IotHttpsConnectionInfo_t *pConnInfo)
	Connects to HTTPS server and initializes the connection context. More...
static void	_networkDisconnect (_httpsConnection_t *pHttpsConnection)
	Disconnects from the network. More...
static void	_networkDestroy (_httpsConnection_t *pHttpsConnection)
	Destroys the network connection. More...
static IotHttpsReturnCode_t	_addHeader (_httpsRequest_t *pHttpsRequest, const char *pName, uint32_t nameLen, const char *pValue, uint32_t valueLen)
	Add a header to the current HTTP request. More...
static IotHttpsReturnCode_t	_networkSend (_httpsConnection_t *pHttpsConnection, uint8_t *pBuf, size_t len)
	Send data on the network. More...
static IotHttpsReturnCode_t	_networkRecv (_httpsConnection_t *pHttpsConnection, uint8_t *pBuf, size_t bufLen, size_t *numBytesRecv)
	Receive data on the network. More...
static IotHttpsReturnCode_t	_sendHttpsHeaders (_httpsConnection_t *pHttpsConnection, uint8_t *pHeadersBuf, uint32_t headersLength, bool isNonPersistent, uint32_t contentLength)
	Send all of the HTTP request headers in the pHeadersBuf and the final Content-Length and Connection headers. More...
static IotHttpsReturnCode_t	_sendHttpsBody (_httpsConnection_t *pHttpsConnection, uint8_t *pBodyBuf, uint32_t bodyLength)
	Send all of the HTTP request body in pBodyBuf. More...
static IotHttpsReturnCode_t	_parseHttpsMessage (_httpParserInfo_t *pHttpParserInfo, char *pBuf, size_t len)
	Parse the HTTP response message in pBuf. More...
static IotHttpsReturnCode_t	_receiveHttpsMessage (_httpsConnection_t *pHttpsConnection, _httpParserInfo_t *pParser, IotHttpsResponseParserState_t *pCurrentParserState, IotHttpsResponseParserState_t finalParserState, IotHttpsResponseBufferState_t currentBufferProcessingState, uint8_t **pBufCur, uint8_t **pBufEnd)
	Receive any part of an HTTP response. More...
static IotHttpsReturnCode_t	_receiveHttpsHeaders (_httpsConnection_t *pHttpsConnection, _httpsResponse_t *pHttpsResponse)
	Receive the HTTP response headers. More...
static IotHttpsReturnCode_t	_receiveHttpsBody (_httpsConnection_t *pHttpsConnection, _httpsResponse_t *pHttpsResponse)
	Receive the HTTP response body. More...
static IotHttpsReturnCode_t	_flushHttpsNetworkData (_httpsConnection_t *pHttpsConnection, _httpsResponse_t *pHttpsResponse)
	Read the rest of any HTTP response that may be on the network. More...
static void	_sendHttpsRequest (IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext)
	Task pool job routine to send the HTTP request within the pUserContext. More...
static IotHttpsReturnCode_t	_receiveHttpsBodyAsync (_httpsResponse_t *pHttpsResponse)
	Receive the HTTPS body specific to an asynchronous type of response. More...
static IotHttpsReturnCode_t	_receiveHttpsBodySync (_httpsResponse_t *pHttpsResponse)
	Receive the HTTPS body specific to a synchronous type of response. More...
IotHttpsReturnCode_t	_scheduleHttpsRequestSend (_httpsRequest_t *pHttpsRequest)
	Schedule the task to send the the HTTP request. More...
IotHttpsReturnCode_t	_addRequestToConnectionReqQ (_httpsRequest_t *pHttpsRequest)
	Add the request to the connection's request queue. More...
static void	_cancelRequest (_httpsRequest_t *pHttpsRequest)
	Cancel the HTTP request's processing. More...
static void	_cancelResponse (_httpsResponse_t *pHttpsResponse)
	Cancel the HTTP response's processing. More...
static IotHttpsReturnCode_t	_initializeResponse (IotHttpsResponseHandle_t *pRespHandle, IotHttpsResponseInfo_t *pRespInfo, _httpsRequest_t *pHttpsRequest)
	Initialize the input pHttpsResponse with pRespInfo. More...
static void	_incrementNextLocationToWriteBeyondParsed (uint8_t **pBufCur, uint8_t **pBufEnd)
	Increment the pointer stored in pBufCur depending on the character found in there. More...
static IotHttpsReturnCode_t	_sendHttpsHeadersAndBody (_httpsConnection_t *pHttpsConnection, _httpsRequest_t *pHttpsRequest)
	Send the HTTPS headers and body referenced in pHttpsRequest. More...
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_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_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_ReadResponseBody (IotHttpsResponseHandle_t respHandle, uint8_t *pBuf, uint32_t *pLen)
	Read the HTTPS response body from the network. 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_SendAsync (IotHttpsConnectionHandle_t connHandle, IotHttpsRequestHandle_t reqHandle, IotHttpsResponseHandle_t *pRespHandle, IotHttpsResponseInfo_t *pRespInfo)
	Asynchronous send of the the HTTPS request. More...
IotHttpsReturnCode_t	IotHttpsClient_ReadResponseStatus (IotHttpsResponseHandle_t respHandle, uint16_t *pStatus)
	Retrieve the HTTPS response status. 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_ReadContentLength (IotHttpsResponseHandle_t respHandle, uint32_t *pContentLength)
	Retrieve the HTTPS response content length. More...

Variables
const char *	_pHttpsMethodStrings []
	Definition of HTTP method enum to strings array. More...
const uint32_t	requestUserBufferMinimumSize
	Minimum size of the request user buffer. More...
const uint32_t	responseUserBufferMinimumSize = sizeof( _httpsResponse_t )
	Minimum size of the response user buffer. More...
const uint32_t	connectionUserBufferMinimumSize = sizeof( _httpsConnection_t )
	Minimum size of the connection user buffer. More...
static http_parser_settings	_httpParserSettings = { 0 }
	Definition of the http-parser settings. More...

Detailed Description

Implementation of the user-facing functions of the FreeRTOS HTTPS Client library.

Macro Definition Documentation

HTTPS_PARTIAL_REQUEST_LINE

#define HTTPS_PARTIAL_REQUEST_LINE   HTTPS_CONNECT_METHOD " " HTTPS_EMPTY_PATH " " HTTPS_PROTOCOL_VERSION

Partial HTTPS request first line.

This is used for the calculation of the requestUserBufferMinimumSize. The minimum path is "/" because we cannot know how long the application requested path is is going to be. CONNECT is the longest string length HTTP method according to RFC 2616.

HTTPS_USER_AGENT_HEADER_LINE

#define HTTPS_USER_AGENT_HEADER_LINE   HTTPS_USER_AGENT_HEADER HTTPS_HEADER_FIELD_SEPARATOR IOT_HTTPS_USER_AGENT HTTPS_END_OF_HEADER_LINES_INDICATOR

The User-Agent header line string.

This is of the form: "User-Agent: <configured-user-agent>\r\n" This is used for the calculation of the requestUserBufferMinimumSize.

HTTPS_PARTIAL_HOST_HEADER_LINE

#define HTTPS_PARTIAL_HOST_HEADER_LINE   HTTPS_HOST_HEADER HTTPS_HEADER_FIELD_SEPARATOR HTTPS_END_OF_HEADER_LINES_INDICATOR

The Host header line with the field only and not the value.

This is of the form: "Host: \r\n" This is used for the calculation of the requestUserBufferMinimumSize. The Host value is not specified because we cannot anticipate what server the client is making requests to.

HTTPS_CONNECTION_KEEP_ALIVE_HEADER_LINE

#define HTTPS_CONNECTION_KEEP_ALIVE_HEADER_LINE   HTTPS_CONNECTION_HEADER HTTPS_HEADER_FIELD_SEPARATOR HTTPS_CONNECTION_KEEP_ALIVE_HEADER_VALUE HTTPS_END_OF_HEADER_LINES_INDICATOR

String literal for "Connection: keep-alive\r\n".

String constants for the Connection header and possible values.

This is used for writing headers automatically during the sending of the HTTP request. "Connection: keep-alive\r\n" is written automatically for a persistent connection. "Connection: close\r\n" is written automatically for a non-persistent connection.

HTTPS_CONNECTION_KEEP_ALIVE_HEADER_LINE_LENGTH

#define HTTPS_CONNECTION_KEEP_ALIVE_HEADER_LINE_LENGTH   ( 24 )

The length of the "Connection: keep-alive\r\n" header.

This is used for sizing a local buffer for the final headers to send that include the "Connection: keep-alive\r\n" header line.

This is used to initialize a local array for the final headers to send.

KEEP_PARSING

#define KEEP_PARSING   ( ( int ) 0 )

Indicator in the http-parser callback to keep parsing when the function returns.

Indicates for the http-parser parsing execution function to tell it to keep parsing or to stop parsing.

A value of 0 means the parser should keep parsing if there is more unparsed length. A value greater than 0 tells the parser to stop parsing.

Function Documentation

_httpParserOnMessageBeginCallback()

static int _httpParserOnMessageBeginCallback ( http_parser *  pHttpParser )

static

Callback from http-parser to indicate the start of the HTTP response message is reached.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]

pHttpParser

- http-parser state structure.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_message_begin.

_httpParserOnStatusCallback()

static int _httpParserOnStatusCallback ( http_parser *  pHttpParser, const char *  pLoc, size_t  length  )

static

Callback from http-parser to indicate it found the HTTP response status code.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]	pHttpParser	- http-parser state structure.
[in]	pLoc	- Pointer to the HTTP response status code string in the response message buffer.
[in]	length	- The length of the HTTP response status code string.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_status.

_httpParserOnHeaderFieldCallback()

static int _httpParserOnHeaderFieldCallback ( http_parser *  pHttpParser, const char *  pLoc, size_t  length  )

static

Callback from http-parser to indicate it found an HTTP response header field.

If only part of the header field was returned here in this callback, then this callback will be invoked again the next time the parser executes on the next part of the header field.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]	pHttpParser	- http-parser state structure.
[in]	pLoc	- Pointer to the header field string in the response message buffer.
[in]	length	- The length of the header field.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_header_field.

_httpParserOnHeaderValueCallback()

static int _httpParserOnHeaderValueCallback ( http_parser *  pHttpParser, const char *  pLoc, size_t  length  )

static

Callback from http-parser to indicate it found an HTTP response header value.

This value corresponds to the field that was found in the _httpParserOnHeaderFieldCallback() called immediately before this callback was called.

If only part of the header value was returned here in this callback, then this callback will be invoked again the next time the parser executes on the next part of the header value.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]	pHttpParser	- http-parser state structure.
[in]	pLoc	- Pointer to the header value string in the response message buffer.
[in]	length	- The length of the header value.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_header_value.

_httpParserOnHeadersCompleteCallback()

static int _httpParserOnHeadersCompleteCallback ( http_parser *  pHttpParser )

static

Callback from http-parser to indicate it reached the end of the headers in the HTTP response message.

The end of the headers is signalled in a HTTP response message by another "\r\n" after the final header line.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]

pHttpParser

- http-parser state structure.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_headers_complete.

_httpParserOnBodyCallback()

static int _httpParserOnBodyCallback ( http_parser *  pHttpParser, const char *  pLoc, size_t  length  )

static

Callback from http-parser to indicate it found HTTP response body.

This callback will be invoked multiple times if the response body is of "Transfer-Encoding: chunked". _httpParserOnChunkHeaderCallback() will be invoked first, then _httpParserOnBodyCallback(), then _httpParserOnChunkCompleteCallback(), then repeated back to _httpParserOnChunkHeaderCallback() if there are more "chunks".

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]	pHttpParser	- http-parser state structure.
[in]	pLoc	- Pointer to the body string in the response message buffer.
[in]	length	- The length of the body found.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_body.

_httpParserOnMessageCompleteCallback()

static int _httpParserOnMessageCompleteCallback ( http_parser *  pHttpParser )

static

Callback from http-parser to indicate it reached the end of the HTTP response message.

The end of the message is signalled in a HTTP response message by another "\r\n" after the final header line, with no entity body; or it is signaled by "\r\n" at the end of the entity body.

For a Transfer-Encoding: chunked type of response message, the end of the message is signalled by a terminating chunk header with length zero.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]

pHttpParser

- http-parser state structure.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_message_complete.

_httpParserOnChunkHeaderCallback()

static int _httpParserOnChunkHeaderCallback ( http_parser *  pHttpParser )

static

Callback from http-parser to indicate it found an HTTP Transfer-Encoding: chunked header.

Transfer-Encoding: chunked headers are embedded in the HTTP response entity body by a "\r\n" followed by the size of the chunk followed by another "\r\n".

If only part of the header field was returned here in this callback, then this callback will be invoked again the next time the parser executes on the next part of the header field.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]

pHttpParser

- http-parser state structure.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_chunk_header.

_httpParserOnChunkCompleteCallback()

static int _httpParserOnChunkCompleteCallback ( http_parser *  pHttpParser )

static

Callback from http-parser to indicate it reached the end of an HTTP response message "chunk".

A chunk is complete when the chunk header size is read fully in the body.

See https://github.com/nodejs/http-parser for more information.

Parameters

[in]

pHttpParser

- http-parser state structure.

Returns

0 to tell http-parser to keep parsing. 1 to tell http-parser that parsing should stop return from http_parser_execute with error HPE_CB_chunk_complete.

_networkReceiveCallback()

static void _networkReceiveCallback ( void *  pNetworkConnection, void *  pReceiveContext  )

static

Network receive callback for the HTTPS Client library.

This function is called by the network layer whenever data is available for the HTTP library.

Parameters

[in]	pNetworkConnection	- The network connection with the HTTPS connection, passed by the network stack.
[in]	pReceiveContext	- A pointer to the HTTPS Client connection handle for which the packet was received.

_createHttpsConnection()

static IotHttpsReturnCode_t _createHttpsConnection ( IotHttpsConnectionHandle_t *  pConnHandle, IotHttpsConnectionInfo_t *  pConnInfo  )

static

Connects to HTTPS server and initializes the connection context.

Parameters

[out]	pConnHandle	- The out parameter to return handle representing the open connection.
[in]	pConnInfo	- The connection configuration.

Returns

IOT_HTTPS_OK if the connection context initialization was successful. IOT_HTTPS_CONNECTION_ERROR if the connection failed. IOT_HTTPS_INTERNAL_ERROR if the context initialization failed.

_networkDisconnect()

static void _networkDisconnect ( _httpsConnection_t *  pHttpsConnection )

static

Disconnects from the network.

Parameters

[in]

pHttpsConnection

- HTTPS connection handle.

_networkDestroy()

static void _networkDestroy ( _httpsConnection_t *  pHttpsConnection )

static

Destroys the network connection.

Parameters

[in]

pHttpsConnection

- HTTPS connection handle.

_addHeader()

static IotHttpsReturnCode_t _addHeader ( _httpsRequest_t *  pHttpsRequest, const char *  pName, uint32_t  nameLen, const char *  pValue, uint32_t  valueLen  )

static

Add a header to the current HTTP request.

The headers are stored in reqHandle->pHeaders.

Parameters

[in]	pHttpsRequest	- HTTP request context.
[in]	pName	- The name of the header to add.
[in]	nameLen	- The length of the header name string.
[in]	pValue	- The buffer containing the value string.
[in]	valueLen	- The length of the header value string.

Returns

IOT_HTTPS_OK if the header was added to the request successfully. IOT_HTTPS_INSUFFICIENT_MEMORY if there was not enough room in the IotHttpsRequestHandle_t->pHeaders.

_networkSend()

static IotHttpsReturnCode_t _networkSend ( _httpsConnection_t *  pHttpsConnection, uint8_t *  pBuf, size_t  len  )

static

Send data on the network.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pBuf	- The buffer containing the data to send.
[in]	len	- The length of the data to send.

Returns

IOT_HTTPS_OK if the data sent successfully. IOT_HTTPS_NETWORK_ERROR if there was an error sending the data on the network.

_networkRecv()

static IotHttpsReturnCode_t _networkRecv ( _httpsConnection_t *  pHttpsConnection, uint8_t *  pBuf, size_t  bufLen, size_t *  numBytesRecv  )

static

Receive data on the network.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pBuf	- The buffer to receive the data into.
[in]	bufLen	- The length of the data to receive.
[in]	numBytesRecv	- The number of bytes read from the network.

Returns

IOT_HTTPS_OK if the data was received successfully. IOT_HTTPS_NETWORK_ERROR if we timedout trying to receive data from the network.

_sendHttpsHeaders()

static IotHttpsReturnCode_t _sendHttpsHeaders ( _httpsConnection_t *  pHttpsConnection, uint8_t *  pHeadersBuf, uint32_t  headersLength, bool  isNonPersistent, uint32_t  contentLength  )

static

Send all of the HTTP request headers in the pHeadersBuf and the final Content-Length and Connection headers.

All of the headers in headerbuf are sent first followed by the computed content length and persistent connection indication.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pHeadersBuf	- The buffer containing the request headers to send. This buffer must contain HTTP headers lines without the indicator for the the end of the HTTP headers.
[in]	headersLength	- The length of the request headers to send.
[in]	isNonPersistent	- Indicator of whether the connection is persistent or not.
[in]	contentLength	- The length of the request body used for automatically creating a "Content-Length" header.

Returns

IOT_HTTPS_OK if the headers were fully sent successfully. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_sendHttpsBody()

static IotHttpsReturnCode_t _sendHttpsBody ( _httpsConnection_t *  pHttpsConnection, uint8_t *  pBodyBuf, uint32_t  bodyLength  )

static

Send all of the HTTP request body in pBodyBuf.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pBodyBuf	- Buffer of the request body to send.
[in]	bodyLength	- The length of the body to send.

Returns

IOT_HTTPS_OK if the body was fully sent successfully. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_parseHttpsMessage()

static IotHttpsReturnCode_t _parseHttpsMessage ( _httpParserInfo_t *  pHttpParserInfo, char *  pBuf, size_t  len  )

static

Parse the HTTP response message in pBuf.

Parameters

[in]	pHttpParserInfo	- Pointer to the information containing the instance of the http-parser and the execution function.
[in]	pBuf	- The buffer containing the data to parse.
[in]	len	- The length of data to parse.

Returns

IOT_HTTPS_OK if the data was parsed successfully. IOT_HTTPS_PARSING_ERROR if there was an error with parsing the data.

_receiveHttpsMessage()

static IotHttpsReturnCode_t _receiveHttpsMessage ( _httpsConnection_t *  pHttpsConnection, _httpParserInfo_t *  pParser, IotHttpsResponseParserState_t *  pCurrentParserState, IotHttpsResponseParserState_t  finalParserState, IotHttpsResponseBufferState_t  currentBufferProcessingState, uint8_t **  pBufCur, uint8_t **  pBufEnd  )

static

Receive any part of an HTTP response.

This function is used for both receiving the body into the body buffer and receiving the header into the header buffer.

Parameters

[in]	pHttpsConnection	- HTTP Connection context.
[in]	pParser	- Pointer to the instance of the http-parser.
[in]	pCurrentParserState	- The current state of what has been parsed in the HTTP response.
[in]	finalParserState	- The final state of the parser expected after this function finishes.
[in]	currentBufferProcessingState	- The current buffer that is the HTTPS message is being received into.
[in]	pBufCur	- Pointer to the next location to write data into the buffer pBuf. This is a double pointer to update the response context buffer pointers.
[in]	pBufEnd	- Pointer to the end of the buffer to receive the HTTP response into.

Returns

IOT_HTTPS_OK if we received the HTTP response message part successfully. IOT_HTTPS_PARSING_ERROR if there was an error with parsing the data. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_receiveHttpsHeaders()

static IotHttpsReturnCode_t _receiveHttpsHeaders ( _httpsConnection_t *  pHttpsConnection, _httpsResponse_t *  pHttpsResponse  )

static

Receive the HTTP response headers.

Receiving the response headers is always the first step in receiving the response, therefore the pHttpsResponse->httpParserInfo will be initialized to a starting state when this function is called.

This function also sets internal states to indicate that the header buffer is being processed now for a new response.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pHttpsResponse	- HTTP response context.

Returns

IOT_HTTPS_OK if we received the HTTP headers successfully. IOT_HTTPS_PARSING_ERROR if there was an error with parsing the header buffer. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_receiveHttpsBody()

static IotHttpsReturnCode_t _receiveHttpsBody ( _httpsConnection_t *  pHttpsConnection, _httpsResponse_t *  pHttpsResponse  )

static

Receive the HTTP response body.

Sets internal states to indicate that the the body buffer is being processed now for a new response.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pHttpsResponse	- HTTP response context.

Returns

IOT_HTTPS_OK if we received the HTTP body successfully. IOT_HTTPS_PARSING_ERROR if there was an error with parsing the body buffer. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_flushHttpsNetworkData()

static IotHttpsReturnCode_t _flushHttpsNetworkData ( _httpsConnection_t *  pHttpsConnection, _httpsResponse_t *  pHttpsResponse  )

static

Read the rest of any HTTP response that may be on the network.

This reads the rest of any left over response data that might still be on the network buffers. We do not want this data left over because it will spill into the header and body buffers of next response that we try to receive.

If we performed a request without a body and the headers received exceeds the size of the pHttpsResponse->pHeaders buffer, then we need to flush the network buffer.

If the application configured the body buffer as null in IotHttpsResponseInfo_t.syncInfo.respData and the server sends body in the response, but it exceeds the size of pHttpsResponse->pHeaders buffer, then we need to flush the network buffer.

If the amount of body received on the network does not fit into a non-null IotHttpsResponseInfo_t.syncInfo.respData, then we need to flush the network buffer.

If an asynchronous request cancels in the middle of a response process, after already sending the request message, then we need to flush the network buffer.

Parameters

[in]	pHttpsConnection	- HTTP connection context.
[in]	pHttpsResponse	- HTTP response context.

Returns

IOT_HTTPS_OK if we successfully flushed the network data. IOT_HTTPS_PARSING_ERROR if there was an error with parsing the data. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_sendHttpsRequest()

static void _sendHttpsRequest ( IotTaskPool_t  pTaskPool, IotTaskPoolJob_t  pJob, void *  pUserContext  )

static

Task pool job routine to send the HTTP request within the pUserContext.

Parameters

[in]	pTaskPool	Pointer to the system task pool.
[in]	pJob	Pointer the to the HTTP request sending job.
[in]	pUserContext	Pointer to an HTTP request, passed as an opaque context.

_receiveHttpsBodyAsync()

static IotHttpsReturnCode_t _receiveHttpsBodyAsync ( _httpsResponse_t *  pHttpsResponse )

static

Receive the HTTPS body specific to an asynchronous type of response.

Parameters

[in]

pHttpsResponse

- HTTP response context.

Returns

IOT_HTTPS_OK - If the the response body was received with no issues. IOT_HTTPS_RECEIVE_ABORT - If the request was cancelled by the Application IOT_HTTPS_PARSING_ERROR - If there was an issue parsing the HTTP response body. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_receiveHttpsBodySync()

static IotHttpsReturnCode_t _receiveHttpsBodySync ( _httpsResponse_t *  pHttpsResponse )

static

Receive the HTTPS body specific to a synchronous type of response.

Parameters

[in]

pHttpsResponse

- HTTP response context.

Returns

IOT_HTTPS_OK - If the the response body was received with no issues. IOT_HTTPS_MESSAGE_TOO_LARGE - If the body from the network is too large to fit into the configured body buffer. IOT_HTTPS_PARSING_ERROR - If there was an issue parsing the HTTP response body. IOT_HTTPS_NETWORK_ERROR if there was an error receiving the data on the network.

_scheduleHttpsRequestSend()

IotHttpsReturnCode_t _scheduleHttpsRequestSend

(

_httpsRequest_t *

pHttpsRequest

)

Schedule the task to send the the HTTP request.

Parameters

[in]

pHttpsRequest

- HTTP request context.

Returns

IOT_HTTPS_OK - If the task to send the HTTP request was successfully scheduled. IOT_HTTPS_INTERNAL_ERROR - If a taskpool job could not be created. IOT_HTTPS_ASYNC_SCHEDULING_ERROR - If there was an error scheduling the job.

_addRequestToConnectionReqQ()

IotHttpsReturnCode_t _addRequestToConnectionReqQ

(

_httpsRequest_t *

pHttpsRequest

)

Add the request to the connection's request queue.

This will schedule a task if the request is first and only request in the queue.

Parameters

[in]

pHttpsRequest

- HTTP request context.

Returns

IOT_HTTPS_OK - If the request was successfully added to the connection's request queue. IOT_HTTPS_INTERNAL_ERROR - If a taskpool job could not be created. IOT_HTTPS_ASYNC_SCHEDULING_ERROR - If there was an error scheduling the job.

_cancelRequest()

static void _cancelRequest ( _httpsRequest_t *  pHttpsRequest )

static

Cancel the HTTP request's processing.

pHttpsRequest->cancelled will be checked and the request cancelled if specified so at the following intervals:

• Before sending the HTTPS headers at the start of the scheduled sending of the HTTPS request.
• After Sending the HTTPS headers.
• After Sending the HTTPS body.

Parameters

[in]

pHttpsRequest

- HTTP request context.

_cancelResponse()

static void _cancelResponse ( _httpsResponse_t *  pHttpsResponse )

static

Cancel the HTTP response's processing.

pHttpsResponse->cancelled will be checked and the response cancelled if specified so at the following intervals:

• At the start of the network receive callback.
• After receiving the HTTPS headers.
• After Receiving the HTTPS body.

Parameters

[in]

pHttpsResponse

- HTTP response context.

_initializeResponse()

static IotHttpsReturnCode_t _initializeResponse ( IotHttpsResponseHandle_t *  pRespHandle, IotHttpsResponseInfo_t *  pRespInfo, _httpsRequest_t *  pHttpsRequest  )

static

Initialize the input pHttpsResponse with pRespInfo.

Parameters

[in]	pRespHandle	- Non-null HTTP response context.
[in]	pRespInfo	- Response configuration information.
[in]	pHttpsRequest	- HTTP request to grab async information, persistence, and method from.

_incrementNextLocationToWriteBeyondParsed()

static void _incrementNextLocationToWriteBeyondParsed ( uint8_t **  pBufCur, uint8_t **  pBufEnd  )

static

Increment the pointer stored in pBufCur depending on the character found in there.

This function increments the pHeadersCur pointer further if the message ended with a header line delimiter.

Parameters

[in]	pBufCur	- Pointer to the next location to write data into the buffer pBuf. This is a double pointer to update the response context buffer pointers.
[in]	pBufEnd	- Pointer to the end of the buffer to receive the HTTP response into.

_sendHttpsHeadersAndBody()

static IotHttpsReturnCode_t _sendHttpsHeadersAndBody ( _httpsConnection_t *  pHttpsConnection, _httpsRequest_t *  pHttpsRequest  )

static

Send the HTTPS headers and body referenced in pHttpsRequest.

Sends both the headers and body over the network.

Parameters

[in]	pHttpsConnection	- HTTPS connection context.
[in]	pHttpsRequest	- HTTPS request context.

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_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_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_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.

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_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_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_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_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.

Variable Documentation

_pHttpsMethodStrings

const char* _pHttpsMethodStrings[]

Initial value:

=
{
    "GET",
    "HEAD",
    "PUT",
    "POST"
}

Definition of HTTP method enum to strings array.

A map of the method enum to strings.

requestUserBufferMinimumSize

const uint32_t requestUserBufferMinimumSize

Initial value:

= sizeof( _httpsRequest_t ) +
                                              sizeof( HTTPS_PARTIAL_REQUEST_LINE ) +
                                              sizeof( HTTPS_USER_AGENT_HEADER_LINE ) +
                                              sizeof( HTTPS_PARTIAL_HOST_HEADER_LINE )

Minimum size of the request user buffer.

The minimum user buffer size for the HTTP request context and headers.

The request user buffer is configured in IotHttpsClientRequestInfo_t.userBuffer. This buffer stores the internal context of the request and then the request headers right after. The minimum size for the buffer is the total size of the internal request context, the HTTP formatted request line, the User-Agent header line, and the part of the Host header line.

responseUserBufferMinimumSize

const uint32_t responseUserBufferMinimumSize = sizeof( _httpsResponse_t )

Minimum size of the response user buffer.

The minimum user buffer size for the HTTP response context and headers.

The response user buffer is configured in IotHttpsClientRequestInfo_t.userBuffer. This buffer stores the internal context of the response and then the response headers right after. This minimum size is calculated for the case if no bytes from the HTTP response headers are to be stored.

connectionUserBufferMinimumSize

const uint32_t connectionUserBufferMinimumSize = sizeof( _httpsConnection_t )

Minimum size of the connection user buffer.

The minimum user buffer size for the HTTP connection context and headers.

The connection user buffer is configured in IotHttpsConnectionInfo_t.userBuffer. This buffer stores the internal context of the connection.

_httpParserSettings

http_parser_settings _httpParserSettings = { 0 }

static

Definition of the http-parser settings.

The http_parser_settings holds all of the callbacks invoked by the http-parser.