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>

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_twin_response
	Twin response. 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_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...

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 }
	Twin response type.

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_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...

Detailed Description

Definition for the Azure IoT Hub client.

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

Note: 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.

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

◆ 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.

Remarks: Methods 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.

Remarks: 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.

Remarks: 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.

Remarks: 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.

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.

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

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_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 of `mqtt_client_id`. Can be `NULL`.

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`.

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. If the ID contains any of the following characters, they must be percent-encoded as follows: `/` : `%2F` `%` : `%25` `#` : `%23` `&` : `%26`
[in]	options	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.

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.

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.

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`.

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_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.

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

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`.

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.

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

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.

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.

Remarks: Telemetry MQTT Publish messages must have QoS At least once (1).; 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`.

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.

Remarks: 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`.

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.

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.

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.

Remarks: 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`.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK The topic was retrieved successfully.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AZ_IOT_HUB_CLIENT_C2D_SUBSCRIBE_TOPIC

◆ AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC

◆ AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC

◆ AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC

◆ AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH_NO_X509_CLIENT_CERT

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ az_iot_hub_client_c2d_parse_received_topic()

◆ az_iot_hub_client_get_client_id()

◆ az_iot_hub_client_get_user_name()

◆ az_iot_hub_client_init()

◆ az_iot_hub_client_methods_parse_received_topic()

◆ az_iot_hub_client_methods_response_get_publish_topic()

◆ az_iot_hub_client_options_default()

◆ az_iot_hub_client_sas_get_password()

◆ az_iot_hub_client_sas_get_signature()

◆ az_iot_hub_client_telemetry_get_publish_topic()

◆ az_iot_hub_client_twin_document_get_publish_topic()

◆ az_iot_hub_client_twin_parse_received_topic()

◆ az_iot_hub_client_twin_patch_get_publish_topic()