Azure IoT C SDK
Macros | Typedefs | Functions
iothub_device_client.h File Reference

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"

Go to the source code of this file.

Typedefs

typedef IOTHUB_CLIENT_CORE_HANDLE IOTHUB_DEVICE_CLIENT_HANDLE
 Handle corresponding to a convenience layer device client instance. More...
 
typedef IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE
 Handle for Upload-to-Blob API Functions.
 

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 the Retry Policy feature to control how immediatelly and frequently the SDK will attempt to re-connect to the Azure IoT Hub in case a connection issue occurs. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_GetRetryPolicy (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY *retryPolicy, size_t *retryTimeoutLimitInSeconds)
 Gets the Retry Policy setting and timeout value for the current retry policy. 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_AzureStorageInitializeBlobUpload (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char *destinationFileName, char **uploadCorrelationId, char **azureBlobSasUri)
 This API creates a new upload within Azure IoT Hub, getting back a correlation-id and a SAS URI for the Blob upload to the Azure Storage associated with the Azure IoT Hub. More...
 
IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE IoTHubDeviceClient_AzureStorageCreateClient (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char *azureBlobSasUri)
 This API creates a client for a new blob upload to Azure Storage. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStoragePutBlock (IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle, uint32_t blockNumber, const uint8_t *dataPtr, size_t dataSize)
 This API uploads a single blob block to Azure Storage (performs a PUT BLOCK operation). More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStoragePutBlockList (IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle)
 This API performs an Azure Storage PUT BLOCK LIST operation. More...
 
void IoTHubDeviceClient_AzureStorageDestroyClient (IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle)
 This API destroys an instance previously created with IoTHubDeviceClient_AzureStorageCreateClient. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion (IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char *uploadCorrelationId, bool isSuccess, int responseCode, const char *responseMessage)
 This API notifies Azure IoT Hub of the upload completion. 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:

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_AzureStorageCreateClient()

IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE IoTHubDeviceClient_AzureStorageCreateClient ( IOTHUB_DEVICE_CLIENT_HANDLE  iotHubClientHandle,
const char *  azureBlobSasUri 
)

This API creates a client for a new blob upload to Azure Storage.

Remarks
It is part of a set of functions for more granular control over Azure IoT-based blob uploads. This function is expected to be used along with: IoTHubDeviceClient_AzureStorageCreateClient IoTHubDeviceClient_AzureStoragePutBlock IoTHubDeviceClient_AzureStoragePutBlockList IoTHubDeviceClient_AzureStorageDestroyClient IoTHubDeviceClient_AzureStorageInitializeBlobUpload IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_UploadToBlobAsync or IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync.
Parameters
iotHubClientHandleThe handle created by a call to the create function.
azureBlobSasUriThe Azure Storage Blob SAS uri obtained with IoTHubDeviceClient_AzureStorageInitializeBlobUpload.
Warning
This is a synchronous/blocking function.
Returns
A IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE on success or NULL if the function fails.

◆ IoTHubDeviceClient_AzureStorageDestroyClient()

void IoTHubDeviceClient_AzureStorageDestroyClient ( IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE  azureStorageClientHandle)

This API destroys an instance previously created with IoTHubDeviceClient_AzureStorageCreateClient.

Remarks
It is part of a set of functions for more granular control over Azure IoT-based blob uploads. This function is expected to be used along with: IoTHubDeviceClient_AzureStorageCreateClient IoTHubDeviceClient_AzureStoragePutBlock IoTHubDeviceClient_AzureStoragePutBlockList IoTHubDeviceClient_AzureStorageDestroyClient IoTHubDeviceClient_AzureStorageInitializeBlobUpload IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_UploadToBlobAsync or IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync.
Parameters
azureStorageClientHandleThe handle created with IoTHubDeviceClient_AzureStorageCreateClient.
Warning
This is a synchronous/blocking function.
Returns
Nothing.

◆ IoTHubDeviceClient_AzureStorageInitializeBlobUpload()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStorageInitializeBlobUpload ( IOTHUB_DEVICE_CLIENT_HANDLE  iotHubClientHandle,
const char *  destinationFileName,
char **  uploadCorrelationId,
char **  azureBlobSasUri 
)

This API creates a new upload within Azure IoT Hub, getting back a correlation-id and a SAS URI for the Blob upload to the Azure Storage associated with the Azure IoT Hub.

