az_iot_common.h

Go to the documentation of this file.

// Copyright (c) Microsoft Corporation. All rights reserved.
// SPDX-License-Identifier: MIT
 
#ifndef _az_IOT_CORE_H
#define _az_IOT_CORE_H
 
#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>
 
enum az_result_iot
{
  // === IoT error codes ===
  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),
};
 
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), 
};
 
enum
{
  AZ_IOT_DEFAULT_MQTT_CONNECT_PORT = 8883,
  AZ_IOT_DEFAULT_MQTT_CONNECT_KEEPALIVE_SECONDS = 240
};
 
typedef enum
{
  // Default, unset value
  AZ_IOT_STATUS_UNKNOWN = 0,
 
  // Service success codes
  AZ_IOT_STATUS_OK = 200,
  AZ_IOT_STATUS_ACCEPTED = 202,
  AZ_IOT_STATUS_NO_CONTENT = 204,
 
  // Service error codes
  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,
} az_iot_status;
 
/*
 *
 * Properties APIs
 *
 *   IoT message properties are used for Device-to-Cloud (D2C) as well as Cloud-to-Device (C2D).
 *   Properties are always appended to the MQTT topic of the published or received message and
 *   must contain percent-encoded names and values.
 */
 
#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"
 
typedef struct
{
  struct
  {
    az_span properties_buffer;
    int32_t properties_written;
    uint32_t current_property_index;
  } _internal;
} az_iot_message_properties;
 
AZ_NODISCARD az_result az_iot_message_properties_init(
    az_iot_message_properties* properties,
    az_span buffer,
    int32_t written_length);
 
AZ_NODISCARD az_result az_iot_message_properties_append(
    az_iot_message_properties* properties,
    az_span name,
    az_span value);
 
AZ_NODISCARD az_result az_iot_message_properties_find(
    az_iot_message_properties* properties,
    az_span name,
    az_span* out_value);
 
AZ_NODISCARD az_result az_iot_message_properties_next(
    az_iot_message_properties* properties,
    az_span* out_name,
    az_span* out_value);
 
AZ_NODISCARD AZ_INLINE bool az_iot_status_succeeded(az_iot_status status)
{
  return status < AZ_IOT_STATUS_BAD_REQUEST;
}
 
AZ_NODISCARD AZ_INLINE bool az_iot_status_retriable(az_iot_status status)
{
  return ((status == AZ_IOT_STATUS_THROTTLED) || (status == AZ_IOT_STATUS_SERVER_ERROR));
}
 
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);
 
#include <azure/core/_az_cfg_suffix.h>
 
#endif // _az_IOT_CORE_H