iothub_client_ll.h File Reference

This struct captures IoTHub client configuration.

This struct captures IoTHub client device configuration.

Enumeration specifying the status of calls to various APIs in this module.

Enumeration passed in by the IoT Hub when the event confirmation callback is invoked to indicate status of the event processing in the hub.

Enumeration passed in by the IoT Hub when the connection status callback is invoked to indicate status of the connection in the hub.

Enumeration passed in by the IoT Hub when the connection status callback is invoked to indicate status of the connection in the hub.

Enumeration returned by the callback which is invoked whenever the IoT Hub sends a message to the device.

Enumeration returned by the IoTHubClient_LL_GetSendStatus API to indicate the current sending status of the IoT Hub client.

Enumeration returned by remotely executed functions.

Enumeration passed in by the IoT Hub when the event confirmation callback is invoked to indicate status of the event processing in the hub.

This function returns the current sending status for IoTHubClient.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
iotHubClientStatus	The sending state is populated at the address pointed at by this parameter. The value will be set to IOTHUBCLIENT_SENDSTATUS_IDLE if there is currently no item to be sent and IOTHUBCLIENT_SENDSTATUS_BUSY if there are.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

Asynchronous call to send the message specified by eventMessageHandle.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
eventMessageHandle	The handle to an IoT Hub message.
eventConfirmationCallback	The callback specified by the device for receiving confirmation of the delivery of the IoT Hub message. This callback can be expected to invoke the IoTHubClient_LL_SendEventAsync function for the same message in an attempt to retry sending a failing message. The user can specify a NULL value here to indicate that no callback is required.
userContextCallback	User specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

Disposes of resources allocated by the IoT Hub client.

This is a blocking call.

Parameters:

iotHubClientHandle

The handle created by a call to the create function.

Creates a IoT Hub client for communication with an existing IoT Hub using an existing transport.

Parameters:

config

Pointer to an IOTHUB_CLIENT_DEVICE_CONFIG structure

The API *allows* sharing of a connection across multiple devices. This is a blocking call.

Returns:

A non-NULL IOTHUB_CLIENT_LL_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters.

Parameters:

config

Pointer to an IOTHUB_CLIENT_CONFIG structure

The API does not allow sharing of a connection across multiple devices. This is a blocking call.

Returns:

A non-NULL IOTHUB_CLIENT_LL_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

Creates a IoT Hub client for communication with an existing IoT Hub using the specified connection string parameter.

Parameters:

connectionString	Pointer to a character string
protocol	Function pointer for protocol implementation

Sample connection string: <blockquote>

HostName=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net];DeviceId=[Device ID goes here];SharedAccessKey=[Device key goes here];

</blockquote>

Returns:

A non-NULL IOTHUB_CLIENT_LL_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

Sets up the connection status callback to be invoked representing the status of the connection to IOT Hub.

This is a blocking call.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
retryPolicy	Out parameter containing the policy to use to reconnect to IoT Hub.
retryTimeoutLimitInSeconds	Out parameter containing maximum amount of time in seconds to attempt reconnection to IOT Hub.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

This API sets a runtime option identified by parameter optionName to a value pointed to by value.

optionName and the data type value is pointing to are specific for every option.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
optionName	Name of the option.
value	The value.

The options that can be set via this API are:

• timeout - the maximum time in milliseconds a communication is allowed to use. value is a pointer to an unsigned int with the timeout value in milliseconds. This is only supported for the HTTP protocol as of now. When the HTTP protocol uses CURL, the meaning of the parameter is total request time. When the HTTP protocol uses winhttp, the meaning is the same as the dwSendTimeout and dwReceiveTimeout parameters of the WinHttpSetTimeouts API.
• CURLOPT_LOW_SPEED_LIMIT - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
• CURLOPT_LOW_SPEED_TIME - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
• CURLOPT_FORBID_REUSE - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
• CURLOPT_FRESH_CONNECT - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.
• CURLOPT_VERBOSE - only available for HTTP protocol and only when CURL is used. It has the same meaning as CURL's option with the same name. value is pointer to a long.

keepalive - available for MQTT protocol. Integer value that sets the interval in seconds when pings are sent to the server.

• logtrace - available for MQTT protocol. Boolean value that turns on and off the diagnostic logging.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

This API specifies a call back to be used when the device receives a desired state update.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
deviceTwinCallback	The callback specified by the device client to be used for updating the desired state. The callback will be called in response to patch request send by the IoTHub services. The payload will be passed to the callback, along with two version numbers: Desired: LastSeenReported:
userContextCallback	User specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

This API sets callback for cloud to device method call.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
deviceMethodCallback	The callback which will be called by IoTHub.
userContextCallback	User specified context that will be provided to the callback. This can be NULL.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

This API uploads to Azure Storage the content pointed to by source having the size size under the blob name devicename/.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
destinationFileName	name of the file.
source	pointer to the source for file content (can be NULL)
size	the size of the source in memory (if source is NULL then size needs to be 0).

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

Sets up the connection status callback to be invoked representing the status of the connection to IOT Hub.

This is a blocking call.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
connectionStatusCallback	The callback specified by the device for receiving updates about the status of the connection to IoT Hub.
userContextCallback	User specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

Sets up the connection status callback to be invoked representing the status of the connection to IOT Hub.

This is a blocking call.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
retryPolicy	The policy to use to reconnect to IoT Hub when a connection drops.
retryTimeoutLimitInSeconds	Maximum amount of time(seconds) to attempt reconnection when a connection drops to IOT Hub.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

This function is meant to be called by the user when work (sending/receiving) can be done by the IoTHubClient.

Parameters:

iotHubClientHandle

The handle created by a call to the create function.

All IoTHubClient interactions (in regards to network traffic and/or user level callbacks) are the effect of calling this function and they take place synchronously inside _DoWork.

This API sneds a report of the device's properties and their current values.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
reportedState	The current device property values to be 'reported' to the IoTHub.
reportedStateCallback	The callback specified by the device client to be called with the result of the transaction.
userContextCallback	User specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

Sets up the message callback to be invoked when IoT Hub issues a message to the device.

This is a blocking call.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
messageCallback	The callback specified by the device for receiving messages from IoT Hub.
userContextCallback	User specified context that will be provided to the callback. This can be NULL.

NOTE: The application behavior is undefined if the user calls the IoTHubClient_LL_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

This function returns in the out parameter lastMessageReceiveTime what was the value of the time function when the last message was received at the client.

Parameters:

iotHubClientHandle	The handle created by a call to the create function.
lastMessageReceiveTime	Out parameter containing the value of time function when the last message was received.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.