Azure IoT C SDK
iothub_device_client_ll.h
Go to the documentation of this file.
1 // Copyright (c) Microsoft. All rights reserved.
2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3 
27 #ifndef IOTHUB_DEVICE_CLIENT_LL_H
28 #define IOTHUB_DEVICE_CLIENT_LL_H
29 
30 #include <stddef.h>
31 #include <stdint.h>
32 
33 #include "azure_macro_utils/macro_utils.h"
34 #include "umock_c/umock_c_prod.h"
35 
36 #include "iothub_transport_ll.h"
37 #include "iothub_client_core_ll.h"
38 
39 #ifdef __cplusplus
40 extern "C"
41 {
42 #endif
43 
49 typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HANDLE;
50 
51 #ifndef DONT_USE_UPLOADTOBLOB
56 #endif // DONT_USE_UPLOADTOBLOB
57 
58 
59 
75  IOTHUB_DEVICE_CLIENT_LL_HANDLE IoTHubDeviceClient_LL_CreateFromConnectionString( const char* connectionString, IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol);
113  IOTHUB_DEVICE_CLIENT_LL_HANDLE IoTHubDeviceClient_LL_CreateFromDeviceAuth( const char* iothub_uri, const char* device_id, IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol);
146  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendEventAsync( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_MESSAGE_HANDLE eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK eventConfirmationCallback, void* userContextCallback);
211 
225  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_GetRetryPolicy( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_CLIENT_RETRY_POLICY* retryPolicy, size_t* retryTimeoutLimitInSeconds);
266  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetOption( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char* optionName, const void* value);
300  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);
336  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_DeviceMethodResponse( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, METHOD_HANDLE methodId, const unsigned char* response, size_t respSize, int statusCode);
337 #ifndef DONT_USE_UPLOADTOBLOB
352  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_UploadToBlob( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char* destinationFileName, const unsigned char* source, size_t size);
392  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStorageInitializeBlobUpload( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char* destinationFileName, char** uploadCorrelationId, char** azureBlobSasUri);
434  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStoragePutBlock( IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle, uint32_t blockNumber, const uint8_t* dataPtr, size_t dataSize);
498  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStorageNotifyBlobUploadCompletion( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char* uploadCorrelationId, bool isSuccess, int responseCode, const char* responseMessage);#endif /*DONT_USE_UPLOADTOBLOB*/
499 
538  IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SendTelemetryAsync( IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, IOTHUB_MESSAGE_HANDLE telemetryMessageHandle, IOTHUB_CLIENT_TELEMETRY_CALLBACK telemetryConfirmationCallback, void* userContextCallback);
571  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);
605 #ifdef __cplusplus
606 }
607 #endif
608 
609 #endif /* IOTHUB_DEVICE_CLIENT_LL_H */
void(* IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK)(int statusCode, void *userContextCallback)
Function callback application implements to receive acknowledgements of properties sent from the clie...
Definition: iothub_client_core_common.h:381
IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_RESULT(* IOTHUB_CLIENT_FILE_UPLOAD_GET_DATA_CALLBACK_EX)(IOTHUB_CLIENT_FILE_UPLOAD_RESULT result, unsigned char const **data, size_t *size, void *context)
Signature of the callback that the application implements to process IoT Hub client SDK requesting ad...
Definition: iothub_client_core_common.h:260
void(* IOTHUB_CLIENT_TELEMETRY_CALLBACK)(IOTHUB_CLIENT_CONFIRMATION_RESULT result, void *userContextCallback)
Function callback application implements to receive notifications when IoT Hub acknowledges telemetry...
Definition: iothub_client_core_common.h:370
void(* IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK)(DEVICE_TWIN_UPDATE_STATE update_state, const unsigned char *payLoad, size_t size, void *userContextCallback)
Signature of the callback that the application implements to process data received from an IoT Hub de...
Definition: iothub_client_core_common.h:201
IOTHUB_CLIENT_RETRY_POLICY
Enumeration specifying the retry strategy the IoT Hub client should use.
Definition: iothub_client_core_common.h:63
void(* IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC)(const IOTHUB_CLIENT_COMMAND_REQUEST *commandRequest, IOTHUB_CLIENT_COMMAND_RESPONSE *commandResponse, void *userContextCallback)
Function callback application implements to process an incoming command from IoT Hub.
Definition: iothub_client_core_common.h:358
void(* IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK)(IOTHUB_CLIENT_CONFIRMATION_RESULT result, void *userContextCallback)
Signature of the callback that the application implements to process acknowledgement or failures when...
Definition: iothub_client_core_common.h:170
IOTHUBMESSAGE_DISPOSITION_RESULT
Enumeration returned by application callbacks that receive cloud-to-device messages.
Definition: iothub_client_core_common.h:81
void(* IOTHUB_CLIENT_REPORTED_STATE_CALLBACK)(int status_code, void *userContextCallback)
Signature of the callback that the application implements to receive notifications of device or modul...
Definition: iothub_client_core_common.h:209
int(* IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC)(const char *method_name, const unsigned char *payload, size_t size, unsigned char **response, size_t *response_size, void *userContextCallback)
Signature of the callback that the application implements to receive incoming device or module method...
Definition: iothub_client_core_common.h:227
void(* IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK)(IOTHUB_CLIENT_PROPERTY_PAYLOAD_TYPE payloadType, const unsigned char *payload, size_t payloadLength, void *userContextCallback)
Function callback application implements to process properties received from IoT Hub.
Definition: iothub_client_core_common.h:392
void(* IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK)(IOTHUB_CLIENT_CONNECTION_STATUS result, IOTHUB_CLIENT_CONNECTION_STATUS_REASON reason, void *userContextCallback)
Signature of the callback that the application implements to process connection status changes betwee...
Definition: iothub_client_core_common.h:179
IOTHUBMESSAGE_DISPOSITION_RESULT(* IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC)(IOTHUB_MESSAGE_HANDLE message, void *userContextCallback)
Signature of the callback that the application implements to process incoming cloud-to-device message...
Definition: iothub_client_core_common.h:189
struct IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_STRUCT * IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE
Definition: iothub_client_core_common.h:38
IOTHUB_CLIENT_RESULT
Enumeration specifying the status of calls to IoT Hub client.
Definition: iothub_client_core_common.h:42
IOTHUB_CLIENT_STATUS
Enumeration returned by the GetSendStatus family of APIs (e.g. IoTHubDeviceClient_LL_GetSendStatus())...
Definition: iothub_client_core_common.h:73
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.
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 func...
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.
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.
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 blo...
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).
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.
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....
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.
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.
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.
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.
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 st...
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.
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.
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_AzureStoragePutBlockList(IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle)
This API performs an Azure Storage PUT BLOCK LIST operation.
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 proper...
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 bl...
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...
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,...
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.
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.
void IoTHubDeviceClient_LL_AzureStorageDestroyClient(IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE azureStorageClientHandle)
This API destroys an instance previously created with IoTHubDeviceClient_LL_AzureStorageCreateClient ...
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 t...
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 a...
IOTHUB_CLIENT_LL_UPLOADTOBLOB_CONTEXT_HANDLE IOTHUB_CLIENT_LL_AZURE_STORAGE_CLIENT_HANDLE
Handle for Upload-to-Blob API Functions.
Definition: iothub_device_client_ll.h:55
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.
struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG * IOTHUB_DEVICE_CLIENT_LL_HANDLE
Handle corresponding to a lower layer (LL) device client instance.
Definition: iothub_device_client_ll.h:49
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.
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...
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.
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.
void IoTHubDeviceClient_LL_Destroy(IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle)
Disposes of resources allocated by the IoT Hub client. This is a blocking call.
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...
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....
struct IOTHUB_MESSAGE_HANDLE_DATA_TAG * IOTHUB_MESSAGE_HANDLE
Handle representing an IoT Hub message.
Definition: iothub_message.h:32
This struct specifies IoT Hub client configuration.
Definition: iothub_client_core_common.h:264
This struct specifies IoT Hub client device configuration.
Definition: iothub_client_core_common.h:294