HTTPS Client API Reference
HTTPS Client v1.0.0 library
IotHttpsClient_SendSync

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_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.
Definition: iot_https_client.c:2923
IotHttpsResponseInfo_t
HTTP request configuration.
Definition: iot_https_types.h:885
IotHttpsResponseHandle_t
struct _httpsResponse * IotHttpsResponseHandle_t
Opaque handle of an HTTP response.
Definition: iot_https_types.h:284
IotHttpsRequestHandle_t
struct _httpsRequest * IotHttpsRequestHandle_t
Opaque handle of an HTTP request.
Definition: iot_https_types.h:267
IotHttpsConnectionHandle_t
struct _httpsConnection * IotHttpsConnectionHandle_t
Opaque handle of an HTTP connection.
Definition: iot_https_types.h:252
IotHttpsReturnCode_t
IotHttpsReturnCode_t
Return codes of HTTPS Client functions.
Definition: iot_https_types.h:296