Definition for the Azure Device Provisioning client. More...

#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>
#include <azure/core/_az_cfg_suffix.h>

Data Structures
struct	az_iot_provisioning_client_options
	Azure IoT Provisioning Client options. More...

struct	az_iot_provisioning_client
	Azure IoT Provisioning Client. More...

struct	az_iot_provisioning_client_registration_state
	The registration operation state. More...

struct	az_iot_provisioning_client_register_response
	Register or query operation response. More...

Macros
#define	AZ_IOT_PROVISIONING_SERVICE_VERSION "2019-03-31"
	The client is fixed to a specific version of the Azure IoT Provisioning service.

#define	AZ_IOT_PROVISIONING_CLIENT_REGISTER_SUBSCRIBE_TOPIC "$dps/registrations/res/#"
	The MQTT topic filter to subscribe to register responses. More...

Enumerations
enum	az_iot_provisioning_client_operation_status { AZ_IOT_PROVISIONING_STATUS_UNASSIGNED, AZ_IOT_PROVISIONING_STATUS_ASSIGNING, AZ_IOT_PROVISIONING_STATUS_ASSIGNED, AZ_IOT_PROVISIONING_STATUS_FAILED, AZ_IOT_PROVISIONING_STATUS_DISABLED }
	Azure IoT Provisioning Service operation status.

Functions
AZ_NODISCARD az_iot_provisioning_client_options	az_iot_provisioning_client_options_default ()
	Gets the default Azure IoT Provisioning Client options. More...

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)
	Initializes an Azure IoT Provisioning Client. More...

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)
	Gets the MQTT user name. More...

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)
	Gets the MQTT client id. More...

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)
	Gets the Shared Access clear-text signature. More...

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)
	Gets the MQTT password. More...

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)
	Attempts to parse a received message's topic. More...

AZ_NODISCARD az_result	az_iot_provisioning_client_parse_operation_status (az_iot_provisioning_client_register_response response, az_iot_provisioning_client_operation_status out_operation_status)
	Returns the az_iot_provisioning_client_operation_status of a az_iot_provisioning_client_register_response object. More...

AZ_INLINE bool	az_iot_provisioning_client_operation_complete (az_iot_provisioning_client_operation_status operation_status)
	Checks if the status indicates that the service has an authoritative result of the register operation. The operation may have completed in either success or error. Completed states are AZ_IOT_PROVISIONING_STATUS_ASSIGNED, AZ_IOT_PROVISIONING_STATUS_FAILED, or AZ_IOT_PROVISIONING_STATUS_DISABLED. More...

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)
	Gets the MQTT topic that must be used to submit a Register request. More...

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)
	Gets the MQTT topic that must be used to submit a Register Status request. More...

Detailed Description

Definition for the Azure Device Provisioning client.

Remarks: The Device Provisioning MQTT protocol is described at https://docs.microsoft.com/en-us/azure/iot-dps/iot-dps-mqtt-support

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_PROVISIONING_CLIENT_REGISTER_SUBSCRIBE_TOPIC

#define AZ_IOT_PROVISIONING_CLIENT_REGISTER_SUBSCRIBE_TOPIC "$dps/registrations/res/#"

The MQTT topic filter to subscribe to register responses.

Remarks: Register MQTT Publish messages will have QoS At most once (0).

Function Documentation

◆ az_iot_provisioning_client_get_client_id()

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
	)

Gets the MQTT client id.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[out]	mqtt_client_id	A buffer with sufficient capacity to hold the MQTT client id. If successful, contains a null-terminated string with the client id that needs to be passed to the MQTT client.
[in]	mqtt_client_id_size	The size, in bytes of `mqtt_client_id`.
[out]	out_mqtt_client_id_length	[nullable] Contains the string length, in bytes, of of `mqtt_client_id`. Can be `NULL`.

Returns: An az_result value indicating the result of the operation.

◆ az_iot_provisioning_client_get_user_name()

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
	)

Gets the MQTT user name.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[out]	mqtt_user_name	A buffer with sufficient capacity to hold the MQTT user name. If successful, contains a null-terminated string with the user name that needs to be passed to the MQTT client.
[in]	mqtt_user_name_size	The size, in bytes of `mqtt_user_name`.
[out]	out_mqtt_user_name_length	[nullable] Contains the string length, in bytes, of `mqtt_user_name`. Can be `NULL`.

Returns: An az_result value indicating the result of the operation.

◆ az_iot_provisioning_client_init()

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
	)

Initializes an Azure IoT Provisioning Client.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	global_device_hostname	The device provisioning services global host name.
[in]	id_scope	The ID Scope.
[in]	registration_id	The Registration ID. This must match the client certificate name (CN part of the certificate subject).
[in]	options	[nullable] A reference to an az_iot_provisioning_client_options structure. Can be `NULL` for default options.

Returns: An az_result value indicating the result of the operation.

◆ az_iot_provisioning_client_operation_complete()

AZ_INLINE bool az_iot_provisioning_client_operation_complete ( az_iot_provisioning_client_operation_status operation_status )

Checks if the status indicates that the service has an authoritative result of the register operation. The operation may have completed in either success or error. Completed states are AZ_IOT_PROVISIONING_STATUS_ASSIGNED, AZ_IOT_PROVISIONING_STATUS_FAILED, or AZ_IOT_PROVISIONING_STATUS_DISABLED.

