Azure IoT C SDK
Typedefs | Functions
iothub_device_client_ll.h File Reference

APIs that allow a user (usually a device) to communicate with an Azure IoT Hub. More...

#include <stddef.h>
#include <stdint.h>
#include "azure_macro_utils/macro_utils.h"
#include "umock_c/umock_c_prod.h"
#include "iothub_transport_ll.h"
#include "iothub_client_core_ll.h"

Go to the source code of this file.

Typedefs

typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG * IOTHUB_DEVICE_CLIENT_LL_HANDLE
 Handle corresponding to a lower layer (LL) device client instance. More...
 
typedef IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE
 Handle for Upload-to-Blob API Functions.
 

Functions

IOTHUB_DEVICE_CLIENT_LL_HANDLE IoTHubDeviceClient_LL_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_LL_HANDLE IoTHubDeviceClient_LL_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_LL_HANDLE IoTHubDeviceClient_LL_CreateWithTransport (const IOTHUB_CLIENT_DEVICE_CONFIG *config)
 Creates a IoT Hub client for communication with an existing IoT Hub using an existing transport. More...
 
IOTHUB_DEVICE_CLIENT_LL_HANDLE IoTHubDeviceClient_LL_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_LL_Destroy (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle)
 Disposes of resources allocated by the IoT Hub client. This is a blocking call. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendEventAsync (IOTHUB_DEVICE_CLIENT_LL_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_LL_GetSendStatus (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_CLIENT_STATUS *iotHubClientStatus)
 This function returns the current sending status for IoTHubClient. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetMessageCallback (IOTHUB_DEVICE_CLIENT_LL_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_LL_SetConnectionStatusCallback (IOTHUB_DEVICE_CLIENT_LL_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_LL_SetRetryPolicy (IOTHUB_DEVICE_CLIENT_LL_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_LL_GetRetryPolicy (IOTHUB_DEVICE_CLIENT_LL_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_LL_GetLastMessageReceiveTime (IOTHUB_DEVICE_CLIENT_LL_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...
 
void IoTHubDeviceClient_LL_DoWork (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle)
 This function MUST be called by the user so work (sending/receiving data on the network, computing and enforcing timeout controls, managing the connection to the IoT Hub) can be done by the IoTHubClient. The recommended call frequency is at least once every 100 milliseconds. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetOption (IOTHUB_DEVICE_CLIENT_LL_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_LL_SetDeviceTwinCallback (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK deviceTwinCallback, void *userContextCallback)
 This API specifies a callback to be used when the device receives a desired state update. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendReportedState (IOTHUB_DEVICE_CLIENT_LL_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_LL_GetTwinAsync (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK deviceTwinCallback, void *userContextCallback)
 This API enabled the device to request the full device twin (with all the desired and reported properties) on demand. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetDeviceMethodCallback (IOTHUB_DEVICE_CLIENT_LL_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_LL_DeviceMethodResponse (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, METHOD_HANDLE methodId, const unsigned char *response, size_t respSize, int statusCode)
 This API responds to an asnyc method callback identified the methodId. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_UploadToBlob (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char *destinationFileName, const unsigned char *source, size_t size)
 This API uploads to Azure Storage the content pointed to by source having the size size under the blob name devicename/destinationFileName. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char *destinationFileName, IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX getDataCallbackEx, void *context)
 This API uploads to Azure Storage the content provided block by block by getDataCallback under the blob name devicename/destinationFileName. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStorageInitializeBlobUpload (IOTHUB_DEVICE_CLIENT_LL_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 access to the Azure Storage associated with the Azure IoT Hub. More...
 
IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE IoTHubDeviceClient_LL_AzureStorageCreateClient (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char *azureBlobSasUri)
 This API creates a client for a new blob upload to Azure Storage. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStoragePutBlock (IOTHUB_CLIENT_LL_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_LL_AzureStoragePutBlockList (IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle)
 This API performs an Azure Storage PUT BLOCK LIST operation. More...
 
void IoTHubDeviceClient_LL_AzureStorageDestroyClient (IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle)
 This API destroys an instance previously created with IoTHubDeviceClient_LL_AzureStorageCreateClient . More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion (IOTHUB_DEVICE_CLIENT_LL_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_LL_SendMessageDisposition (IOTHUB_DEVICE_CLIENT_LL_HANDLE device_ll_handle, 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_LL_SendTelemetryAsync (IOTHUB_DEVICE_CLIENT_LL_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_LL_SubscribeToCommands (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC commandCallback, void *userContextCallback)
 Subscribe to incoming commands from IoT Hub. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendPropertiesAsync (IOTHUB_DEVICE_CLIENT_LL_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_LL_GetPropertiesAsync (IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK propertyCallback, void *userContextCallback)
 Retrieves all device properties from IoT Hub. More...
 
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetPropertiesAndSubscribeToUpdatesAsync (IOTHUB_DEVICE_CLIENT_LL_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

APIs that allow a user (usually a device) to communicate with an Azure IoT Hub.

IoTHubDeviceClient_LL allows a user (usually a device) to communicate with an Azure IoT Hub. It can send events and receive messages. At any given moment in time there can only be at most 1 message callback function.

This API surface contains a set of APIs that allows the user to interact with the lower layer portion of the IoTHubClient. These APIs contain LL in their name, but retain the same functionality like the IoTHubDeviceClient_... APIs, with one difference. If the LL APIs are used then the user is responsible for scheduling when the actual work done by the IoTHubClient happens (when the data is sent/received on/from the network). This is useful for constrained devices where spinning a separate thread is often not desired.

Warning
IoTHubDeviceClient_LL_* functions are NOT thread safe. See https://github.com/Azure/azure-iot-sdk-c/blob/main/doc/threading_notes.md for more details.

Typedef Documentation

◆ IOTHUB_DEVICE_CLIENT_LL_HANDLE

typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HANDLE

Handle corresponding to a lower layer (LL) device client instance.

Warning
The API functions that use this handle are not thread safe. See https://github.com/Azure/azure-iot-sdk-c/blob/main/doc/threading_notes.md for more details.

Function Documentation

◆ IoTHubDeviceClient_LL_AzureStorageCreateClient()

IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE IoTHubDeviceClient_LL_AzureStorageCreateClient ( IOTHUB_DEVICE_CLIENT_LL_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_LL_AzureStoragePutBlock IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion IoTHubDeviceClient_LL_AzureStorageDestroyClient For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_LL_UploadToBlob or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob.
Parameters
iotHubClientHandleThe handle created by a call to the create function.
azureBlobSasUriThe Azure Storage Blob SAS uri obtained with IoTHubDeviceClient_LL_AzureStorageInitializeBlobUpload.
Warning
This is a synchronous/blocking function.
Returns
A IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE on success or NULL if the function fails.

◆ IoTHubDeviceClient_LL_AzureStorageDestroyClient()

void IoTHubDeviceClient_LL_AzureStorageDestroyClient ( IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE  azureStorageClientHandle)

This API destroys an instance previously created with IoTHubDeviceClient_LL_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_LL_AzureStorageCreateClient IoTHubDeviceClient_LL_AzureStoragePutBlock IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_LL_UploadToBlob or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob.
Parameters
azureStorageClientHandleThe handle created with IoTHubDeviceClient_LL_AzureStorageCreateClient.
Warning
This is a synchronous/blocking function.
Returns
Nothing.

◆ IoTHubDeviceClient_LL_AzureStorageInitializeBlobUpload()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStorageInitializeBlobUpload ( IOTHUB_DEVICE_CLIENT_LL_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 access 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_LL_AzureStoragePutBlock IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion IoTHubDeviceClient_LL_AzureStorageDestroyClient For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_LL_UploadToBlob or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob.
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. This function only attempts to send HTTP requests once, it does not retry in case of failure. Any retries must be explicitly implemented by the calling application. uploadCorrelationId and azureBlobSasUri must be freed by the calling application after the blob upload process is done (e.g., after calling IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion).
Returns
An IOTHUB_CLIENT_RESULT value indicating the success or failure of the API call.

◆ IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion ( IOTHUB_DEVICE_CLIENT_LL_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_LL_AzureStorageCreateClient IoTHubDeviceClient_LL_AzureStoragePutBlock IoTHubDeviceClient_LL_AzureStorageDestroyClient For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_LL_UploadToBlob or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob. 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_LL_AzureStorageCreateClient.
uploadCorrelationIdUpload correlation-id obtained with IoTHubDeviceClient_LL_AzureStorageInitializeBlobUpload.
isSuccessA boolean value indicating if the call(s) to IoTHubDeviceClient_LL_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. This function only attempts to send HTTP requests once, it does not retry in case of failure. Any retries must be explicitly implemented by the calling application.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_AzureStoragePutBlock()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStoragePutBlock ( IOTHUB_CLIENT_LL_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_LL_AzureStorageCreateClient IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion IoTHubDeviceClient_LL_AzureStorageDestroyClient For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_LL_UploadToBlob or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob. 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_LL_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. This function only attempts to send HTTP requests once, it does not retry in case of failure. Any retries must be explicitly implemented by the calling application.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_AzureStoragePutBlockList()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStoragePutBlockList ( IOTHUB_CLIENT_LL_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_LL_AzureStorageCreateClient IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion IoTHubDeviceClient_LL_AzureStorageDestroyClient For simpler/less-granular control of uploads to Azure blob storage please use either IoTHubDeviceClient_LL_UploadToBlob or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob. 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_LL_AzureStorageCreateClient.
Warning
This is a synchronous/blocking function. This function only attempts to send HTTP requests once, it does not retry in case of failure. Any retries must be explicitly implemented by the calling application.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_Create()

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

◆ IoTHubDeviceClient_LL_CreateFromConnectionString()

IOTHUB_DEVICE_CLIENT_LL_HANDLE IoTHubDeviceClient_LL_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>
           </blockquote>
Returns
A non-NULL IOTHUB_DEVICE_CLIENT_LL_HANDLE value that is used when invoking other functions for IoT Hub client and NULL on failure.

◆ IoTHubDeviceClient_LL_CreateFromDeviceAuth()

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

◆ IoTHubDeviceClient_LL_CreateWithTransport()

IOTHUB_DEVICE_CLIENT_LL_HANDLE IoTHubDeviceClient_LL_CreateWithTransport ( const IOTHUB_CLIENT_DEVICE_CONFIG config)

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

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

◆ IoTHubDeviceClient_LL_Destroy()

void IoTHubDeviceClient_LL_Destroy ( IOTHUB_DEVICE_CLIENT_LL_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_LL_DeviceMethodResponse()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_DeviceMethodResponse ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  iotHubClientHandle,
METHOD_HANDLE  methodId,
const unsigned char *  response,
size_t  respSize,
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.
respSizeThe 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_LL_DoWork()

void IoTHubDeviceClient_LL_DoWork ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  iotHubClientHandle)

This function MUST be called by the user so work (sending/receiving data on the network, computing and enforcing timeout controls, managing the connection to the IoT Hub) can be done by the IoTHubClient. The recommended call frequency is at least once every 100 milliseconds.

Parameters
iotHubClientHandleThe 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.
Warning
Do not call this function from inside any application callbacks from this SDK, e.g. your IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK handler.

◆ IoTHubDeviceClient_LL_GetLastMessageReceiveTime()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetLastMessageReceiveTime ( IOTHUB_DEVICE_CLIENT_LL_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_LL_GetPropertiesAndSubscribeToUpdatesAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetPropertiesAndSubscribeToUpdatesAsync ( IOTHUB_DEVICE_CLIENT_LL_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_LL_Destroy function from within any callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_GetPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetPropertiesAsync ( IOTHUB_DEVICE_CLIENT_LL_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_LL_Destroy function from within any callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_GetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetRetryPolicy ( IOTHUB_DEVICE_CLIENT_LL_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
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.
Warning
: Do not call IoTHubDeviceClient_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_GetSendStatus()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetSendStatus ( IOTHUB_DEVICE_CLIENT_LL_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_LL_UploadToBlob() or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob().
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_GetTwinAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetTwinAsync ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  iotHubClientHandle,
IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK  deviceTwinCallback,
void *  userContextCallback 
)

This API enabled the device to request the full device twin (with all the desired and reported properties) on demand.

Parameters
iotHubClientHandleThe handle created by a call to the create function.
deviceTwinCallbackThe callback specified by the device client to receive the Twin document.
userContextCallbackUser specified context that will be provided to the callback. This can be NULL.
Warning
: Do not call IoTHubDeviceClient_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_SendEventAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendEventAsync ( IOTHUB_DEVICE_CLIENT_LL_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_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.
userContextCallbackUser specified context that will be provided to the callback. This can be NULL.
Warning
: Do not call IoTHubDeviceClient_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() 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_LL_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_LL_SendMessageDisposition()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendMessageDisposition ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  device_ll_handle,
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
device_ll_handleThe handle created by a call to a create function.
messageThe cloud-to-device message received through the callback provided to IoTHubDeviceClient_LL_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_LL_SendPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendPropertiesAsync ( IOTHUB_DEVICE_CLIENT_LL_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_LL_Destroy function from within any callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_SendReportedState()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendReportedState ( IOTHUB_DEVICE_CLIENT_LL_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_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_SendTelemetryAsync()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendTelemetryAsync ( IOTHUB_DEVICE_CLIENT_LL_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_LL_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_LL_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_LL_SetConnectionStatusCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetConnectionStatusCallback ( IOTHUB_DEVICE_CLIENT_LL_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_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Remarks
Callback specified will not receive connection status change notifications for upload connections created with IoTHubDeviceClient_LL_UploadToBlob() or IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob().
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_SetDeviceMethodCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetDeviceMethodCallback ( IOTHUB_DEVICE_CLIENT_LL_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_LL_SetDeviceTwinCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetDeviceTwinCallback ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  iotHubClientHandle,
IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK  deviceTwinCallback,
void *  userContextCallback 
)

This API specifies a callback to be used when the device receives a desired 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 patch 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_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_SetMessageCallback()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetMessageCallback ( IOTHUB_DEVICE_CLIENT_LL_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_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_SetOption()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetOption ( IOTHUB_DEVICE_CLIENT_LL_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_LL_SetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetRetryPolicy ( IOTHUB_DEVICE_CLIENT_LL_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
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.
Warning
: Do not call IoTHubDeviceClient_LL_Destroy() or IoTHubDeviceClient_LL_DoWork() from inside your application's callback.
Remarks
Uploads initiated by IoTHubDeviceClient_LL_UploadToBlob() or IoTHubDeviceClient_LL_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_LL_SubscribeToCommands()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SubscribeToCommands ( IOTHUB_DEVICE_CLIENT_LL_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_LL_UploadMultipleBlocksToBlob()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  iotHubClientHandle,
const char *  destinationFileName,
IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX  getDataCallbackEx,
void *  context 
)

This API uploads to Azure Storage the content provided block by block by getDataCallback under the blob name devicename/destinationFileName.

Parameters
iotHubClientHandleThe handle created by a call to the create function.
destinationFileNamename of the file.
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.
Warning
Other LL functions such as IoTHubDeviceClient_LL_SendEventAsync() queue work to be performed later and do not block. IoTHubDeviceClient_LL_UploadMultipleBlocksToBlob will block however until the upload is completed or fails, which may take a while.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubDeviceClient_LL_UploadToBlob()

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_UploadToBlob ( IOTHUB_DEVICE_CLIENT_LL_HANDLE  iotHubClientHandle,
const char *  destinationFileName,
const unsigned char *  source,
size_t  size 
)

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

Parameters
iotHubClientHandleThe handle created by a call to the create function.
destinationFileNamename of the file.
sourcepointer to the source for file content (can be NULL)
sizethe size of the source in memory (if source is NULL then size needs to be 0).
Warning
Other LL functions such as IoTHubDeviceClient_LL_SendEventAsync() queue work to be performed later and do not block. IoTHubDeviceClient_LL_UploadToBlob will block however until the upload is completed or fails, which may take a while.
Returns
IOTHUB_CLIENT_OK upon success or an error code upon failure.