az_iot_common.h File Reference

Azure IoT common definitions. More...

#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"
	Supported IoT message properties. More...
#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"

Enumerations
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_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_PROPERTIES_CONTENT_ENCODING

#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING   "%24.ce"

UTF-8, UTF-16, etc.

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.

AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID

#define AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID    "%24.cid"

Used in distributed tracing. More information here: \ https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-distributed-tracing.

AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME

#define AZ_IOT_MESSAGE_PROPERTIES_CREATION_TIME   "%24.ctime"

Creation time of the message.

AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID

#define AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID    "%24.mid"

Supported IoT message properties.

Note

These can be used with IoT message property API's by wrapping the macros in a AZ_SPAN_FROM_STR marco as a parameter where needed. Add unique identification to a message.

AZ_IOT_MESSAGE_PROPERTIES_USER_ID

#define AZ_IOT_MESSAGE_PROPERTIES_USER_ID   "%24.uid"

User ID field.

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

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_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_msec	A random value between 0 and the maximum allowed jitter, in milliseconds.

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.

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.

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.

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.

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.