Azure SDK for Embedded C
Data Structures | Macros | Enumerations | Functions
az_iot_common.h File Reference

Azure IoT common definitions. More...

#include <azure/core/az_log.h>
#include <azure/core/az_result.h>
#include <azure/core/az_span.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_message_properties
 Telemetry or C2D properties. More...
 

Macros

#define AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID   "%24.mid"
 
#define AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID   "%24.cid"
 
#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE   "%24.ct"
 
#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING   "%24.ce"
 
#define AZ_IOT_MESSAGE_PROPERTIES_USER_ID   "%24.uid"
 
#define AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME   "%24.ctime"
 
#define AZ_IOT_MESSAGE_COMPONENT_NAME   "%24.sub"
 

Enumerations

enum  az_result_iot { AZ_ERROR_IOT_TOPIC_NO_MATCH = _az_RESULT_MAKE_ERROR(_az_FACILITY_IOT, 1), AZ_ERROR_IOT_END_OF_PROPERTIES = _az_RESULT_MAKE_ERROR(_az_FACILITY_IOT, 2) }
 The type represents the various az_result success and error conditions specific to the IoT clients within the SDK. More...
 
enum  az_log_classification_iot {
  AZ_LOG_MQTT_RECEIVED_TOPIC = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT_MQTT, 1), AZ_LOG_MQTT_RECEIVED_PAYLOAD = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT_MQTT, 2), AZ_LOG_IOT_RETRY = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 1), AZ_LOG_IOT_SAS_TOKEN = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 2),
  AZ_LOG_IOT_AZURERTOS = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 3), AZ_LOG_IOT_ADU = _az_LOG_MAKE_CLASSIFICATION(_az_FACILITY_IOT, 4)
}
 Identifies the az_log_classification produced specifically by the IoT clients within the SDK. More...
 
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
}
 
enum  az_iot_status {
  AZ_IOT_STATUS_UNKNOWN = 0, AZ_IOT_STATUS_OK = 200, AZ_IOT_STATUS_ACCEPTED = 202, AZ_IOT_STATUS_NO_CONTENT = 204,
  AZ_IOT_STATUS_BAD_REQUEST = 400, AZ_IOT_STATUS_UNAUTHORIZED = 401, AZ_IOT_STATUS_FORBIDDEN = 403, AZ_IOT_STATUS_NOT_FOUND = 404,
  AZ_IOT_STATUS_NOT_ALLOWED = 405, AZ_IOT_STATUS_NOT_CONFLICT = 409, AZ_IOT_STATUS_PRECONDITION_FAILED = 412, AZ_IOT_STATUS_REQUEST_TOO_LARGE = 413,
  AZ_IOT_STATUS_UNSUPPORTED_TYPE = 415, AZ_IOT_STATUS_THROTTLED = 429, AZ_IOT_STATUS_CLIENT_CLOSED = 499, AZ_IOT_STATUS_SERVER_ERROR = 500,
  AZ_IOT_STATUS_BAD_GATEWAY = 502, AZ_IOT_STATUS_SERVICE_UNAVAILABLE = 503, AZ_IOT_STATUS_TIMEOUT = 504
}
 Azure IoT service status codes. More...
 

Functions

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. More...
 
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. More...
 
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. More...
 
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. More...
 
AZ_NODISCARD AZ_INLINE bool az_iot_status_succeeded (az_iot_status status)
 Checks if the status indicates a successful operation. More...
 
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. More...
 
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. More...
 

Detailed Description

Azure IoT common definitions.

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_MESSAGE_COMPONENT_NAME

#define AZ_IOT_MESSAGE_COMPONENT_NAME   "%24.sub"

Name of the component

Note
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

◆ AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING

#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING   "%24.ce"

UTF-8, UTF-16, etc.

Note
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

◆ AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE

#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE   "%24.ct"

URL encoded and of the form text%2Fplain or application%2Fjson, etc.

Note
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

◆ AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID

#define AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID   "%24.cid"

Used in distributed tracing.

Note
More information here: https://docs.microsoft.com/azure/iot-hub/iot-hub-distributed-tracing.
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

◆ AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME

#define AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME   "%24.ctime"

Creation time of the message.

Note
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

◆ AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID

#define AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID   "%24.mid"

Add unique identification to a message.

Note
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

◆ AZ_IOT_MESSAGE_PROPERTIES_USER_ID

