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>

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) }
	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/en-us/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

enum az_iot_status

Azure IoT service status codes.

Note: https://docs.microsoft.com/en-us/azure/iot-central/core/troubleshoot-connection#error-codes

◆ az_log_classification_iot

enum 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_result_iot

enum 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_msec	The time it took, in milliseconds, to perform the operation that failed.
[in]	attempt	The number of failed retry attempts.
[in]	min_retry_delay_msec	The minimum time, in milliseconds, to wait before a retry.
[in]	max_retry_delay_msec	The maximum time, in milliseconds, to wait before a retry.
[in]	random_jitter_msec	A 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 append API will not encode properties. In order to support the following characters, they must be percent-encoded (RFC3986) as follows: / : %2F % : %25 # : %23 & : %26 Only these characters would have to be encoded. If you would like to avoid the need to encode the names/values, avoid using these characters in names and values.

Parameters

[in]	properties	The az_iot_message_properties to use for this call.
[in]	name	The name of the property. Must be a valid, non-empty span.
[in]	value	The 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_OK	The operation was performed successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	There 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]	properties	The az_iot_message_properties to use for this call.
[in]	name	The name of the property to search for.
[out]	out_value	An 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_OK	The property was successfully found.
AZ_ERROR_ITEM_NOT_FOUND	The 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 init API will not encode properties. In order to support the following characters, they must be percent-encoded (RFC3986) as follows:

/ : %2F
% : %25
# : %23
& : %26 Only these characters would have to be encoded. If you would like to avoid the need to encode the names/values, avoid using these characters in names and values.

Parameters

[in]	properties	The az_iot_message_properties to initialize.
[in]	buffer	Can 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_length	The 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]	properties	The az_iot_message_properties to use for this call.
[out]	out_name	A pointer to an az_span containing the name of the next property.
[out]	out_value	A 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_OK	A property was retrieved successfully.
AZ_ERROR_IOT_END_OF_PROPERTIES	The 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] status The 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] status The az_iot_status to verify.

Returns: true if the status indicates success. false otherwise.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AZ_IOT_MESSAGE_COMPONENT_NAME

◆ AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING

◆ AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE

◆ AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID

◆ AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME

◆ AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID

◆ AZ_IOT_MESSAGE_PROPERTIES_USER_ID

Enumeration Type Documentation

◆ anonymous enum

◆ az_iot_status

◆ az_log_classification_iot

◆ az_result_iot

Function Documentation

◆ az_iot_calculate_retry_delay()

◆ az_iot_message_properties_append()

◆ az_iot_message_properties_find()

◆ az_iot_message_properties_init()

◆ az_iot_message_properties_next()

◆ az_iot_status_retriable()

◆ az_iot_status_succeeded()