APIs that allow a user to communicate with an Azure IoT Hub. More...

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

Typedefs
typedef struct IOTHUB_MODULE_CLIENT_LL_HANDLE_DATA_TAG *	IOTHUB_MODULE_CLIENT_LL_HANDLE
	Handle corresponding to a lower layer (LL) module client instance. More...

Functions
IOTHUB_MODULE_CLIENT_LL_HANDLE	IoTHubModuleClient_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...

void	IoTHubModuleClient_LL_Destroy (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle)
	Disposes of resources allocated by the IoT Hub client. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SendEventAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_GetSendStatus (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_STATUS *iotHubClientStatus)
	This function returns the current sending status for IoTHubModuleClient. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SetMessageCallback (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC messageCallback, void *userContextCallback)
	Sets up the message callback to be invoked when Edge issues a message to the module. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SetConnectionStatusCallback (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_SetRetryPolicy (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_GetRetryPolicy (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_GetLastMessageReceiveTime (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_DoWork (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle)
	This function is meant to be called by the user when work (sending/receiving) can be done by the IoTHubModuleClient. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SetOption (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_SetModuleTwinCallback (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK moduleTwinCallback, void *userContextCallback)
	This API specifies a call back to be used when the module receives a desired state update. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SendReportedState (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, const unsigned char reportedState, size_t size, IOTHUB_CLIENT_REPORTED_STATE_CALLBACK reportedStateCallback, void userContextCallback)
	This API sneds a report of the module's properties and their current values. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_GetTwinAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK deviceTwinCallback, void *userContextCallback)
	This API enabled the device to request the full module twin (with all the desired and reported properties) on demand. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SetModuleMethodCallback (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC moduleMethodCallback, void *userContextCallback)
	This API sets callback for async cloud to module method call. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SendEventToOutputAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_MESSAGE_HANDLE eventMessageHandle, const char outputName, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK eventConfirmationCallback, void userContextCallback)
	Asynchronous call to send the message specified by `eventMessageHandle`. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SetInputMessageCallback (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, const char inputName, IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC eventHandlerCallback, void userContextCallback)
	This API sets callback for method call that is directed to specified 'inputName' queue (e.g. messages from IoTHubModuleClient_LL_SendEventToOutputAsync) More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SendMessageDisposition (IOTHUB_MODULE_CLIENT_LL_HANDLE module_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	IoTHubModuleClient_LL_SendTelemetryAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_LL_SubscribeToCommands (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC commandCallback, void *userContextCallback)
	Subscribe to incoming commands from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_SendPropertiesAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, const unsigned char properties, size_t propertiesLength, IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK propertyAcknowledgedCallback, void userContextCallback)
	Sends module properties to IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_GetPropertiesAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK propertyCallback, void *userContextCallback)
	Retrieves all module properties from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_LL_GetPropertiesAndSubscribeToUpdatesAsync (IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK propertyUpdateCallback, void *userContextCallback)
	Retrieves all module properties from IoT Hub and also subscribes for updates to writable properties. More...

Detailed Description

APIs that allow a user to communicate with an Azure IoT Hub.

IoTHubModuleClient_LL allows a user 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 IoTHubModuleClient. These APIs contain LL in their name, but retain the same functionality like the IoTHubModuleClient_... APIs, with one difference. If the LL APIs are used then the user is responsible for scheduling when the actual work done by the IoTHubModuleClient 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: IoTHubModuleClient_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_MODULE_CLIENT_LL_HANDLE

typedef struct IOTHUB_MODULE_CLIENT_LL_HANDLE_DATA_TAG* IOTHUB_MODULE_CLIENT_LL_HANDLE

Handle corresponding to a lower layer (LL) module 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

◆ IoTHubModuleClient_LL_CreateFromConnectionString()

IOTHUB_MODULE_CLIENT_LL_HANDLE IoTHubModuleClient_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

connectionString Pointer to a character string

protocol

Function pointer for protocol implementation

       Sample connection string:
           <blockquote>
               <pre>HostName=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net];DeviceId=[Device ID goes here];SharedAccessKey=[Device key goes here];ModuleId=[Module ID goes here]</pre>
           </blockquote>

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

◆ IoTHubModuleClient_LL_Destroy()

void IoTHubModuleClient_LL_Destroy ( IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle )

Disposes of resources allocated by the IoT Hub client. This is a blocking call.

Parameters

iotHubModuleClientHandle The handle created by a call to the create function.

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

◆ IoTHubModuleClient_LL_DoWork()

void IoTHubModuleClient_LL_DoWork ( IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle )

This function is meant to be called by the user when work (sending/receiving) can be done by the IoTHubModuleClient.

Parameters

iotHubModuleClientHandle

The handle created by a call to the create function.

       All IoTHubModuleClient 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.

◆ IoTHubModuleClient_LL_GetLastMessageReceiveTime()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_GetLastMessageReceiveTime	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		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

iotHubModuleClientHandle	The handle created by a call to the create function.
lastMessageReceiveTime	Out parameter containing the value of `time` function when the last message was received.

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

◆ IoTHubModuleClient_LL_GetPropertiesAndSubscribeToUpdatesAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_GetPropertiesAndSubscribeToUpdatesAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK	propertyUpdateCallback,
		void *	userContextCallback
	)

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

Parameters

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

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

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

◆ IoTHubModuleClient_LL_GetPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_GetPropertiesAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK	propertyCallback,
		void *	userContextCallback
	)

