IotHttpsClient_Connect

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

IotHttpsReturnCode_t IotHttpsClient_Connect( IotHttpsConnectionHandle_t * pConnHandle,
                                             IotHttpsConnectionInfo_t * pConnInfo );

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);
}