Extends the IoTHubDeviceClient_LL with additional features. More...

#include <stddef.h>
#include <stdint.h>
#include "umock_c/umock_c_prod.h"
#include "iothub_transport_ll.h"
#include "iothub_client_core_ll.h"
#include "iothub_client_core.h"
#include "iothub_device_client_ll.h"

Typedefs
typedef IOTHUB_CLIENT_CORE_HANDLE	IOTHUB_DEVICE_CLIENT_HANDLE
	Handle corresponding to a convenience layer device client instance. More...

Functions
IOTHUB_DEVICE_CLIENT_HANDLE	IoTHubDeviceClient_CreateFromConnectionString (const char *connectionString, IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol)
	Creates a IoT Hub client for communication with an existing IoT Hub using the specified connection string parameter. More...

IOTHUB_DEVICE_CLIENT_HANDLE	IoTHubDeviceClient_Create (const IOTHUB_CLIENT_CONFIG *config)
	Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters. More...

IOTHUB_DEVICE_CLIENT_HANDLE	IoTHubDeviceClient_CreateWithTransport (TRANSPORT_HANDLE transportHandle, const IOTHUB_CLIENT_CONFIG *config)
	Creates a IoT Hub client for communication with an existing IoT Hub using the specified parameters. More...

IOTHUB_DEVICE_CLIENT_HANDLE	IoTHubDeviceClient_CreateFromDeviceAuth (const char iothub_uri, const char device_id, IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol)
	Creates a IoT Hub client for communication with an existing IoT Hub using the device auth. More...

void	IoTHubDeviceClient_Destroy (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle)
	Disposes of resources allocated by the IoT Hub client. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SendEventAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_MESSAGE_HANDLE eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK eventConfirmationCallback, void *userContextCallback)
	Asynchronous call to send the message specified by `eventMessageHandle`. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_GetSendStatus (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_STATUS *iotHubClientStatus)
	This function returns the current sending status for IoTHubClient. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SetMessageCallback (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC messageCallback, void *userContextCallback)
	Sets up the message callback to be invoked when IoT Hub issues a message to the device. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SetConnectionStatusCallback (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK connectionStatusCallback, void *userContextCallback)
	Sets up the connection status callback to be invoked representing the status of the connection to IOT Hub. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SetRetryPolicy (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY retryPolicy, size_t retryTimeoutLimitInSeconds)
	Sets up the connection status callback to be invoked representing the status of the connection to IOT Hub. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_GetRetryPolicy (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY retryPolicy, size_t retryTimeoutLimitInSeconds)
	Sets up the connection status callback to be invoked representing the status of the connection to IOT Hub. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_GetLastMessageReceiveTime (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, time_t *lastMessageReceiveTime)
	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. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SetOption (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char optionName, const void value)
	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. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SetDeviceTwinCallback (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK deviceTwinCallback, void *userContextCallback)
	This API specifies a callback to be used when the device receives a state update. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SendReportedState (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const unsigned char reportedState, size_t size, IOTHUB_CLIENT_REPORTED_STATE_CALLBACK reportedStateCallback, void userContextCallback)
	This API sends a report of the device's properties and their current values. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_GetTwinAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK deviceTwinCallback, void *userContextCallback)
	This API provides a way to retrieve the complete device Twin properties on-demand. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SetDeviceMethodCallback (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC deviceMethodCallback, void *userContextCallback)
	This API sets the callback for async cloud to device method calls. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_DeviceMethodResponse (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, METHOD_HANDLE methodId, const unsigned char *response, size_t response_size, int statusCode)
	This API responds to an asnyc method callback identified the methodId. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_UploadToBlobAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char destinationFileName, const unsigned char source, size_t size, IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK iotHubClientFileUploadCallback, void *context)
	IoTHubDeviceClient_UploadToBlobAsync uploads data from memory to a file in Azure Blob Storage. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char destinationFileName, IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX getDataCallbackEx, void context)
	Uploads a file to a Blob storage in chunks, fed through the callback function provided by the user. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SendMessageDisposition (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_MESSAGE_HANDLE message, IOTHUBMESSAGE_DISPOSITION_RESULT disposition)
	This API sends an acknowledgement to Azure IoT Hub that a cloud-to-device message has been received and frees resources associated with the message. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SendTelemetryAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_MESSAGE_HANDLE telemetryMessageHandle, IOTHUB_CLIENT_TELEMETRY_CALLBACK telemetryConfirmationCallback, void *userContextCallback)
	Asynchronous call to send the telemetry message specified by `telemetryMessageHandle`. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SubscribeToCommands (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC commandCallback, void *userContextCallback)
	Subscribe to incoming commands from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_SendPropertiesAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const unsigned char properties, size_t propertiesLength, IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK propertyAcknowledgedCallback, void userContextCallback)
	Sends device properties to IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_GetPropertiesAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK propertyCallback, void *userContextCallback)
	Retrieves all device properties from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubDeviceClient_GetPropertiesAndSubscribeToUpdatesAsync (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK propertyUpdateCallback, void *userContextCallback)
	Retrieves all device properties from IoT Hub and also subscribes for updates to writable properties. More...