Retrieves all module properties from IoT Hub.

Parameters

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

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

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

◆ IoTHubModuleClient_LL_GetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_GetRetryPolicy	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_RETRY_POLICY *	retryPolicy,
		size_t *	retryTimeoutLimitInSeconds
	)

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

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
retryPolicy	Out parameter containing the policy to use to reconnect to IoT Hub.
retryTimeoutLimitInSeconds	Out parameter containing maximum amount of time, in seconds, to attempt reconnection to IOT Hub for the specified retry policy.

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

◆ IoTHubModuleClient_LL_GetSendStatus()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_GetSendStatus	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_STATUS *	iotHubClientStatus
	)

This function returns the current sending status for IoTHubModuleClient.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
iotHubClientStatus	The sending state is populated at the address pointed at by this parameter. The value will be set to `IOTHUB_CLIENT_SEND_STATUS_IDLE` if there is currently no item to be sent and `IOTHUB_CLIENT_SEND_STATUS_BUSY` if there are.

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

◆ IoTHubModuleClient_LL_GetTwinAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_GetTwinAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK	deviceTwinCallback,
		void *	userContextCallback
	)

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

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
deviceTwinCallback	The callback specified by the module client to receive the Twin document.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_LL_DoWork() from inside your application's callback.

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

◆ IoTHubModuleClient_LL_SendEventAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SendEventAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_MESSAGE_HANDLE	eventMessageHandle,
		IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK	eventConfirmationCallback,
		void *	userContextCallback
	)

Asynchronous call to send the message specified by eventMessageHandle.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
eventMessageHandle	The handle to an IoT Hub message.
eventConfirmationCallback	The callback specified by the module for receiving confirmation of the delivery of the IoT Hub message. This callback can be expected to invoke the IoTHubModuleClient_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.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_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 IoTHubModuleClient_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.

◆ IoTHubModuleClient_LL_SendEventToOutputAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SendEventToOutputAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_MESSAGE_HANDLE	eventMessageHandle,
		const char *	outputName,
		IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK	eventConfirmationCallback,
		void *	userContextCallback
	)

Asynchronous call to send the message specified by eventMessageHandle.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
eventMessageHandle	The handle to an IoT Hub message.
outputName	The name of the queue to send the message to.
eventConfirmationCallback	The callback specified by the module for receiving confirmation of the delivery of the IoT Hub message. This callback can be expected to invoke the IoTHubModuleClient_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.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_LL_DoWork() from inside your application's callback.

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

◆ IoTHubModuleClient_LL_SendMessageDisposition()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SendMessageDisposition	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	module_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

module_ll_handle	The handle created by a call to a create function.
message	The cloud-to-device message received through the callback provided to IoTHubModuleClient_LL_SetMessageCallback or IoTHubModuleClient_LL_SetInputMessageCallback.
disposition	Acknowledgement option for the message.

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

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

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

◆ IoTHubModuleClient_LL_SendPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SendPropertiesAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		const unsigned char *	properties,
		size_t	propertiesLength,
		IOTHUB_CLIENT_PROPERTY_ACKNOWLEDGED_CALLBACK	propertyAcknowledgedCallback,
		void *	userContextCallback
	)

Sends module properties to IoT Hub.

Parameters

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

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

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

◆ IoTHubModuleClient_LL_SendReportedState()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SendReportedState	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		const unsigned char *	reportedState,
		size_t	size,
		IOTHUB_CLIENT_REPORTED_STATE_CALLBACK	reportedStateCallback,
		void *	userContextCallback
	)

This API sneds a report of the module's properties and their current values.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
reportedState	The current module property values to be 'reported' to the IoT Hub.
size	Number of bytes in `reportedState`.
reportedStateCallback	The callback specified by the module client to be called with the result of the transaction.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_LL_DoWork() from inside your application's callback.

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

◆ IoTHubModuleClient_LL_SendTelemetryAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SendTelemetryAsync	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_MESSAGE_HANDLE	telemetryMessageHandle,
		IOTHUB_CLIENT_TELEMETRY_CALLBACK	telemetryConfirmationCallback,
		void *	userContextCallback
	)