Remarks
It is part of a set of functions for more granular control over Azure IoT-based blob uploads. This function is expected to be used along with: IoTHubDeviceClient_AzureStorageCreateClient IoTHubDeviceClient_AzureStoragePutBlock IoTHubDeviceClient_AzureStoragePutBlockList IoTHubDeviceClient_AzureStorageDestroyClient IoTHubDeviceClient_AzureStorageInitializeBlobUpload IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_UploadToBlobAsync or IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync.
Parameters
iotHubClientHandleThe handle created by a call to the create function.
destinationFileNameName of the file in blob storage.
uploadCorrelationIdVariable where to store the correlation-id of the new upload.
azureBlobSasUriVariable where to store the Azure Storage SAS URI for the new upload.
Warning
This is a synchronous/blocking function. uploadCorrelationId and azureBlobSasUri must be freed by the calling application after the blob upload process is done (e.g., after calling IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion).
Returns
An IOTHUB_CLIENT_RESULT value indicating the success or failure of the API call.

◆ IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion ( IOTHUB_DEVICE_CLIENT_HANDLE  iotHubClientHandle,
const char *  uploadCorrelationId,
bool  isSuccess,
int  responseCode,
const char *  responseMessage 
)

This API notifies Azure IoT Hub of the upload completion.

Remarks
It is part of a set of functions for more granular control over Azure IoT-based blob uploads. This function is expected to be used along with: IoTHubDeviceClient_AzureStorageCreateClient IoTHubDeviceClient_AzureStoragePutBlock IoTHubDeviceClient_AzureStoragePutBlockList IoTHubDeviceClient_AzureStorageDestroyClient IoTHubDeviceClient_AzureStorageInitializeBlobUpload IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_UploadToBlobAsync or IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync. If this function fails (due to any HTTP error to either Azure Storage or Azure IoT Hub) it can be run again for a discretionary number of times in an attempt to succeed after, for example, an internet connectivity disruption is over.
Parameters
azureStorageClientHandleThe handle created with IoTHubDeviceClient_AzureStorageCreateClient.
uploadCorrelationIdUpload correlation-id obtained with IoTHubDeviceClient_AzureStorageInitializeBlobUpload.
isSuccessA boolean value indicating if the call(s) to IoTHubDeviceClient_AzureStoragePutBlock succeeded.
responseCodeAn user-defined code to signal the status of the upload (e.g., 200 for success, or -1 for abort).
responseMessageAn user-defined status message to go along with responseCode on the notification to Azure IoT Hub.
Warning
This is a synchronous/blocking function.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_AzureStoragePutBlock()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStoragePutBlock ( IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE  azureStorageClientHandle,
uint32_t  blockNumber,
const uint8_t *  dataPtr,
size_t  dataSize 
)

This API uploads a single blob block to Azure Storage (performs a PUT BLOCK operation).

Remarks
It is part of a set of functions for more granular control over Azure IoT-based blob uploads. This function is expected to be used along with: IoTHubDeviceClient_AzureStorageCreateClient IoTHubDeviceClient_AzureStoragePutBlock IoTHubDeviceClient_AzureStoragePutBlockList IoTHubDeviceClient_AzureStorageDestroyClient IoTHubDeviceClient_AzureStorageInitializeBlobUpload IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_UploadToBlobAsync or IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync. For more information about Azure Storage PUT BLOCK, its parameters and behavior, please refer to https://learn.microsoft.com/en-us/rest/api/storageservices/put-block
Parameters
azureStorageClientHandleThe handle created with IoTHubDeviceClient_AzureStorageCreateClient.
blockNumberNumber of the block being uploaded.
dataPtrPointer to the block data to be uploaded to Azure Storage blob.
dataSizeSize of the block data pointed by dataPtr.
Warning
This is a synchronous/blocking function.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_AzureStoragePutBlockList()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_AzureStoragePutBlockList ( IOTHUB_CLIENT_AZURE_STORAGE_CLIENT_HANDLE  azureStorageClientHandle)

This API performs an Azure Storage PUT BLOCK LIST operation.

