Azure SDK for Embedded C
az_iot_common.h
Go to the documentation of this file.
1 // Copyright (c) Microsoft Corporation. All rights reserved.
2 // SPDX-License-Identifier: MIT
3 
15 #ifndef _az_IOT_CORE_H
16 #define _az_IOT_CORE_H
17 
18 #include <azure/core/az_log.h>
19 #include <azure/core/az_result.h>
20 #include <azure/core/az_span.h>
21 
22 #include <stdbool.h>
23 #include <stdint.h>
24 
25 #include <azure/core/_az_cfg_prefix.h>
26 
32 {
33  // === IoT error codes ===
35  AZ_ERROR_IOT_TOPIC_NO_MATCH = _az_RESULT_MAKE_ERROR(_az_FACILITY_IOT, 1),
36 
38  AZ_ERROR_IOT_END_OF_PROPERTIES = _az_RESULT_MAKE_ERROR(_az_FACILITY_IOT, 2),
39 };
40 
46 {
48  = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_MQTT, 1),
49 
51  = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_MQTT, 2),
52 
53  AZ_LOG_IOT_RETRY = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 1),
54 
56  = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 2),
57 
59  = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 3),
60 };
61 
62 enum
63 {
64  AZ_IOT_DEFAULT_MQTT_CONNECT_PORT = 8883,
65  AZ_IOT_DEFAULT_MQTT_CONNECT_KEEPALIVE_SECONDS = 240
66 };
67 
74 typedef enum
75 {
76  // Default, unset value
77  AZ_IOT_STATUS_UNKNOWN = 0,
78 
79  // Service success codes
80  AZ_IOT_STATUS_OK = 200,
81  AZ_IOT_STATUS_ACCEPTED = 202,
82  AZ_IOT_STATUS_NO_CONTENT = 204,
83 
84  // Service error codes
85  AZ_IOT_STATUS_BAD_REQUEST = 400,
86  AZ_IOT_STATUS_UNAUTHORIZED = 401,
87  AZ_IOT_STATUS_FORBIDDEN = 403,
88  AZ_IOT_STATUS_NOT_FOUND = 404,
89  AZ_IOT_STATUS_NOT_ALLOWED = 405,
90  AZ_IOT_STATUS_NOT_CONFLICT = 409,
91  AZ_IOT_STATUS_PRECONDITION_FAILED = 412,
92  AZ_IOT_STATUS_REQUEST_TOO_LARGE = 413,
93  AZ_IOT_STATUS_UNSUPPORTED_TYPE = 415,
94  AZ_IOT_STATUS_THROTTLED = 429,
95  AZ_IOT_STATUS_CLIENT_CLOSED = 499,
96  AZ_IOT_STATUS_SERVER_ERROR = 500,
97  AZ_IOT_STATUS_BAD_GATEWAY = 502,
98  AZ_IOT_STATUS_SERVICE_UNAVAILABLE = 503,
99  AZ_IOT_STATUS_TIMEOUT = 504,
100 } az_iot_status;
101 
102 /*
103  *
104  * Properties APIs
105  *
106  * IoT message properties are used for Device-to-Cloud (D2C) as well as Cloud-to-Device (C2D).
107  * Properties are always appended to the MQTT topic of the published or received message and
108  * must contain percent-encoded names and values.
109  */
110 
117 #define AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID \
118  "%24.mid"
119 #define AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID \
120  "%24.cid"
122 #define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE \
123  "%24.ct"
124 #define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING "%24.ce"
125 #define AZ_IOT_MESSAGE_PROPERTIES_USER_ID "%24.uid"
126 #define AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME "%24.ctime"
132 typedef struct
133 {
134  struct
135  {
136  az_span properties_buffer;
137  int32_t properties_written;
138  uint32_t current_property_index;
139  } _internal;
141 
163  az_iot_message_properties* properties,
164  az_span buffer,
165  int32_t written_length);
166 
187  az_iot_message_properties* properties,
188  az_span name,
189  az_span value);
190 
204  az_iot_message_properties* properties,
205  az_span name,
206  az_span* out_value);
207 
219  az_iot_message_properties* properties,
220  az_span* out_name,
221  az_span* out_value);
222 
229 AZ_NODISCARD AZ_INLINE bool az_iot_status_succeeded(az_iot_status status)
230 {
231  return status < AZ_IOT_STATUS_BAD_REQUEST;
232 }
233 
241 AZ_NODISCARD AZ_INLINE bool az_iot_status_retriable(az_iot_status status)
242 {
243  return ((status == AZ_IOT_STATUS_THROTTLED) || (status == AZ_IOT_STATUS_SERVER_ERROR));
244 }
245 
258 AZ_NODISCARD int32_t az_iot_calculate_retry_delay(
259  int32_t operation_msec,
260  int16_t attempt,
261  int32_t min_retry_delay_msec,
262  int32_t max_retry_delay_msec,
263  int32_t random_jitter_msec);
264 
265 #include <azure/core/_az_cfg_suffix.h>
266 
267 #endif // _az_IOT_CORE_H
az_result.h
Definition of az_result and helper functions.
az_log.h
This header defines the types and functions your application uses to be notified of Azure SDK client ...
az_iot_message_properties_next
AZ_NODISCARD az_result az_iot_message_properties_next(az_iot_message_properties *properties, az_span *out_name, az_span *out_value)
Iterates over the list of properties.
az_iot_calculate_retry_delay
AZ_NODISCARD int32_t az_iot_calculate_retry_delay(int32_t operation_msec, int16_t attempt, int32_t min_retry_delay_msec, int32_t max_retry_delay_msec, int32_t random_jitter_msec)
Calculates the recommended delay before retrying an operation that failed.
AZ_ERROR_IOT_END_OF_PROPERTIES
@ AZ_ERROR_IOT_END_OF_PROPERTIES
While iterating, there are no more properties to return.
Definition: az_iot_common.h:38
az_result
int32_t az_result
The type represents the various success and error conditions.
Definition: az_result.h:45
AZ_LOG_IOT_SAS_TOKEN
@ AZ_LOG_IOT_SAS_TOKEN
IoT Client generated new SAS token.
Definition: az_iot_common.h:55
az_iot_status_retriable
AZ_NODISCARD AZ_INLINE bool az_iot_status_retriable(az_iot_status status)
Checks if the status indicates a retriable error occurred during the operation.
Definition: az_iot_common.h:241
AZ_ERROR_IOT_TOPIC_NO_MATCH
@ AZ_ERROR_IOT_TOPIC_NO_MATCH
The IoT topic is not matching the expected format.
Definition: az_iot_common.h:35
az_result_iot
az_result_iot
The type represents the various az_result success and error conditions specific to the IoT clients wi...
Definition: az_iot_common.h:32
AZ_LOG_MQTT_RECEIVED_TOPIC
@ AZ_LOG_MQTT_RECEIVED_TOPIC
Accepted MQTT topic received.
Definition: az_iot_common.h:47
az_iot_message_properties
Telemetry or C2D properties.
Definition: az_iot_common.h:133
az_span.h
An az_span represents a contiguous byte buffer and is used for string manipulations,...
az_iot_message_properties_init
AZ_NODISCARD az_result az_iot_message_properties_init(az_iot_message_properties *properties, az_span buffer, int32_t written_length)
Initializes the Telemetry or C2D properties.
AZ_LOG_MQTT_RECEIVED_PAYLOAD
@ AZ_LOG_MQTT_RECEIVED_PAYLOAD
Accepted MQTT payload received.
Definition: az_iot_common.h:50
az_iot_message_properties_append
AZ_NODISCARD az_result az_iot_message_properties_append(az_iot_message_properties *properties, az_span name, az_span value)
Appends a name-value property to the list of properties.
az_log_classification_iot
az_log_classification_iot
Identifies the az_log_classification produced specifically by the IoT clients within the SDK.
Definition: az_iot_common.h:46
az_iot_message_properties_find
AZ_NODISCARD az_result az_iot_message_properties_find(az_iot_message_properties *properties, az_span name, az_span *out_value)
Finds the value of a property.
AZ_LOG_IOT_RETRY
@ AZ_LOG_IOT_RETRY
IoT Client retry.
Definition: az_iot_common.h:53
az_iot_status
az_iot_status
Azure IoT service status codes.
Definition: az_iot_common.h:75
AZ_LOG_IOT_AZURERTOS
@ AZ_LOG_IOT_AZURERTOS
Azure IoT classification for Azure RTOS.
Definition: az_iot_common.h:58
az_span
Represents a "view" over a byte buffer that represents a contiguous region of memory....
Definition: az_span.h:33
az_iot_status_succeeded
AZ_NODISCARD AZ_INLINE bool az_iot_status_succeeded(az_iot_status status)
Checks if the status indicates a successful operation.
Definition: az_iot_common.h:229