Asynchronous call to send the telemetry message specified by telemetryMessageHandle.

Parameters

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

Remarks: The application behavior is undefined if the user calls the IoTHubModuleClient_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 IoTHubModuleClient_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.

◆ IoTHubModuleClient_LL_SetConnectionStatusCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetConnectionStatusCallback	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		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

iotHubModuleClientHandle	The handle created by a call to the create function.
connectionStatusCallback	The callback specified by the module for receiving updates about the status of the connection to IoT Hub.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_LL_DoWork() from inside your application's callback.

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

◆ IoTHubModuleClient_LL_SetInputMessageCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetInputMessageCallback	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		const char *	inputName,
		IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC	eventHandlerCallback,
		void *	userContextCallback
	)

This API sets callback for method call that is directed to specified 'inputName' queue (e.g. messages from IoTHubModuleClient_LL_SendEventToOutputAsync)

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
inputName	The name of the queue to listen on for this moduleMethodCallback/userContextCallback.
eventHandlerCallback	The callback which will be called by IoT Hub.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

◆ IoTHubModuleClient_LL_SetMessageCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetMessageCallback	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC	messageCallback,
		void *	userContextCallback
	)

Sets up the message callback to be invoked when Edge issues a message to the module. This is a blocking call.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
messageCallback	The callback specified by the module for receiving messages from IoT Hub.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_LL_DoWork() from inside your application's callback.

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

◆ IoTHubModuleClient_LL_SetModuleMethodCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetModuleMethodCallback	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC	moduleMethodCallback,
		void *	userContextCallback
	)

This API sets callback for async cloud to module method call.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
moduleMethodCallback	The callback which will be called by IoT Hub.
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

◆ IoTHubModuleClient_LL_SetModuleTwinCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetModuleTwinCallback	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK	moduleTwinCallback,
		void *	userContextCallback
	)

This API specifies a call back to be used when the module receives a desired state update.

Parameters

iotHubModuleClientHandle	The handle created by a call to the create function.
moduleTwinCallback	The callback specified by the module 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:
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

Warning: : Do not call IoTHubModuleClient_LL_Destroy() or IoTHubModuleClient_LL_DoWork() from inside your application's callback.

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

◆ IoTHubModuleClient_LL_SetOption()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetOption	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		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

iotHubModuleClientHandle	The handle created by a call to the create function.
optionName	Name of the option.
value	The value.

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

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

◆ IoTHubModuleClient_LL_SetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SetRetryPolicy	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		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

iotHubModuleClientHandle	The handle created by a call to the create function.
retryPolicy	The policy to use to reconnect to IoT Hub when a connection drops.
retryTimeoutLimitInSeconds	Maximum amount of time(seconds) to attempt reconnection when a connection drops to IOT Hub.

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

◆ IoTHubModuleClient_LL_SubscribeToCommands()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_LL_SubscribeToCommands	(	IOTHUB_MODULE_CLIENT_LL_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC	commandCallback,
		void *	userContextCallback
	)

Subscribe to incoming commands from IoT Hub.

Parameters

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

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

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

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ IOTHUB_MODULE_CLIENT_LL_HANDLE

Function Documentation

◆ IoTHubModuleClient_LL_CreateFromConnectionString()

◆ IoTHubModuleClient_LL_Destroy()

◆ IoTHubModuleClient_LL_DoWork()

◆ IoTHubModuleClient_LL_GetLastMessageReceiveTime()

◆ IoTHubModuleClient_LL_GetPropertiesAndSubscribeToUpdatesAsync()

◆ IoTHubModuleClient_LL_GetPropertiesAsync()

◆ IoTHubModuleClient_LL_GetRetryPolicy()

◆ IoTHubModuleClient_LL_GetSendStatus()

◆ IoTHubModuleClient_LL_GetTwinAsync()

◆ IoTHubModuleClient_LL_SendEventAsync()

◆ IoTHubModuleClient_LL_SendEventToOutputAsync()

◆ IoTHubModuleClient_LL_SendMessageDisposition()

◆ IoTHubModuleClient_LL_SendPropertiesAsync()

◆ IoTHubModuleClient_LL_SendReportedState()

◆ IoTHubModuleClient_LL_SendTelemetryAsync()

◆ IoTHubModuleClient_LL_SetConnectionStatusCallback()

◆ IoTHubModuleClient_LL_SetInputMessageCallback()

◆ IoTHubModuleClient_LL_SetMessageCallback()

◆ IoTHubModuleClient_LL_SetModuleMethodCallback()

◆ IoTHubModuleClient_LL_SetModuleTwinCallback()

◆ IoTHubModuleClient_LL_SetOption()

◆ IoTHubModuleClient_LL_SetRetryPolicy()

◆ IoTHubModuleClient_LL_SubscribeToCommands()