az_iot_hub_client.h File Reference

Definition for the Azure IoT Hub client. More...

#include <azure/core/az_result.h>
#include <azure/core/az_span.h>
#include <azure/iot/az_iot_common.h>
#include <stdbool.h>
#include <stdint.h>
#include <azure/core/_az_cfg_prefix.h>
#include <azure/core/_az_cfg_suffix.h>

Go to the source code of this file.

Data Structures
struct	az_iot_hub_client_options
	Azure IoT Hub Client options. More...
struct	az_iot_hub_client
	Azure IoT Hub Client. More...
struct	az_iot_hub_client_c2d_request
	The Cloud-To-Device Request. More...
struct	az_iot_hub_client_method_request
	A method request received from IoT Hub. More...
struct	az_iot_hub_client_command_request
	A command request received from IoT Hub. More...
struct	az_iot_hub_client_twin_response
	Twin response. More...
struct	az_iot_hub_client_properties_message
	Properties message. More...

Macros
#define	AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH   "/$iothub/websocket"
	The HTTP URI Path necessary when connecting to IoT Hub using WebSockets.
#define	AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH_NO_X509_CLIENT_CERT    AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH "?iothub-no-client-cert=true"
	The HTTP URI Path necessary when connecting to IoT Hub using WebSockets without an X509 client certificate. More...
#define	AZ_IOT_HUB_CLIENT_C2D_SUBSCRIBE_TOPIC   "devices/+/messages/devicebound/#"
	The MQTT topic filter to subscribe to Cloud-to-Device requests. More...
#define	AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC   "$iothub/methods/POST/#"
	The MQTT topic filter to subscribe to method requests. More...
#define	AZ_IOT_HUB_CLIENT_COMMANDS_SUBSCRIBE_TOPIC   AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC
	The MQTT topic filter to subscribe to command requests. More...
#define	AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC   "$iothub/twin/res/#"
	The MQTT topic filter to subscribe to twin operation responses. More...
#define	AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC   "$iothub/twin/PATCH/properties/desired/#"
	Gets the MQTT topic filter to subscribe to twin desired property changes. More...
#define	AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_SUBSCRIBE_TOPIC    AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC
	The MQTT topic filter to subscribe to properties operation messages. More...
#define	AZ_IOT_HUB_CLIENT_PROPERTIES_WRITABLE_UPDATES_SUBSCRIBE_TOPIC    AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC
	Gets the MQTT topic filter to subscribe to desired properties changes. More...

Enumerations
enum	{   AZ_HTTP_REQUEST_URL_BUFFER_SIZE = 2 * 1024, AZ_HTTP_REQUEST_BODY_BUFFER_SIZE = 1024, AZ_LOG_MESSAGE_BUFFER_SIZE = 1024 , AZ_IOT_DEFAULT_MQTT_CONNECT_PORT = 8883,   AZ_IOT_DEFAULT_MQTT_CONNECT_KEEPALIVE_SECONDS = 240, AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_QOS = 0 }
	Azure IoT service MQTT bit field properties for telemetry publish messages. More...
enum	az_iot_hub_client_twin_response_type { AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_TYPE_GET = 1, AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_TYPE_DESIRED_PROPERTIES = 2, AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_TYPE_REPORTED_PROPERTIES = 3, AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_TYPE_REQUEST_ERROR = 4 }
	Twin response type.
enum	az_iot_hub_client_properties_message_type { AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_GET_RESPONSE = 1, AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_WRITABLE_UPDATED = 2, AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_ACKNOWLEDGEMENT = 3, AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_ERROR = 4 }
	Properties message type. More...

Functions
AZ_NODISCARD az_iot_hub_client_options	az_iot_hub_client_options_default ()
	Gets the default Azure IoT Hub Client options. More...
AZ_NODISCARD az_result	az_iot_hub_client_init (az_iot_hub_client *client, az_span iot_hub_hostname, az_span device_id, az_iot_hub_client_options const *options)
	Initializes an Azure IoT Hub Client. More...
AZ_NODISCARD az_result	az_iot_hub_client_get_user_name (az_iot_hub_client const *client, char *mqtt_user_name, size_t mqtt_user_name_size, size_t *out_mqtt_user_name_length)
	Gets the MQTT user name. More...
