Synchronous send of the HTTPS request.

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

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.