Extends the IoTHubModuleClient_LL module with additional features. More...

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

Typedefs
typedef IOTHUB_CLIENT_CORE_HANDLE	IOTHUB_MODULE_CLIENT_HANDLE
	Handle corresponding to a convenience layer module client instance. More...

Functions
IOTHUB_MODULE_CLIENT_HANDLE	IoTHubModuleClient_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_Destroy (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle)
	Disposes of resources allocated by the IoT Hub client. This is a blocking call. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_SendEventAsync (IOTHUB_MODULE_CLIENT_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_GetSendStatus (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_STATUS *IoTHubClientStatus)
	This function returns the current sending status for IoTHubModuleClient. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_SetMessageCallback (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle, 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	IoTHubModuleClient_SetConnectionStatusCallback (IOTHUB_MODULE_CLIENT_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_SetRetryPolicy (IOTHUB_MODULE_CLIENT_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_GetRetryPolicy (IOTHUB_MODULE_CLIENT_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_GetLastMessageReceiveTime (IOTHUB_MODULE_CLIENT_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...

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

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

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_GetTwinAsync (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK moduleTwinCallback, void *userContextCallback)
	This API provides a way to retrieve the complete module Twin properties on-demand. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_SetModuleMethodCallback (IOTHUB_MODULE_CLIENT_HANDLE IoTHubClientHandle, IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC methodCallback, void *userContextCallback)
	This API sets callback for async cloud to module method call. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_SendEventToOutputAsync (IOTHUB_MODULE_CLIENT_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_SetInputMessageCallback (IOTHUB_MODULE_CLIENT_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_SendEventToOutputAsync) More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_SendMessageDisposition (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle, 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_SendTelemetryAsync (IOTHUB_MODULE_CLIENT_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_SubscribeToCommands (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_COMMAND_CALLBACK_ASYNC commandCallback, void *userContextCallback)
	Subscribe to incoming commands from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_SendPropertiesAsync (IOTHUB_MODULE_CLIENT_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_GetPropertiesAsync (IOTHUB_MODULE_CLIENT_HANDLE iotHubModuleClientHandle, IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK propertyCallback, void *userContextCallback)
	Retrieves all module properties from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubModuleClient_GetPropertiesAndSubscribeToUpdatesAsync (IOTHUB_MODULE_CLIENT_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

Extends the IoTHubModuleClient_LL module with additional features.

IoTHubModuleClient extends the IoTHubModuleClient_LL with 2 features:

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

Typedef Documentation

◆ IOTHUB_MODULE_CLIENT_HANDLE

typedef IOTHUB_CLIENT_CORE_HANDLE IOTHUB_MODULE_CLIENT_HANDLE

Handle corresponding to a convenience layer module client instance.

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

Function Documentation

◆ IoTHubModuleClient_CreateFromConnectionString()

IOTHUB_MODULE_CLIENT_HANDLE IoTHubModuleClient_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>
              <pre>HostName=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net];DeviceId=[Device ID goes here];SharedAccessSignature=SharedAccessSignature sr=[IoT Hub name goes here].[IoT Hub suffix goes here, e.g., private.azure-devices-int.net]/devices/[Device ID goes here]&sig=[SAS Token goes here]&se=[Expiry Time goes here];ModuleId=[Module ID goes here]</pre>
           </blockquote>

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

◆ IoTHubModuleClient_Destroy()

void IoTHubModuleClient_Destroy ( IOTHUB_MODULE_CLIENT_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_GetLastMessageReceiveTime()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_GetLastMessageReceiveTime	(	IOTHUB_MODULE_CLIENT_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_GetPropertiesAndSubscribeToUpdatesAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_GetPropertiesAndSubscribeToUpdatesAsync	(	IOTHUB_MODULE_CLIENT_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_Destroy function from within any callback.

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

◆ IoTHubModuleClient_GetPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_GetPropertiesAsync	(	IOTHUB_MODULE_CLIENT_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_Destroy function from within any callback.

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

◆ IoTHubModuleClient_GetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_GetRetryPolicy	(	IOTHUB_MODULE_CLIENT_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_GetSendStatus()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_GetSendStatus	(	IOTHUB_MODULE_CLIENT_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_GetTwinAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_GetTwinAsync	(	IOTHUB_MODULE_CLIENT_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK	moduleTwinCallback,
		void *	userContextCallback
	)

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

Parameters

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

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

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

◆ IoTHubModuleClient_SendEventAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SendEventAsync	(	IOTHUB_MODULE_CLIENT_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_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_Destroy() from inside your application's callback.

Remarks: The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function, so this argument can be destroyed by the calling application right after IoTHubModuleClient_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_SendEventToOutputAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SendEventToOutputAsync	(	IOTHUB_MODULE_CLIENT_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_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_Destroy() from inside your application's callback.

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

◆ IoTHubModuleClient_SendMessageDisposition()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SendMessageDisposition	(	IOTHUB_MODULE_CLIENT_HANDLE	iotHubModuleClientHandle,
		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

iotHubModuleClientHandle	The handle created by a call to a create function.
message	The cloud-to-device message received through the callback provided to IoTHubModuleClient_SetMessageCallback or IoTHubModuleClient_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_SendPropertiesAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SendPropertiesAsync	(	IOTHUB_MODULE_CLIENT_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_Destroy function from within any callback.

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

◆ IoTHubModuleClient_SendReportedState()

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

This API sends 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_Destroy() from inside your application's callback.

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

◆ IoTHubModuleClient_SendTelemetryAsync()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SendTelemetryAsync	(	IOTHUB_MODULE_CLIENT_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_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_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_SetConnectionStatusCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetConnectionStatusCallback	(	IOTHUB_MODULE_CLIENT_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_Destroy() from inside your application's callback.

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

◆ IoTHubModuleClient_SetInputMessageCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetInputMessageCallback	(	IOTHUB_MODULE_CLIENT_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_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_SetMessageCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetMessageCallback	(	IOTHUB_MODULE_CLIENT_HANDLE	iotHubModuleClientHandle,
		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

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

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

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

◆ IoTHubModuleClient_SetModuleMethodCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetModuleMethodCallback	(	IOTHUB_MODULE_CLIENT_HANDLE	IoTHubClientHandle,
		IOTHUB_CLIENT_DEVICE_METHOD_CALLBACK_ASYNC	methodCallback,
		void *	userContextCallback
	)

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

Parameters

IoTHubClientHandle	The handle created by a call to the create function.
methodCallback	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_SetModuleTwinCallback()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetModuleTwinCallback	(	IOTHUB_MODULE_CLIENT_HANDLE	iotHubModuleClientHandle,
		IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK	moduleTwinCallback,
		void *	userContextCallback
	)

This API specifies a call back to be used when the module receives a 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 a request send by the IoT Hub services. The payload will be passed to the callback, along with two version numbers: Desired: LastSeenReported:
userContextCallback	User specified context that will be provided to the callback. This can be `NULL`.

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

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

◆ IoTHubModuleClient_SetOption()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetOption	(	IOTHUB_MODULE_CLIENT_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_SetRetryPolicy()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SetRetryPolicy	(	IOTHUB_MODULE_CLIENT_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_SubscribeToCommands()

IOTHUB_CLIENT_RESULT IoTHubModuleClient_SubscribeToCommands	(	IOTHUB_MODULE_CLIENT_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_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_HANDLE

Function Documentation

◆ IoTHubModuleClient_CreateFromConnectionString()

◆ IoTHubModuleClient_Destroy()

◆ IoTHubModuleClient_GetLastMessageReceiveTime()

◆ IoTHubModuleClient_GetPropertiesAndSubscribeToUpdatesAsync()

◆ IoTHubModuleClient_GetPropertiesAsync()

◆ IoTHubModuleClient_GetRetryPolicy()

◆ IoTHubModuleClient_GetSendStatus()

◆ IoTHubModuleClient_GetTwinAsync()

◆ IoTHubModuleClient_SendEventAsync()

◆ IoTHubModuleClient_SendEventToOutputAsync()

◆ IoTHubModuleClient_SendMessageDisposition()

◆ IoTHubModuleClient_SendPropertiesAsync()

◆ IoTHubModuleClient_SendReportedState()

◆ IoTHubModuleClient_SendTelemetryAsync()

◆ IoTHubModuleClient_SetConnectionStatusCallback()

◆ IoTHubModuleClient_SetInputMessageCallback()

◆ IoTHubModuleClient_SetMessageCallback()

◆ IoTHubModuleClient_SetModuleMethodCallback()

◆ IoTHubModuleClient_SetModuleTwinCallback()

◆ IoTHubModuleClient_SetOption()

◆ IoTHubModuleClient_SetRetryPolicy()

◆ IoTHubModuleClient_SubscribeToCommands()