AZ_NODISCARD az_result	az_iot_hub_client_get_client_id (az_iot_hub_client const *client, char *mqtt_client_id, size_t mqtt_client_id_size, size_t *out_mqtt_client_id_length)
	Gets the MQTT client ID. More...
AZ_NODISCARD az_result	az_iot_hub_client_sas_get_signature (az_iot_hub_client const *client, uint64_t token_expiration_epoch_time, az_span signature, az_span *out_signature)
	Gets the Shared Access clear-text signature. More...
AZ_NODISCARD az_result	az_iot_hub_client_sas_get_password (az_iot_hub_client const *client, uint64_t token_expiration_epoch_time, az_span base64_hmac_sha256_signature, az_span key_name, char *mqtt_password, size_t mqtt_password_size, size_t *out_mqtt_password_length)
	Gets the MQTT password. More...
AZ_NODISCARD az_result	az_iot_hub_client_telemetry_get_publish_topic (az_iot_hub_client const *client, az_iot_message_properties const *properties, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that must be used for device to cloud telemetry messages. More...
AZ_NODISCARD az_result	az_iot_hub_client_c2d_parse_received_topic (az_iot_hub_client const *client, az_span received_topic, az_iot_hub_client_c2d_request *out_request)
	Attempts to parse a received message's topic for C2D features. More...
AZ_NODISCARD az_result	az_iot_hub_client_methods_parse_received_topic (az_iot_hub_client const *client, az_span received_topic, az_iot_hub_client_method_request *out_request)
	Attempts to parse a received message's topic for method features. More...
AZ_NODISCARD az_result	az_iot_hub_client_methods_response_get_publish_topic (az_iot_hub_client const *client, az_span request_id, uint16_t status, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that must be used to respond to method requests. More...
AZ_NODISCARD az_result	az_iot_hub_client_commands_parse_received_topic (az_iot_hub_client const *client, az_span received_topic, az_iot_hub_client_command_request *out_request)
	Attempts to parse a received message's topic for command features. More...
AZ_NODISCARD az_result	az_iot_hub_client_commands_response_get_publish_topic (az_iot_hub_client const *client, az_span request_id, uint16_t status, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that is used to respond to command requests. More...
AZ_NODISCARD az_result	az_iot_hub_client_twin_parse_received_topic (az_iot_hub_client const *client, az_span received_topic, az_iot_hub_client_twin_response *out_response)
	Attempts to parse a received message's topic for twin features. More...
AZ_NODISCARD az_result	az_iot_hub_client_twin_document_get_publish_topic (az_iot_hub_client const *client, az_span request_id, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that must be used to submit a Twin GET request. More...
AZ_NODISCARD az_result	az_iot_hub_client_twin_patch_get_publish_topic (az_iot_hub_client const *client, az_span request_id, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that must be used to submit a Twin PATCH request. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_parse_received_topic (az_iot_hub_client const *client, az_span received_topic, az_iot_hub_client_properties_message *out_message)
	Attempts to parse a received message's topic for properties features. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_document_get_publish_topic (az_iot_hub_client const *client, az_span request_id, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that is used to submit a properties GET request. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_get_reported_publish_topic (az_iot_hub_client const *client, az_span request_id, char *mqtt_topic, size_t mqtt_topic_size, size_t *out_mqtt_topic_length)
	Gets the MQTT topic that is used to send properties from the device to service. More...

Detailed Description

Definition for the Azure IoT Hub client.

Note

The IoT Hub MQTT protocol is described at https://docs.microsoft.com/azure/iot-hub/iot-hub-mqtt-support

You MUST NOT use any symbols (macros, functions, structures, enums, etc.) prefixed with an underscore ('_') directly in your application code. These symbols are part of Azure SDK's internal implementation; we do not document these symbols and they are subject to change in future versions of the SDK which would break your code.

Macro Definition Documentation

AZ_IOT_HUB_CLIENT_C2D_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_C2D_SUBSCRIBE_TOPIC   "devices/+/messages/devicebound/#"

The MQTT topic filter to subscribe to Cloud-to-Device requests.

Note

C2D MQTT Publish messages will have QoS At least once (1).

AZ_IOT_HUB_CLIENT_COMMANDS_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_COMMANDS_SUBSCRIBE_TOPIC   AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC

The MQTT topic filter to subscribe to command requests.

Note

Commands MQTT Publish messages will have QoS At most once (0).

AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC   "$iothub/methods/POST/#"

The MQTT topic filter to subscribe to method requests.

Note

Methods MQTT Publish messages will have QoS At most once (0).

AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_SUBSCRIBE_TOPIC    AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC

The MQTT topic filter to subscribe to properties operation messages.

Note

Twin MQTT Publish messages will have QoS At most once (0).

AZ_IOT_HUB_CLIENT_PROPERTIES_WRITABLE_UPDATES_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_PROPERTIES_WRITABLE_UPDATES_SUBSCRIBE_TOPIC    AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC

Gets the MQTT topic filter to subscribe to desired properties changes.

Note

Property MQTT Publish messages will have QoS At most once (0).

AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC   "$iothub/twin/PATCH/properties/desired/#"

Gets the MQTT topic filter to subscribe to twin desired property changes.

Note

Twin MQTT Publish messages will have QoS At most once (0).

AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC

#define AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC   "$iothub/twin/res/#"

The MQTT topic filter to subscribe to twin operation responses.

Note

Twin MQTT Publish messages will have QoS At most once (0).

AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH_NO_X509_CLIENT_CERT

#define AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH_NO_X509_CLIENT_CERT    AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH "?iothub-no-client-cert=true"

The HTTP URI Path necessary when connecting to IoT Hub using WebSockets without an X509 client certificate.

Note

Most devices should use AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH. This option is available for devices not using X509 client certificates that fail to connect to IoT Hub.

Enumeration Type Documentation

anonymous enum

anonymous enum

Azure IoT service MQTT bit field properties for telemetry publish messages.

Enumerator
AZ_HTTP_REQUEST_URL_BUFFER_SIZE	The maximum buffer size for a URL.
AZ_HTTP_REQUEST_BODY_BUFFER_SIZE	The maximum buffer size for an HTTP request body.
AZ_LOG_MESSAGE_BUFFER_SIZE	The maximum buffer size for a log message.

az_iot_hub_client_properties_message_type

enum az_iot_hub_client_properties_message_type

Properties message type.

Enumerator
AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_GET_RESPONSE	A response from a properties "GET" request.
AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_WRITABLE_UPDATED	A message with a payload containing updated writable properties for the device to process.
AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_ACKNOWLEDGEMENT	A response acknowledging the service has received properties that the device sent.
AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_ERROR	An error has occurred from the service processing properties.

Function Documentation

az_iot_hub_client_c2d_parse_received_topic()

AZ_NODISCARD az_result az_iot_hub_client_c2d_parse_received_topic	(	az_iot_hub_client const *	client,
		az_span	received_topic,
		az_iot_hub_client_c2d_request *	out_request
	)

Attempts to parse a received message's topic for C2D features.

Warning

The topic must be a valid MQTT topic or the resulting behavior will be undefined.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	received_topic	An az_span containing the received topic.
[out]	out_request	If the message is a C2D request, this will contain the az_iot_hub_client_c2d_request.

Precondition

client must not be NULL and must already be initialized by first calling az_iot_hub_client_init().

received_topic must be a valid span of size greater than 0.

out_request must not be NULL.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The topic is meant for this feature and the out_request was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCH	The topic does not match the expected format. This could be due to either a malformed topic OR the message which came in on this topic is not meant for this feature.

az_iot_hub_client_commands_parse_received_topic()

AZ_NODISCARD az_result az_iot_hub_client_commands_parse_received_topic	(	az_iot_hub_client const *	client,
		az_span	received_topic,
		az_iot_hub_client_command_request *	out_request
	)

Attempts to parse a received message's topic for command features.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	received_topic	An az_span containing the received topic.
[out]	out_request	If the message is a command request, this will contain the az_iot_hub_client_command_request.

Precondition

client must not be NULL.

received_topic must be a valid, non-empty az_span.

out_request must not be NULL. It must point to an az_iot_hub_client_command_request instance.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The topic is meant for this feature and the out_request was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCH	The topic does not match the expected format. This could be due to either a malformed topic OR the message which came in on this topic is not meant for this feature.

az_iot_hub_client_commands_response_get_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_commands_response_get_publish_topic	(	az_iot_hub_client const *	client,
		az_span	request_id,
		uint16_t	status,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that is used to respond to command requests.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	request_id	The request ID. Must match a received az_iot_hub_client_command_request request_id.
[in]	status	A code that indicates the result of the command, as defined by the application.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes, of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL.

request_id must be a valid, non-empty az_span.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.

az_iot_hub_client_get_client_id()

AZ_NODISCARD az_result az_iot_hub_client_get_client_id	(	az_iot_hub_client const *	client,
		char *	mqtt_client_id,
		size_t	mqtt_client_id_size,
		size_t *	out_mqtt_client_id_length
	)

Gets the MQTT client ID.

The client ID will be of the following format:

Format without module ID

{device_id}

Format with module ID

{device_id}/{module_id}

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[out]	mqtt_client_id	A buffer with sufficient capacity to hold the MQTT client ID. If successful, contains a null-terminated string with the client ID that needs to be passed to the MQTT client.
[in]	mqtt_client_id_size	The size, in bytes of mqtt_client_id.
[out]	out_mqtt_client_id_length	[nullable] Contains the string length, in bytes, of mqtt_client_id. Can be NULL.

Precondition

client must not be NULL.

mqtt_client_id must not be NULL.

mqtt_client_id_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

az_iot_hub_client_get_user_name()

AZ_NODISCARD az_result az_iot_hub_client_get_user_name	(	az_iot_hub_client const *	client,
		char *	mqtt_user_name,
		size_t	mqtt_user_name_size,
		size_t *	out_mqtt_user_name_length
	)

Gets the MQTT user name.

The user name will be of the following format:

Format without module ID

{iothubhostname}/{device_id}/?api-version=2018-06-30&{user_agent}

Format with module ID

{iothubhostname}/{device_id}/{module_id}/?api-version=2018-06-30&{user_agent}

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[out]	mqtt_user_name	A buffer with sufficient capacity to hold the MQTT user name. If successful, contains a null-terminated string with the user name that needs to be passed to the MQTT client.
[in]	mqtt_user_name_size	The size, in bytes of mqtt_user_name.
[out]	out_mqtt_user_name_length	[nullable] Contains the string length, in bytes, of mqtt_user_name. Can be NULL.

Precondition

client must not be NULL.

mqtt_user_name must not be NULL.

mqtt_user_name_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

az_iot_hub_client_init()

AZ_NODISCARD az_result az_iot_hub_client_init	(	az_iot_hub_client *	client,
		az_span	iot_hub_hostname,
		az_span	device_id,
		az_iot_hub_client_options const *	options
	)

Initializes an Azure IoT Hub Client.

Parameters

[out]	client	The az_iot_hub_client to use for this call.
[in]	iot_hub_hostname	The IoT Hub Hostname.
[in]	device_id	The Device ID. Must conform to the requirements of the MQTT spec for topic names (listed below) and of the IoT Hub (listed below) http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718106 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#device-identity-properties
[in]	options	[nullable] A reference to an az_iot_hub_client_options structure. If NULL is passed, the hub client will use the default options. If using custom options, please initialize first by calling az_iot_hub_client_options_default() and then populating relevant options with your own values.

Precondition

client must not be NULL.

iot_hub_hostname must be a valid span of size greater than 0.

device_id must be a valid span of size greater than 0.

Returns

An az_result value indicating the result of the operation.

az_iot_hub_client_methods_parse_received_topic()

AZ_NODISCARD az_result az_iot_hub_client_methods_parse_received_topic	(	az_iot_hub_client const *	client,
		az_span	received_topic,
		az_iot_hub_client_method_request *	out_request
	)

Attempts to parse a received message's topic for method features.

Warning

The topic must be a valid MQTT topic or the resulting behavior will be undefined.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	received_topic	An az_span containing the received topic.
[out]	out_request	If the message is a method request, this will contain the az_iot_hub_client_method_request.

Precondition

client must not be NULL and must already be initialized by first calling az_iot_hub_client_init().

received_topic must be a valid span of size greater than 0.

out_request must not be NULL.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The topic is meant for this feature and the out_request was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCH	The topic does not match the expected format. This could be due to either a malformed topic OR the message which came in on this topic is not meant for this feature.

az_iot_hub_client_methods_response_get_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_methods_response_get_publish_topic	(	az_iot_hub_client const *	client,
		az_span	request_id,
		uint16_t	status,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that must be used to respond to method requests.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	request_id	The request ID. Must match a received az_iot_hub_client_method_request request_id.
[in]	status	A code that indicates the result of the method, as defined by the user.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL and must already be initialized by first calling az_iot_hub_client_init().

request_id must be a valid span of size greater than 0.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.

az_iot_hub_client_options_default()

AZ_NODISCARD az_iot_hub_client_options az_iot_hub_client_options_default

(

)

Gets the default Azure IoT Hub Client options.

Call this to obtain an initialized az_iot_hub_client_options structure that can be afterwards modified and passed to az_iot_hub_client_init.

Returns

az_iot_hub_client_options.

az_iot_hub_client_properties_document_get_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_properties_document_get_publish_topic	(	az_iot_hub_client const *	client,
		az_span	request_id,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that is used to submit a properties GET request.

Note

The payload of the MQTT publish message should be empty.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	request_id	The request ID.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes, of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL.

request_id must be a valid, non-empty az_span.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.

az_iot_hub_client_properties_get_reported_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_properties_get_reported_publish_topic	(	az_iot_hub_client const *	client,
		az_span	request_id,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that is used to send properties from the device to service.

Note

The payload of the MQTT publish message should contain a JSON document formatted according to the DTDL specification.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	request_id	The request ID.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes, of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL.

request_id must be a valid, non-empty az_span.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.

az_iot_hub_client_properties_parse_received_topic()

AZ_NODISCARD az_result az_iot_hub_client_properties_parse_received_topic	(	az_iot_hub_client const *	client,
		az_span	received_topic,
		az_iot_hub_client_properties_message *	out_message
	)

Attempts to parse a received message's topic for properties features.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	received_topic	An az_span containing the received topic.
[out]	out_message	If the message is properties-operation related, this will contain the az_iot_hub_client_properties_message.

Precondition

client must not be NULL.

received_topic must be a valid, non-empty az_span.

out_message must not be NULL. It must point to an az_iot_hub_client_properties_message instance.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The topic is meant for this feature and the out_message was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCH	The topic does not match the expected format. This could be due to either a malformed topic OR the message which came in on this topic is not meant for this feature.

az_iot_hub_client_sas_get_password()

AZ_NODISCARD az_result az_iot_hub_client_sas_get_password	(	az_iot_hub_client const *	client,
		uint64_t	token_expiration_epoch_time,
		az_span	base64_hmac_sha256_signature,
		az_span	key_name,
		char *	mqtt_password,
		size_t	mqtt_password_size,
		size_t *	out_mqtt_password_length
	)

Gets the MQTT password.

Note

The MQTT password must be an empty string if X509 Client certificates are used. Use this API only when authenticating with SAS tokens.

This API should be used in conjunction with az_iot_hub_client_sas_get_signature().

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	base64_hmac_sha256_signature	The Base64 encoded value of the HMAC-SHA256(signature, SharedAccessKey). The signature is obtained by using az_iot_hub_client_sas_get_signature().
[in]	token_expiration_epoch_time	The time, in seconds, from 1/1/1970. It MUST be the same value passed to az_iot_hub_client_sas_get_signature().
[in]	key_name	The Shared Access Key Name (Policy Name). This is optional. For security reasons we recommend using one key per device instead of using a global policy key.
[out]	mqtt_password	A char buffer with sufficient capacity to hold the MQTT password.
[in]	mqtt_password_size	The size, in bytes of mqtt_password.
[out]	out_mqtt_password_length	[nullable] Contains the string length, in bytes, of mqtt_password. Can be NULL.

Precondition

client must not be NULL.

token_expiration_epoch_time must be greater than 0.

base64_hmac_sha256_signature must be a valid span of size greater than 0.

mqtt_password must not be NULL.

mqtt_password_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The operation was successful. In this case, mqtt_password will contain a null-terminated string with the password that needs to be passed to the MQTT client.
AZ_ERROR_NOT_ENOUGH_SPACE	The mqtt_password does not have enough size.

az_iot_hub_client_sas_get_signature()

AZ_NODISCARD az_result az_iot_hub_client_sas_get_signature	(	az_iot_hub_client const *	client,
		uint64_t	token_expiration_epoch_time,
		az_span	signature,
		az_span *	out_signature
	)

Gets the Shared Access clear-text signature.

The application must obtain a valid clear-text signature using this API, sign it using HMAC-SHA256 using the Shared Access Key as password then Base64 encode the result.

Use the following APIs when the Shared Access Key is available to the application or stored within a Hardware Security Module. The APIs are not necessary if X509 Client Certificate Authentication is used.

Note

This API should be used in conjunction with az_iot_hub_client_sas_get_password().

More information available at https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security#security-tokens

A typical flow for using these two APIs might look something like the following (note the size of buffers and non-SDK APIs are for demo purposes only):

const char* const signature_str = "TST+J9i1F8tE6dLYCtuQcu10u7umGO+aWGqPQhd9AAo=";
az_span signature = AZ_SPAN_FROM_STR(signature_str);
az_iot_hub_client_sas_get_signature(&client, expiration_time_in_seconds, signature, &signature);
 
char decoded_sas_key[128] = { 0 };
base64_decode(base64_encoded_sas_key, decoded_sas_key);
 
char signed_bytes[256] = { 0 };
hmac_256(az_span_ptr(signature), az_span_size(signature), decoded_sas_key, signed_bytes);
 
char signed_bytes_base64_encoded[256] = { 0 };
base64_encode(signed_bytes, signed_bytes_base64_encoded);
 
char final_password[512] = { 0 };
az_iot_hub_client_sas_get_password(client, expiration_time_in_seconds,
  AZ_SPAN_FROM_STR(signed_bytes_base64_encoded), final_password, sizeof(final_password), NULL);
 
mqtt_set_password(&mqtt_client, final_password);

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	token_expiration_epoch_time	The time, in seconds, from 1/1/1970.
[in]	signature	An empty az_span with sufficient capacity to hold the SAS signature.
[out]	out_signature	The output az_span containing the SAS signature.

Precondition

client must not be NULL.

token_expiration_epoch_time must be greater than 0.

signature must be a valid span of size greater than 0.

out_signature must not be NULL.

Returns

An az_result value indicating the result of the operation.

az_iot_hub_client_telemetry_get_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_telemetry_get_publish_topic	(	az_iot_hub_client const *	client,
		az_iot_message_properties const *	properties,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that must be used for device to cloud telemetry messages.

Note

This topic can also be used to set the MQTT Will message in the Connect message.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	properties	An optional az_iot_message_properties object (can be NULL).
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.

az_iot_hub_client_twin_document_get_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_twin_document_get_publish_topic	(	az_iot_hub_client const *	client,
		az_span	request_id,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that must be used to submit a Twin GET request.

Note

The payload of the MQTT publish message should be empty.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	request_id	The request ID.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL and must already be initialized by first calling az_iot_hub_client_init().

request_id must be a valid span of size greater than 0.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.

az_iot_hub_client_twin_parse_received_topic()

AZ_NODISCARD az_result az_iot_hub_client_twin_parse_received_topic	(	az_iot_hub_client const *	client,
		az_span	received_topic,
		az_iot_hub_client_twin_response *	out_response
	)

Attempts to parse a received message's topic for twin features.

Warning

The topic must be a valid MQTT topic or the resulting behavior will be undefined.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	received_topic	An az_span containing the received topic.
[out]	out_response	If the message is twin-operation related, this will contain the az_iot_hub_client_twin_response.

Precondition

client must not be NULL and must already be initialized by first calling az_iot_hub_client_init().

received_topic must be a valid span of size greater than 0.

out_response must not be NULL.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The topic is meant for this feature and the out_response was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCH	The topic does not match the expected format. This could be due to either a malformed topic OR the message which came in on this topic is not meant for this feature.

az_iot_hub_client_twin_patch_get_publish_topic()

AZ_NODISCARD az_result az_iot_hub_client_twin_patch_get_publish_topic	(	az_iot_hub_client const *	client,
		az_span	request_id,
		char *	mqtt_topic,
		size_t	mqtt_topic_size,
		size_t *	out_mqtt_topic_length
	)

Gets the MQTT topic that must be used to submit a Twin PATCH request.

Note

The payload of the MQTT publish message should contain a JSON document formatted according to the Twin specification.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in]	request_id	The request ID.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic. If successful, contains a null-terminated string with the topic that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes of mqtt_topic.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of mqtt_topic. Can be NULL.

Precondition

client must not be NULL and must already be initialized by first calling az_iot_hub_client_init().

request_id must be a valid span of size greater than 0.

mqtt_topic must not be NULL.

mqtt_topic_size must be greater than 0.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The topic was retrieved successfully.