Detailed Description

Extends the IoTHubDeviceClient_LL with additional features.

IoTHubDeviceClient extends the IoTHubDeviceClient_LL with 2 features:

scheduling the work for the IoTHubDeviceClient from a thread, so that the user does not need to create their own thread
thread-safe APIs

Typedef Documentation

◆ IOTHUB_DEVICE_CLIENT_HANDLE

typedef IOTHUB_CLIENT_CORE_HANDLE IOTHUB_DEVICE_CLIENT_HANDLE

Handle corresponding to a convenience layer device client instance.

Remarks: See https://github.com/Azure/azure-iot-sdk-c/blob/main/doc/threading_notes.md for more details about convenience layer versus lower layer (LL) threading models.

Function Documentation

◆ IoTHubDeviceClient_Create()

IOTHUB_DEVICE_CLIENT_HANDLE IoTHubDeviceClient_Create ( const IOTHUB_CLIENT_CONFIG * config )

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_DEVICE_CLIENT_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

◆ IoTHubDeviceClient_CreateFromConnectionString()

IOTHUB_DEVICE_CLIENT_HANDLE IoTHubDeviceClient_CreateFromConnectionString	(	const char *	connectionString,
		IOTHUB_CLIENT_TRANSPORT_PROVIDER	protocol
	)

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>
               <pre>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];</pre>
              <pre>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];</pre>
           </blockquote>

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

◆ IoTHubDeviceClient_CreateFromDeviceAuth()

IOTHUB_DEVICE_CLIENT_HANDLE IoTHubDeviceClient_CreateFromDeviceAuth	(	const char *	iothub_uri,
		const char *	device_id,
		IOTHUB_CLIENT_TRANSPORT_PROVIDER	protocol
	)

Creates a IoT Hub client for communication with an existing IoT Hub using the device auth.

Parameters

iothub_uri	Pointer to an ioThub hostname received in the registration process
device_id	Pointer to the device Id of the device
protocol	Function pointer for protocol implementation

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

◆ IoTHubDeviceClient_CreateWithTransport()

IOTHUB_DEVICE_CLIENT_HANDLE IoTHubDeviceClient_CreateWithTransport	(	TRANSPORT_HANDLE	transportHandle,
		const IOTHUB_CLIENT_CONFIG *	config
	)

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_DEVICE_CLIENT_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

◆ IoTHubDeviceClient_Destroy()

void IoTHubDeviceClient_Destroy ( IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle )

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.

Warning: Do not call this function from inside any application callbacks from this SDK, e.g. your IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK handler.

◆ IoTHubDeviceClient_DeviceMethodResponse()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_DeviceMethodResponse	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		METHOD_HANDLE	methodId,
		const unsigned char *	response,
		size_t	response_size,
		int	statusCode
	)

This API responds to an asnyc method callback identified the methodId.

Parameters

iotHubClientHandle	The handle created by a call to the create function.
methodId	The methodId of the Device Method callback.
response	The response data for the method callback.
response_size	The size of the response data buffer.
statusCode	The status response of the method callback.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_GetLastMessageReceiveTime()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetLastMessageReceiveTime	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		time_t *	lastMessageReceiveTime
	)

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.

◆ IoTHubDeviceClient_GetPropertiesAndSubscribeToUpdatesAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetPropertiesAndSubscribeToUpdatesAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK	propertyUpdateCallback,
		void *	userContextCallback
	)

Retrieves all device properties from IoT Hub and also subscribes for updates to writable properties.

Parameters

[in]	iotHubClientHandle	The handle created by a call to the create function.
[in]	propertyUpdateCallback	Callback both on initial retrieval of properties stored on IoT Hub and subsequent service-initiated modifications of writable properties. The API IoTHubClient_Deserialize_Properties() can help deserialize the raw payload stream.
[in]	userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_GetPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetPropertiesAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK	propertyCallback,
		void *	userContextCallback
	)

Retrieves all device properties from IoT Hub.

Parameters

[in]	iotHubClientHandle	The handle created by a call to the create function.
[in]	propertyCallback	Callback invoked when properties are retrieved. The API IoTHubClient_Deserialize_Properties() can help deserialize the raw payload stream.
[in]	userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_GetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetRetryPolicy	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_RETRY_POLICY *	retryPolicy,
		size_t *	retryTimeoutLimitInSeconds
	)

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.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_GetSendStatus()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetSendStatus	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_STATUS *	iotHubClientStatus
	)

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 `IOTHUB_CLIENT_SEND_STATUS_IDLE` if there is currently no item to be sent and `IOTHUB_CLIENT_SEND_STATUS_BUSY` if there are.