Remarks
It is part of a set of functions for more granular control over Azure IoT-based blob uploads. This function is expected to be used along with: IoTHubDeviceClient_AzureStorageCreateClient IoTHubDeviceClient_AzureStoragePutBlock IoTHubDeviceClient_AzureStoragePutBlockList IoTHubDeviceClient_AzureStorageDestroyClient IoTHubDeviceClient_AzureStorageInitializeBlobUpload IoTHubDeviceClient_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_UploadToBlobAsync or IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync. If this function fails (due to any HTTP error to Azure Storage) it can be run again for a discretionary number of times in an attempt to succeed after, for example, an internet connectivity disruption is over. For more information about Azure Storage PUT BLOCK LIST, please refer to https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-list
Parameters
azureStorageClientHandleThe handle created with IoTHubDeviceClient_AzureStorageCreateClient.
Warning
This is a synchronous/blocking function.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ 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
configPointer 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
connectionStringPointer to a character string
protocolFunction 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_uriPointer to an ioThub hostname received in the registration process
device_idPointer to the device Id of the device
protocolFunction 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
transportHandleTRANSPORT_HANDLE which represents a connection.
configPointer 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
iotHubClientHandleThe 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
iotHubClientHandleThe handle created by a call to the create function.
methodIdThe methodId of the Device Method callback.
responseThe response data for the method callback.
response_sizeThe size of the response data buffer.
statusCodeThe 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
iotHubClientHandleThe handle created by a call to the create function.
lastMessageReceiveTimeOut 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]iotHubClientHandleThe handle created by a call to the create function.
[in]propertyUpdateCallbackCallback 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]userContextCallbackUser 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]iotHubClientHandleThe handle created by a call to the create function.
[in]propertyCallbackCallback invoked when properties are retrieved. The API IoTHubClient_Deserialize_Properties() can help deserialize the raw payload stream.
[in]userContextCallbackUser 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 
)

Gets the Retry Policy setting and timeout value for the current retry policy.

Parameters
iotHubClientHandleThe handle created by a call to the create function.
retryPolicyOut parameter containing the policy to use to reconnect to IoT Hub.
retryTimeoutLimitInSecondsOut parameter containing maximum amount of time, in seconds, to attempt reconnection to IOT Hub for the specified retry policy.
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
iotHubClientHandleThe handle created by a call to the create function.
iotHubClientStatusThe 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
iotHubClientHandleThe handle created by a call to the create function.
deviceTwinCallbackThe 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.
userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
eventMessageHandleThe handle to an IoT Hub message.
eventConfirmationCallbackThe 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.
userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to a create function.
messageThe cloud-to-device message received through the callback provided to IoTHubDeviceClient_SetMessageCallback.
dispositionAcknowledgement 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]iotHubClientHandleThe handle created by a call to the create function.
[in]propertiesSerialized 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]propertiesLengthNumber of bytes in the properties buffer.
[in]propertyAcknowledgedCallbackOptional callback specified by the application to be called with the result of the transaction.
[in]userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
reportedStateThe current device property values to be 'reported' to the IoT Hub.
sizeNumber of bytes in reportedState.
reportedStateCallbackThe callback specified by the device client to be called with the result of the transaction.
userContextCallbackUser 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]iotHubClientHandleThe handle created by a call to the create function.
[in]telemetryMessageHandleThe handle to an IoT Hub message.
[in]telemetryConfirmationCallbackOptional callback specified by the device for receiving confirmation of the delivery of the telemetry.
[in]userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
connectionStatusCallbackThe callback specified by the device for receiving updates about the status of the connection to IoT Hub.
userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
deviceMethodCallbackThe callback which will be called by IoT Hub.
userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
deviceTwinCallbackThe 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:
userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
messageCallbackThe callback specified by the device for receiving messages from IoT Hub.
userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the create function.
optionNameName of the option.
valueThe 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 the Retry Policy feature to control how immediatelly and frequently the SDK will attempt to re-connect to the Azure IoT Hub in case a connection issue occurs.

Parameters
iotHubClientHandleThe handle created by a call to the create function.
retryPolicyThe policy to use to reconnect to IoT Hub when a connection drops.
retryTimeoutLimitInSecondsMaximum amount of time(seconds) to attempt reconnection when a connection drops to IOT Hub.
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]iotHubClientHandleThe handle created by a call to the create function.
[in]commandCallbackThe callback which will be called when a command request arrives.
[in]userContextCallbackUser 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
iotHubClientHandleThe handle created by a call to the IoTHubDeviceClient_Create function.
destinationFileNameThe name of the file to be created in Azure Blob Storage.
getDataCallbackExA 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.
contextAny 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
iotHubClientHandleThe handle created by a call to the IoTHubDeviceClient_Create function.
destinationFileNameThe name of the file to be created in Azure Blob Storage.
sourceThe source of data.
sizeThe size of data.
iotHubClientFileUploadCallbackA callback to be invoked when the file upload operation has finished.
contextA user-provided context to be passed to the file upload callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.