Parameters

[in] operation_status The az_iot_provisioning_client_operation_status obtained by calling az_iot_provisioning_client_parse_operation_status.

Returns: true if the operation completed. false otherwise.

◆ az_iot_provisioning_client_options_default()

AZ_NODISCARD az_iot_provisioning_client_options az_iot_provisioning_client_options_default ( )

Gets the default Azure IoT Provisioning Client options.

Call this to obtain an initialized az_iot_provisioning_client_options structure that can be afterwards modified and passed to az_iot_provisioning_client_init().

Returns: az_iot_provisioning_client_options.

◆ az_iot_provisioning_client_parse_operation_status()

AZ_NODISCARD az_result az_iot_provisioning_client_parse_operation_status	(	az_iot_provisioning_client_register_response *	response,
		az_iot_provisioning_client_operation_status *	out_operation_status
	)

Returns the az_iot_provisioning_client_operation_status of a az_iot_provisioning_client_register_response object.

Parameters

[in]	response	The az_iot_provisioning_client_register_response obtained after a successful call to az_iot_provisioning_client_parse_received_topic_and_payload().
[out]	out_operation_status	The registration operation status.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_ERROR_UNEXPECTED_CHAR If the string contains an unexpected value.

◆ az_iot_provisioning_client_parse_received_topic_and_payload()

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
	)

Attempts to parse a received message's topic.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	received_topic	An az_span containing the received MQTT topic.
[in]	received_payload	An az_span containing the received MQTT payload.
[out]	out_response	If the message is register-operation related, this will contain the az_iot_provisioning_client_register_response.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_ERROR_IOT_TOPIC_NO_MATCH If the topic is not matching the expected format.

◆ az_iot_provisioning_client_query_status_get_publish_topic()

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
	)

Gets the MQTT topic that must be used to submit a Register Status request.

Remarks: The payload of the MQTT publish message should be empty.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	operation_id	The received operation_id from the az_iot_provisioning_client_register_response response.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic filter. If successful, contains a null-terminated string with the topic filter that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes of `mqtt_topic`.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of `mqtt_topic`. Can be `NULL`.

Returns: An az_result value indicating the result of the operation.

◆ az_iot_provisioning_client_register_get_publish_topic()

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
	)

Gets the MQTT topic that must be used to submit a Register request.

Remarks: The payload of the MQTT publish message may contain a JSON document formatted according to the Provisioning Service's Device Registration document specification.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[out]	mqtt_topic	A buffer with sufficient capacity to hold the MQTT topic filter. If successful, contains a null-terminated string with the topic filter that needs to be passed to the MQTT client.
[in]	mqtt_topic_size	The size, in bytes of `mqtt_topic`.
[out]	out_mqtt_topic_length	[nullable] Contains the string length, in bytes, of `mqtt_topic`. Can be `NULL`.

Returns: An az_result value indicating the result of the operation.

◆ az_iot_provisioning_client_sas_get_password()

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
	)

Gets the MQTT password.

Remarks: The MQTT password must be an empty string if X509 Client certificates are used. Use this API only when authenticating with SAS tokens.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	base64_hmac_sha256_signature	The Base64 encoded value of the HMAC-SHA256(signature, SharedAccessKey). The signature is obtained by using az_iot_provisioning_client_sas_get_signature.
[in]	token_expiration_epoch_time	The time, in seconds, from 1/1/1970.
[in]	key_name	The Shared Access Key Name (Policy Name). This is optional. For security reasons we recommend using one key per device instead of using a global policy key.
[out]	mqtt_password	A buffer with sufficient capacity to hold the MQTT password. If successful, contains a null-terminated string with the password that needs to be passed to the MQTT client.
[in]	mqtt_password_size	The size, in bytes of `mqtt_password`.
[out]	out_mqtt_password_length	[nullable] Contains the string length, in bytes, of `mqtt_password`. Can be `NULL`.

Returns: An az_result value indicating the result of the operation..

◆ az_iot_provisioning_client_sas_get_signature()

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
	)

Gets the Shared Access clear-text signature.

The application must obtain a valid clear-text signature using this API, sign it using HMAC-SHA256 using the Shared Access Key as password then Base64 encode the result.

Remarks: More information available at https://docs.microsoft.com/en-us/azure/iot-dps/concepts-symmetric-key-attestation#detailed-attestation-process

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	token_expiration_epoch_time	The time, in seconds, from 1/1/1970.
[in]	signature	An empty az_span with sufficient capacity to hold the SAS signature.
[out]	out_signature	The output az_span containing the SAS signature.

Returns: An az_result value indicating the result of the operation.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AZ_IOT_PROVISIONING_CLIENT_REGISTER_SUBSCRIBE_TOPIC

Function Documentation

◆ az_iot_provisioning_client_get_client_id()

◆ az_iot_provisioning_client_get_user_name()

◆ az_iot_provisioning_client_init()

◆ az_iot_provisioning_client_operation_complete()

◆ az_iot_provisioning_client_options_default()

◆ az_iot_provisioning_client_parse_operation_status()

◆ az_iot_provisioning_client_parse_received_topic_and_payload()

◆ az_iot_provisioning_client_query_status_get_publish_topic()

◆ az_iot_provisioning_client_register_get_publish_topic()

◆ az_iot_provisioning_client_sas_get_password()

◆ az_iot_provisioning_client_sas_get_signature()