Azure SDK for Embedded C
Data Structures | Macros | Enumerations | Functions
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]clientThe az_iot_hub_client to use for this call.
[in]received_topicAn az_span containing the received topic.
[out]out_requestIf 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_OKThe topic is meant for this feature and the out_request was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCHThe 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]clientThe az_iot_hub_client to use for this call.
[out]mqtt_client_idA 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_sizeThe 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]clientThe az_iot_hub_client to use for this call.
[out]mqtt_user_nameA 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_sizeThe 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]clientThe az_iot_hub_client to use for this call.
[in]iot_hub_hostnameThe IoT Hub Hostname.
[in]device_idThe Device ID.
[in]optionsA 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]clientThe az_iot_hub_client to use for this call.
[in]received_topicAn az_span containing the received topic.
[out]out_requestIf 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_OKThe topic is meant for this feature and the out_request was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCHThe 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]clientThe az_iot_hub_client to use for this call.
[in]request_idThe request id. Must match a received az_iot_hub_client_method_request request_id.
[in]statusA code that indicates the result of the method, as defined by the user.
[out]mqtt_topicA 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_sizeThe 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_OKThe 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]clientThe az_iot_hub_client to use for this call.
[in]base64_hmac_sha256_signatureThe 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_timeThe time, in seconds, from 1/1/1970. It MUST be the same value passed to az_iot_hub_client_sas_get_signature().
[in]key_nameThe 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_passwordA char buffer with sufficient capacity to hold the MQTT password.
[in]mqtt_password_sizeThe 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_OKThe 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_SPACEThe 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]clientThe az_iot_hub_client to use for this call.
[in]token_expiration_epoch_timeThe time, in seconds, from 1/1/1970.
[in]signatureAn empty az_span with sufficient capacity to hold the SAS signature.
[out]out_signatureThe 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]clientThe az_iot_hub_client to use for this call.
[in]propertiesAn optional az_iot_message_properties object (can be NULL).
[out]mqtt_topicA 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_sizeThe 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_OKThe 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]clientThe az_iot_hub_client to use for this call.
[in]request_idThe request id.
[out]mqtt_topicA 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_sizeThe 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_OKThe 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]clientThe az_iot_hub_client to use for this call.
[in]received_topicAn az_span containing the received topic.
[out]out_twin_responseIf 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_OKThe topic is meant for this feature and the out_twin_response was populated with relevant information.
AZ_ERROR_IOT_TOPIC_NO_MATCHThe 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]clientThe az_iot_hub_client to use for this call.
[in]request_idThe request id.
[out]mqtt_topicA 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_sizeThe 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_OKThe topic was retrieved successfully.