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_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_CLIENT_TWIN_RESPONSE_TYPE_GET = 1, AZ_IOT_CLIENT_TWIN_RESPONSE_TYPE_DESIRED_PROPERTIES = 2, AZ_IOT_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_twin_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.
[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_twin_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_twin_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_twin_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.