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_result.h>
19 #include <azure/core/az_span.h>
20 
21 #include <stdbool.h>
22 #include <stdint.h>
23 
24 #include <azure/core/_az_cfg_prefix.h>
25 
26 enum
27 {
28  AZ_IOT_DEFAULT_MQTT_CONNECT_PORT = 8883,
29  AZ_IOT_DEFAULT_MQTT_CONNECT_KEEPALIVE_SECONDS = 240
30 };
31 
38 typedef enum
39 {
40  // Default, unset value
41  AZ_IOT_STATUS_UNKNOWN = 0,
42 
43  // Service success codes
44  AZ_IOT_STATUS_OK = 200,
45  AZ_IOT_STATUS_ACCEPTED = 202,
46  AZ_IOT_STATUS_NO_CONTENT = 204,
47 
48  // Service error codes
49  AZ_IOT_STATUS_BAD_REQUEST = 400,
50  AZ_IOT_STATUS_UNAUTHORIZED = 401,
51  AZ_IOT_STATUS_FORBIDDEN = 403,
52  AZ_IOT_STATUS_NOT_FOUND = 404,
53  AZ_IOT_STATUS_NOT_ALLOWED = 405,
54  AZ_IOT_STATUS_NOT_CONFLICT = 409,
55  AZ_IOT_STATUS_PRECONDITION_FAILED = 412,
56  AZ_IOT_STATUS_REQUEST_TOO_LARGE = 413,
57  AZ_IOT_STATUS_UNSUPPORTED_TYPE = 415,
58  AZ_IOT_STATUS_THROTTLED = 429,
59  AZ_IOT_STATUS_CLIENT_CLOSED = 499,
60  AZ_IOT_STATUS_SERVER_ERROR = 500,
61  AZ_IOT_STATUS_BAD_GATEWAY = 502,
62  AZ_IOT_STATUS_SERVICE_UNAVAILABLE = 503,
63  AZ_IOT_STATUS_TIMEOUT = 504,
65 
66 /*
67  *
68  * Properties APIs
69  *
70  * IoT message properties are used for Device-to-Cloud (D2C) as well as Cloud-to-Device (C2D).
71  * Properties are always appended to the MQTT topic of the published or received message and
72  * must contain percent-encoded names and values.
73  */
74 
81 #define AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID \
82  "%24.mid"
83 #define AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID \
84  "%24.cid"
86 #define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE \
87  "%24.ct"
88 #define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING "%24.ce"
89 #define AZ_IOT_MESSAGE_PROPERTIES_USER_ID "%24.uid"
90 #define AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME "%24.ctime"
96 typedef struct
97 {
98  struct
99  {
100  az_span properties_buffer;
101  int32_t properties_written;
102  uint32_t current_property_index;
103  } _internal;
105 
127  az_iot_message_properties* properties,
128  az_span buffer,
129  int32_t written_length);
130 
151  az_iot_message_properties* properties,
152  az_span name,
153  az_span value);
154 
168  az_iot_message_properties* properties,
169  az_span name,
170  az_span* out_value);
171 
183  az_iot_message_properties* properties,
184  az_span* out_name,
185  az_span* out_value);
186 
193 AZ_NODISCARD AZ_INLINE bool az_iot_status_succeeded(az_iot_status status)
194 {
195  return status < AZ_IOT_STATUS_BAD_REQUEST;
196 }
197 
205 AZ_NODISCARD AZ_INLINE bool az_iot_status_retriable(az_iot_status status)
206 {
207  return ((status == AZ_IOT_STATUS_THROTTLED) || (status == AZ_IOT_STATUS_SERVER_ERROR));
208 }
209 
221 AZ_NODISCARD int32_t az_iot_calculate_retry_delay(
222  int32_t operation_msec,
223  int16_t attempt,
224  int32_t min_retry_delay_msec,
225  int32_t max_retry_delay_msec,
226  int32_t random_msec);
227 
228 #include <azure/core/_az_cfg_suffix.h>
229 
230 #endif
az_result.h
Definition of az_result and helper functions.
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_result
az_result
The type represents the various success and error conditions.
Definition: az_result.h:53
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:205
az_iot_message_properties
Telemetry or C2D properties.
Definition: az_iot_common.h:97
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_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_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_msec)
Calculates the recommended delay before retrying an operation that failed.
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_iot_status
az_iot_status
Azure IoT service status codes.
Definition: az_iot_common.h:39
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:193