Azure SDK for Embedded C
az_iot_hub_client.h
Go to the documentation of this file.
1 // Copyright (c) Microsoft Corporation. All rights reserved.
2 // SPDX-License-Identifier: MIT
3 
17 #ifndef _az_IOT_HUB_CLIENT_H
18 #define _az_IOT_HUB_CLIENT_H
19 
20 #include <azure/core/az_result.h>
21 #include <azure/core/az_span.h>
23 
24 #include <stdbool.h>
25 #include <stdint.h>
26 
27 #include <azure/core/_az_cfg_prefix.h>
28 
33 enum
34 {
35  AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_QOS = 0
36 };
37 
42 typedef struct
43 {
50 
54 typedef struct
55 {
56  struct
57  {
58  az_span iot_hub_hostname;
59  az_span device_id;
61  } _internal;
63 
72 
86  az_iot_hub_client* client,
87  az_span iot_hub_hostname,
88  az_span device_id,
89  az_iot_hub_client_options const* options);
90 
94 #define AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH "/$iothub/websocket"
95 
102 #define AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH_NO_X509_CLIENT_CERT \
103  AZ_IOT_HUB_CLIENT_WEB_SOCKET_PATH "?iothub-no-client-cert=true"
104 
123  az_iot_hub_client const* client,
124  char* mqtt_user_name,
125  size_t mqtt_user_name_size,
126  size_t* out_mqtt_user_name_length);
127 
145  az_iot_hub_client const* client,
146  char* mqtt_client_id,
147  size_t mqtt_client_id_size,
148  size_t* out_mqtt_client_id_length);
149 
150 /*
151  *
152  * SAS Token APIs
153  *
154  * Use the following APIs when the Shared Access Key is available to the application or stored
155  * within a Hardware Security Module. The APIs are not necessary if X509 Client Certificate
156  * Authentication is used.
157  */
158 
174  az_iot_hub_client const* client,
175  uint64_t token_expiration_epoch_time,
176  az_span signature,
177  az_span* out_signature);
178 
204  az_iot_hub_client const* client,
205  uint64_t token_expiration_epoch_time,
206  az_span base64_hmac_sha256_signature,
207  az_span key_name,
208  char* mqtt_password,
209  size_t mqtt_password_size,
210  size_t* out_mqtt_password_length);
211 
212 /*
213  *
214  * Telemetry APIs
215  *
216  */
217 
235  az_iot_hub_client const* client,
236  az_iot_message_properties const* properties,
237  char* mqtt_topic,
238  size_t mqtt_topic_size,
239  size_t* out_mqtt_topic_length);
240 
241 /*
242  *
243  * Cloud-to-device (C2D) APIs
244  *
245  */
246 
251 #define AZ_IOT_HUB_CLIENT_C2D_SUBSCRIBE_TOPIC "devices/+/messages/devicebound/#"
252 
257 typedef struct
258 {
261 
277  az_iot_hub_client const* client,
278  az_span received_topic,
279  az_iot_hub_client_c2d_request* out_request);
280 
281 /*
282  *
283  * Methods APIs
284  *
285  */
286 
291 #define AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC "$iothub/methods/POST/#"
292 
297 typedef struct
298 {
303 
319  az_iot_hub_client const* client,
320  az_span received_topic,
321  az_iot_hub_client_method_request* out_request);
322 
340  az_iot_hub_client const* client,
341  az_span request_id,
342  uint16_t status,
343  char* mqtt_topic,
344  size_t mqtt_topic_size,
345  size_t* out_mqtt_topic_length);
346 
347 /*
348  *
349  * Twin APIs
350  *
351  */
352 
357 #define AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC "$iothub/twin/res/#"
358 
363 #define AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC "$iothub/twin/PATCH/properties/desired/#"
364 
369 typedef enum
370 {
371  AZ_IOT_CLIENT_TWIN_RESPONSE_TYPE_GET = 1,
372  AZ_IOT_CLIENT_TWIN_RESPONSE_TYPE_DESIRED_PROPERTIES = 2,
373  AZ_IOT_CLIENT_TWIN_RESPONSE_TYPE_REPORTED_PROPERTIES = 3,
375 
380 typedef struct
381 {
384  az_span
392 
408  az_iot_hub_client const* client,
409  az_span received_topic,
410  az_iot_hub_client_twin_response* out_twin_response);
411 
428  az_iot_hub_client const* client,
429  az_span request_id,
430  char* mqtt_topic,
431  size_t mqtt_topic_size,
432  size_t* out_mqtt_topic_length);
433 
451  az_iot_hub_client const* client,
452  az_span request_id,
453  char* mqtt_topic,
454  size_t mqtt_topic_size,
455  size_t* out_mqtt_topic_length);
456 
457 #include <azure/core/_az_cfg_suffix.h>
458 
459 #endif
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.
az_result.h
Definition of az_result and helper functions.
az_iot_hub_client_c2d_request::properties
az_iot_message_properties properties
Definition: az_iot_hub_client.h:259
az_iot_hub_client_method_request::name
az_span name
Definition: az_iot_hub_client.h:301
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.
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.
az_result
az_result
The type represents the various success and error conditions.
Definition: az_result.h:53
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.
az_iot_hub_client_twin_response::request_id
az_span request_id
Definition: az_iot_hub_client.h:385
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.
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.
az_iot_hub_client_twin_response::status
az_iot_status status
Definition: az_iot_hub_client.h:383
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.
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.
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.
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.
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.
az_iot_hub_client_c2d_request
The Cloud-To-Device Request.
Definition: az_iot_hub_client.h:258
az_iot_message_properties
Telemetry or C2D properties.
Definition: az_iot_common.h:97
az_iot_hub_client_twin_response_type
az_iot_hub_client_twin_response_type
Twin response type.
Definition: az_iot_hub_client.h:370
az_span.h
An az_span represents a contiguous byte buffer and is used for string manipulations,...
az_iot_hub_client_twin_response::response_type
az_iot_hub_client_twin_response_type response_type
Definition: az_iot_hub_client.h:382
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.
az_iot_hub_client_options::user_agent
az_span user_agent
Definition: az_iot_hub_client.h:45
az_iot_hub_client_options::module_id
az_span module_id
Definition: az_iot_hub_client.h:44
az_iot_hub_client_method_request::request_id
az_span request_id
Definition: az_iot_hub_client.h:299
az_iot_hub_client_options
Azure IoT Hub Client options.
Definition: az_iot_hub_client.h:43
az_iot_hub_client_twin_response::version
az_span version
Definition: az_iot_hub_client.h:386
az_iot_hub_client_method_request
A method request received from IoT Hub.
Definition: az_iot_hub_client.h:298
az_iot_hub_client_twin_response
Twin response.
Definition: az_iot_hub_client.h:381
az_iot_status
az_iot_status
Azure IoT service status codes.
Definition: az_iot_common.h:39
az_iot_hub_client
Azure IoT Hub Client.
Definition: az_iot_hub_client.h:55
az_iot_common.h
Azure IoT common definitions.
az_iot_hub_client_options::model_id
az_span model_id
Definition: az_iot_hub_client.h:47
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.
az_span
Represents a "view" over a byte buffer that represents a contiguous region of memory....
Definition: az_span.h:33