#define AZ_IOT_MESSAGE_PROPERTIES_USER_ID   "%24.uid"

User ID field.

Note
It can be used with IoT message property APIs by wrapping the macro in a AZ_SPAN_FROM_STR macro as a parameter, where needed.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
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.

◆ az_iot_status

◆ az_log_classification_iot

Identifies the az_log_classification produced specifically by the IoT clients within the SDK.

Enumerator
AZ_LOG_MQTT_RECEIVED_TOPIC 

Accepted MQTT topic received.

AZ_LOG_MQTT_RECEIVED_PAYLOAD 

Accepted MQTT payload received.

AZ_LOG_IOT_RETRY 

IoT Client retry.

AZ_LOG_IOT_SAS_TOKEN 

IoT Client generated new SAS token.

AZ_LOG_IOT_AZURERTOS 

Azure IoT classification for Azure RTOS.

AZ_LOG_IOT_ADU 

Azure IoT classification for ADU APIs.

◆ az_result_iot

The type represents the various az_result success and error conditions specific to the IoT clients within the SDK.

Enumerator
AZ_ERROR_IOT_TOPIC_NO_MATCH 

The IoT topic is not matching the expected format.

AZ_ERROR_IOT_END_OF_PROPERTIES 

While iterating, there are no more properties to return.

Function Documentation

◆ 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.

Parameters
[in]operation_msecThe time it took, in milliseconds, to perform the operation that failed.
[in]attemptThe number of failed retry attempts.
[in]min_retry_delay_msecThe minimum time, in milliseconds, to wait before a retry.
[in]max_retry_delay_msecThe maximum time, in milliseconds, to wait before a retry.
[in]random_jitter_msecA random value between 0 and the maximum allowed jitter, in milliseconds.
Precondition
operation_msec must be between 0 and INT32_MAX - 1.
attempt must be between 0 and INT16_MAX - 1.
min_retry_delay_msec must be between 0 and INT32_MAX - 1.
max_retry_delay_msec must be between 0 and INT32_MAX - 1.
random_jitter_msec must be between 0 and INT32_MAX - 1.
Returns
The recommended delay in milliseconds.

◆ 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.

Note
The properties must adhere to the character restrictions listed in the below link. https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-construct
Parameters
[in]propertiesThe az_iot_message_properties to use for this call.
[in]nameThe name of the property. Must be a valid, non-empty span.
[in]valueThe value of the property. Must be a valid, non-empty span.
Precondition
properties must not be NULL.
name must be a valid span of size greater than 0.
value must be a valid span of size greater than 0.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe operation was performed successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThere was not enough space to append the property.

◆ 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.

Remarks
This will return the first value of the property with the given name if multiple properties with the same name exist.
Parameters
[in]propertiesThe az_iot_message_properties to use for this call.
[in]nameThe name of the property to search for.
[out]out_valueAn az_span containing the value of the found property.
Precondition
properties must not be NULL.
name must be a valid span of size greater than 0.
out_value must not be NULL.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe property was successfully found.
AZ_ERROR_ITEM_NOT_FOUNDThe property could not be found.

◆ 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.

Note
The properties must adhere to the character restrictions listed in the below link. https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-construct
Parameters
[in]propertiesThe az_iot_message_properties to initialize.
[in]bufferCan either be an unfilled (but properly sized) az_span or an az_span containing properly formatted (with above mentioned characters encoded if applicable) properties with the following format: {name}={value}&{name}={value}.
[in]written_lengthThe length of the properly formatted properties already initialized within the buffer. If the buffer is unfilled (uninitialized), this should be 0.
Precondition
properties must not be NULL.
buffer must be a valid span of size greater than 0.
written_length must be greater than or equal to 0.
Returns
An az_result value indicating the result of the operation.

◆ 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.

Parameters
[in]propertiesThe az_iot_message_properties to use for this call.
[out]out_nameA pointer to an az_span containing the name of the next property.
[out]out_valueA pointer to an az_span containing the value of the next property.
Precondition
properties must not be NULL.
out_name must not be NULL.
out_value must not be NULL.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKA property was retrieved successfully.
AZ_ERROR_IOT_END_OF_PROPERTIESThe API reached the end of the properties to retrieve.

◆ 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.

Parameters
[in]statusThe az_iot_status to verify.
Returns
true if the operation should be retried. false otherwise.

◆ 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.

Parameters
[in]statusThe az_iot_status to verify.
Returns
true if the status indicates success. false otherwise.