Remarks: Does not return information related to uploads initiated by IoTHubDeviceClient_UploadToBlob or IoTHubDeviceClient_UploadMultipleBlocksToBlob.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_GetTwinAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetTwinAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK	deviceTwinCallback,
		void *	userContextCallback
	)

This API provides a way to retrieve the complete device Twin properties on-demand.

Parameters

iotHubClientHandle	The handle created by a call to the create function.
deviceTwinCallback	The callback invoked to provide the complete Device Twin properties once its retrieval is completed by the client. If any failures occur, the callback is invoked passing `NULL` as payLoad and zero as size.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SendEventAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SendEventAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_MESSAGE_HANDLE	eventMessageHandle,
		IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK	eventConfirmationCallback,
		void *	userContextCallback
	)

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 IoTHubDeviceClient_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`.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Remarks: The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function, so this argument can be destroyed by the calling application right after IoTHubDeviceClient_SendEventAsync returns. The copy of eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SendMessageDisposition()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SendMessageDisposition	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_MESSAGE_HANDLE	message,
		IOTHUBMESSAGE_DISPOSITION_RESULT	disposition
	)

This API sends an acknowledgement to Azure IoT Hub that a cloud-to-device message has been received and frees resources associated with the message.

Parameters

iotHubClientHandle	The handle created by a call to a create function.
message	The cloud-to-device message received through the callback provided to IoTHubDeviceClient_SetMessageCallback.
disposition	Acknowledgement option for the message.

Warning: This function is to be used only when IOTHUBMESSAGE_ASYNC_ACK is used in the callback for incoming cloud-to-device messages.

Remarks: If your cloud-to-device message callback returned IOTHUBMESSAGE_ASYNC_ACK, it MUST call this API eventually. Beyond sending acknowledgment to the service, this method also handles freeing message's memory. Not calling this function will result in memory leaks. Depending on the protocol used, this API will acknowledge cloud-to-device messages differently: AMQP: A MESSAGE DISPOSITION is sent using the disposition option provided. MQTT: A PUBACK is sent if disposition is IOTHUBMESSAGE_ACCEPTED. Passing any other option results in no PUBACK sent for the message. HTTP: A HTTP request is sent using the disposition option provided.

Returns: IOTHUB_CLIENT_OK upon success, or an error code upon failure.

◆ IoTHubDeviceClient_SendPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SendPropertiesAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		const unsigned char *	properties,
		size_t	propertiesLength,
		IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK	propertyAcknowledgedCallback,
		void *	userContextCallback
	)

Sends device properties to IoT Hub.

Parameters

[in]	iotHubClientHandle	The handle created by a call to the create function.
[in]	properties	Serialized property data to be sent to IoT Hub. This buffer can either be manually serialized created with IoTHubClient_Properties_Serializer_CreateReported() or IoTHubClient_Properties_Serializer_CreateWritableResponse().
[in]	propertiesLength	Number of bytes in the properties buffer.
[in]	propertyAcknowledgedCallback	Optional callback specified by the application to be called with the result of the transaction.
[in]	userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SendReportedState()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SendReportedState	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		const unsigned char *	reportedState,
		size_t	size,
		IOTHUB_CLIENT_REPORTED_STATE_CALLBACK	reportedStateCallback,
		void *	userContextCallback
	)

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 IoT Hub.
size	Number of bytes in `reportedState`.
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`.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SendTelemetryAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SendTelemetryAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_MESSAGE_HANDLE	telemetryMessageHandle,
		IOTHUB_CLIENT_TELEMETRY_CALLBACK	telemetryConfirmationCallback,
		void *	userContextCallback
	)

Asynchronous call to send the telemetry message specified by telemetryMessageHandle.

Parameters

[in]	iotHubClientHandle	The handle created by a call to the create function.
[in]	telemetryMessageHandle	The handle to an IoT Hub message.
[in]	telemetryConfirmationCallback	Optional callback specified by the device for receiving confirmation of the delivery of the telemetry.
[in]	userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

