iothub_client.h File Reference

IoTHubClient_UploadToBlobAsync uploads data from memory to a file in Azure Blob Storage.

Parameters:

iotHubClientHandle	The handle created by a call to the IoTHubClient_Create function.
destinationFileName	The name of the file to be created in Azure Blob Storage.
source	The source of data.
size	The size of data.
iotHubClientFileUploadCallback	A callback to be invoked when the file upload operation has finished.
context	A user-provided context to be passed to the file upload 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 sends 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_Destroy function from within any callback.

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 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 a 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_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.
• messageTimeout - the maximum time in milliseconds until a message is timeouted. The time starts at IoTHubClient_SendEventAsync. By default, messages do not expire. is a pointer to a uint64_t

  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.

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.

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.

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 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_Destroy function from within any callback.

Returns:

IOTHUB_CLIENT_OK upon success or an error code upon failure.

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_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_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 the specified parameters.

Parameters:

transportHandle	TRANSPORT_HANDLE which represents a connection.
config	Pointer to an IOTHUB_CLIENT_CONFIG structure

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

Returns:

A non-NULL IOTHUB_CLIENT_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_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];

HostName=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net];DeviceId=[Device ID goes here];SharedAccessSignature=SharedAccessSignature sr=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net]/devices/[Device ID goes here]&sig=[SAS Token goes here]&se=[Expiry Time goes here];

</blockquote>

Returns:

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