az_iot_provisioning_client.h

Go to the documentation of this file.

// Copyright (c) Microsoft Corporation. All rights reserved.
// SPDX-License-Identifier: MIT
 
#ifndef _az_IOT_PROVISIONING_CLIENT_H
#define _az_IOT_PROVISIONING_CLIENT_H
 
#include <azure/core/az_result.h>
#include <azure/core/az_span.h>
#include <azure/iot/az_iot_common.h>
 
#include <stdbool.h>
#include <stdint.h>
 
#include <azure/core/_az_cfg_prefix.h>
 
#define AZ_IOT_PROVISIONING_SERVICE_VERSION "2019-03-31"
 
typedef struct
{
  az_span user_agent;
} az_iot_provisioning_client_options;
 
typedef struct
{
  struct
  {
    az_span global_device_endpoint;
    az_span id_scope;
    az_span registration_id;
    az_iot_provisioning_client_options options;
  } _internal;
} az_iot_provisioning_client;
 
AZ_NODISCARD az_iot_provisioning_client_options az_iot_provisioning_client_options_default();
 
AZ_NODISCARD az_result az_iot_provisioning_client_init(
    az_iot_provisioning_client* client,
    az_span global_device_hostname,
    az_span id_scope,
    az_span registration_id,
    az_iot_provisioning_client_options const* options);
 
AZ_NODISCARD az_result az_iot_provisioning_client_get_user_name(
    az_iot_provisioning_client const* client,
    char* mqtt_user_name,
    size_t mqtt_user_name_size,
    size_t* out_mqtt_user_name_length);
 
AZ_NODISCARD az_result az_iot_provisioning_client_get_client_id(
    az_iot_provisioning_client const* client,
    char* mqtt_client_id,
    size_t mqtt_client_id_size,
    size_t* out_mqtt_client_id_length);
 
/*
 *
 * SAS Token APIs
 *
 *   Use the following APIs when the Shared Access Key is available to the application or stored
 *   within a Hardware Security Module. The APIs are not necessary if X509 Client Certificate
 *   Authentication is used.
 *
 *   The TPM Asymmetric Device Provisioning protocol is not supported on the MQTT protocol. TPMs can
 *   still be used to securely store and perform HMAC-SHA256 operations for SAS tokens.
 */
 
AZ_NODISCARD az_result az_iot_provisioning_client_sas_get_signature(
    az_iot_provisioning_client const* client,
    uint64_t token_expiration_epoch_time,
    az_span signature,
    az_span* out_signature);
 
AZ_NODISCARD az_result az_iot_provisioning_client_sas_get_password(
    az_iot_provisioning_client const* client,
    az_span base64_hmac_sha256_signature,
    uint64_t token_expiration_epoch_time,
    az_span key_name,
    char* mqtt_password,
    size_t mqtt_password_size,
    size_t* out_mqtt_password_length);
 
/*
 *
 * Register APIs
 *
 *   Use the following APIs when the Shared Access Key is available to the application or stored
 *   within a Hardware Security Module. The APIs are not necessary if X509 Client Certificate
 *   Authentication is used.
 */
 
#define AZ_IOT_PROVISIONING_CLIENT_REGISTER_SUBSCRIBE_TOPIC "$dps/registrations/res/#"
 
typedef struct
{
  az_span assigned_hub_hostname;
 
  az_span device_id;
 
  az_iot_status error_code;
 
  uint32_t extended_error_code;
 
  az_span error_message;
 
  az_span error_tracking_id;
 
  az_span error_timestamp;
 
  az_span payload;
 
} az_iot_provisioning_client_registration_state;
 
typedef enum
{
  AZ_IOT_PROVISIONING_STATUS_UNASSIGNED,
  AZ_IOT_PROVISIONING_STATUS_ASSIGNING,
 
  // Device assignment operation complete.
  AZ_IOT_PROVISIONING_STATUS_ASSIGNED,
 
  AZ_IOT_PROVISIONING_STATUS_FAILED,
 
  AZ_IOT_PROVISIONING_STATUS_DISABLED,
} az_iot_provisioning_client_operation_status;
 
typedef struct
{
  az_span operation_id;
 
  // Avoid using enum as the first field within structs, to allow for { 0 } initialization.
  // This is a workaround for IAR compiler warning [Pe188]: enumerated type mixed with another type.
 
  az_iot_status status;
 
  az_iot_provisioning_client_operation_status operation_status;
 
  uint32_t retry_after_seconds;
 
  az_iot_provisioning_client_registration_state registration_state;
} az_iot_provisioning_client_register_response;
 
AZ_NODISCARD az_result az_iot_provisioning_client_parse_received_topic_and_payload(
    az_iot_provisioning_client const* client,
    az_span received_topic,
    az_span received_payload,
    az_iot_provisioning_client_register_response* out_response);
 
AZ_INLINE bool az_iot_provisioning_client_operation_complete(
    az_iot_provisioning_client_operation_status operation_status)
{
  return (operation_status > AZ_IOT_PROVISIONING_STATUS_ASSIGNING);
}
 
AZ_NODISCARD az_result az_iot_provisioning_client_register_get_publish_topic(
    az_iot_provisioning_client const* client,
    char* mqtt_topic,
    size_t mqtt_topic_size,
    size_t* out_mqtt_topic_length);
 
AZ_NODISCARD az_result az_iot_provisioning_client_query_status_get_publish_topic(
    az_iot_provisioning_client const* client,
    az_span operation_id,
    char* mqtt_topic,
    size_t mqtt_topic_size,
    size_t* out_mqtt_topic_length);
 
typedef struct
{
  struct
  {
    bool unused;
  } _internal;
} az_iot_provisioning_client_payload_options;
 
AZ_NODISCARD az_iot_provisioning_client_payload_options
az_iot_provisioning_client_payload_options_default();
 
AZ_NODISCARD az_result az_iot_provisioning_client_register_get_request_payload(
    az_iot_provisioning_client const* client,
    az_span custom_payload_property,
    az_iot_provisioning_client_payload_options const* options,
    uint8_t* mqtt_payload,
    size_t mqtt_payload_size,
    size_t* out_mqtt_payload_length);
 
AZ_DEPRECATED AZ_NODISCARD az_result az_iot_provisioning_client_get_request_payload(
    az_iot_provisioning_client const* client,
    az_span custom_payload_property,
    az_iot_provisioning_client_payload_options const* options,
    uint8_t* mqtt_payload,
    size_t mqtt_payload_size,
    size_t* out_mqtt_payload_length);
 
#include <azure/core/_az_cfg_suffix.h>
 
#endif // _az_IOT_PROVISIONING_CLIENT_H