The IOTHUB_MESSAGE_HANDLE instance provided as an argument is copied by the function, so this argument can be destroyed by the calling application right after IoTHubDeviceClient_SendTelemetryAsync returns. The copy of telemetryMessageHandle is later destroyed by the iothub client when the message is successfully sent, if a failure sending it occurs, or if the client is destroyed.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SetConnectionStatusCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetConnectionStatusCallback	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK	connectionStatusCallback,
		void *	userContextCallback
	)

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`.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Remarks: Callback specified will not receive connection status change notifications for upload connections created with IoTHubDeviceClient_UploadToBlob or IoTHubDeviceClient_UploadMultipleBlocksToBlob.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SetDeviceMethodCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetDeviceMethodCallback	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC	deviceMethodCallback,
		void *	userContextCallback
	)

This API sets the callback for async cloud to device method calls.

Parameters

iotHubClientHandle	The handle created by a call to the create function.
deviceMethodCallback	The callback which will be called by IoT Hub.
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.

◆ IoTHubDeviceClient_SetDeviceTwinCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetDeviceTwinCallback	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK	deviceTwinCallback,
		void *	userContextCallback
	)

This API specifies a callback 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 IoT Hub 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`.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SetMessageCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetMessageCallback	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC	messageCallback,
		void *	userContextCallback
	)

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`.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SetOption()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetOption	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		const char *	optionName,
		const void *	value
	)

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.

Remarks: Documentation for configuration options is available at https://github.com/Azure/azure-iot-sdk-c/blob/main/doc/Iothub_sdk_options.md.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetRetryPolicy	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_RETRY_POLICY	retryPolicy,
		size_t	retryTimeoutLimitInSeconds
	)

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.

Warning: : Do not call IoTHubDeviceClient_Destroy() from inside your application's callback.

Remarks: Uploads initiated by IoTHubDeviceClient_UploadToBlob or IoTHubDeviceClient_UploadMultipleBlocksToBlob do not have automatic retries and do not honor the retryPolicy settings.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_SubscribeToCommands()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SubscribeToCommands	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC	commandCallback,
		void *	userContextCallback
	)

Subscribe to incoming commands from IoT Hub.

Parameters

[in]	iotHubClientHandle	The handle created by a call to the create function.
[in]	commandCallback	The callback which will be called when a command request arrives.
[in]	userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		const char *	destinationFileName,
		IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX	getDataCallbackEx,
		void *	context
	)

Uploads a file to a Blob storage in chunks, fed through the callback function provided by the user.

Remarks: This function allows users to upload large files in chunks, not requiring the whole file content to be passed in memory.

Parameters

iotHubClientHandle	The handle created by a call to the IoTHubDeviceClient_Create function.
destinationFileName	The name of the file to be created in Azure Blob Storage.
getDataCallbackEx	A callback to be invoked to acquire the file chunks to be uploaded, as well as to indicate the status of the upload of the previous block.
context	Any data provided by the user to serve as context on getDataCallback.

Returns: An IOTHUB_CLIENT_RESULT value indicating the success or failure of the API call.

◆ IoTHubDeviceClient_UploadToBlobAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_UploadToBlobAsync	(	IOTHUB_DEVICE_CLIENT_HANDLE	iotHubClientHandle,
		const char *	destinationFileName,
		const unsigned char *	source,
		size_t	size,
		IOTHUB_CLIENT_FILE_UPLOAD_CALLBACK	iotHubClientFileUploadCallback,
		void *	context
	)

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

Parameters

iotHubClientHandle	The handle created by a call to the IoTHubDeviceClient_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.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ IOTHUB_DEVICE_CLIENT_HANDLE

Function Documentation

◆ IoTHubDeviceClient_Create()

◆ IoTHubDeviceClient_CreateFromConnectionString()

◆ IoTHubDeviceClient_CreateFromDeviceAuth()

◆ IoTHubDeviceClient_CreateWithTransport()

◆ IoTHubDeviceClient_Destroy()

◆ IoTHubDeviceClient_DeviceMethodResponse()

◆ IoTHubDeviceClient_GetLastMessageReceiveTime()

◆ IoTHubDeviceClient_GetPropertiesAndSubscribeToUpdatesAsync()

◆ IoTHubDeviceClient_GetPropertiesAsync()

◆ IoTHubDeviceClient_GetRetryPolicy()

◆ IoTHubDeviceClient_GetSendStatus()

◆ IoTHubDeviceClient_GetTwinAsync()

◆ IoTHubDeviceClient_SendEventAsync()

◆ IoTHubDeviceClient_SendMessageDisposition()

◆ IoTHubDeviceClient_SendPropertiesAsync()

◆ IoTHubDeviceClient_SendReportedState()

◆ IoTHubDeviceClient_SendTelemetryAsync()

◆ IoTHubDeviceClient_SetConnectionStatusCallback()

◆ IoTHubDeviceClient_SetDeviceMethodCallback()

◆ IoTHubDeviceClient_SetDeviceTwinCallback()

◆ IoTHubDeviceClient_SetMessageCallback()

◆ IoTHubDeviceClient_SetOption()

◆ IoTHubDeviceClient_SetRetryPolicy()

◆ IoTHubDeviceClient_SubscribeToCommands()

◆ IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync()

◆ IoTHubDeviceClient_UploadToBlobAsync()