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...

struct	az_iot_provisioning_client_payload_options
	Azure IoT Provisioning Client options for az_iot_provisioning_client_get_request_payload() and az_iot_provisioning_client_register_get_request_payload(). 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. More...

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_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: 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...

AZ_NODISCARD az_iot_provisioning_client_payload_options	az_iot_provisioning_client_payload_options_default ()
	Gets the default az_iot_provisioning_client_payload_options. More...

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)
	Builds the optional payload for a provisioning request. More...

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)
	Builds the optional payload for a provisioning request. More...

Detailed Description

Definition for the Azure Device Provisioning client.

Remarks: The Device Provisioning MQTT protocol is described at https://docs.microsoft.com/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).

Enumeration Type Documentation

◆ az_iot_provisioning_client_operation_status

enum az_iot_provisioning_client_operation_status

Azure IoT Provisioning Service operation status.

Enumerator
AZ_IOT_PROVISIONING_STATUS_UNASSIGNED	Starting state (not assigned).
AZ_IOT_PROVISIONING_STATUS_ASSIGNING	Assigning in progress.
AZ_IOT_PROVISIONING_STATUS_ASSIGNED	Device was assigned successfully.
AZ_IOT_PROVISIONING_STATUS_FAILED	The provisioning for the device failed.
AZ_IOT_PROVISIONING_STATUS_DISABLED	The provisioning for this device was disabled.

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`.

Precondition: client must not be NULL.; mqtt_client_id must not be NULL.; mqtt_client_id_size must be greater than 0.

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

Return values

AZ_OK	The client id was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_iot_provisioning_client_get_request_payload()

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
	)

Builds the optional payload for a provisioning request.

Deprecated:: since 1.5.0-beta.1.

See also: az_iot_provisioning_client_register_get_request_payload

Remarks: Use this API to build an MQTT payload during registration. This call is optional for most scenarios. Some service applications may require custom_payload_property specified during registration to make additional decisions during provisioning time. For example, if you need to register an IoT Plug and Play device you must specify its model_id with this API via the custom_payload_property {"modelId":"your_model_id"}.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	custom_payload_property	[nullable] Custom JSON to be added to this payload. Can be `NULL`.
[in]	options	[nullable] Reserved field for future options to this function. Must be `NULL`.
[out]	mqtt_payload	A buffer with sufficient capacity to hold the MQTT payload.
[in]	mqtt_payload_size	The size, in bytes of `mqtt_payload`.
[out]	out_mqtt_payload_length	Contains the length, in bytes, written to `mqtt_payload` on success.

Precondition: client must not be NULL.; options must be NULL.; mqtt_payload must not be NULL.; mqtt_payload_size must be greater than 0.; out_mqtt_payload_length must not be NULL.

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

Return values

AZ_OK	The payload was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ 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`.

Precondition: client must not be NULL.; mqtt_user_name must not be NULL.; mqtt_user_name_size must be greater than 0.

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

Return values

AZ_OK	The user name was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ 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). Must conform to the limitations listed in the link below: https://docs.microsoft.com/azure/iot-dps/concepts-service#registration-id
[in]	options	[nullable] A reference to an az_iot_provisioning_client_options structure. If `NULL` is passed, the provisioning client will use the default options. If using custom options, please initialize first by calling az_iot_provisioning_client_options_default() and then populating relevant options with your own values.

Precondition: client must not be NULL.; global_device_hostname must be a valid span of size greater than 0.; id_scope must be a valid span of size greater than 0.; registration_id 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 client was initialized successfully.

◆ 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:

Parameters

[in] operation_status The status used to check if the operation completed.

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_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.

Precondition: client must not be NULL.; received_topic must be a valid span of size greater than or equal to 0.; received_payload must be a valid span of size greater than or equal to 0.; out_response must not be NULL.

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

Return values

AZ_OK	The topic and payload were parsed successfully.
AZ_ERROR_IOT_TOPIC_NO_MATCH	If the topic is not matching the expected format.

◆ az_iot_provisioning_client_payload_options_default()

AZ_NODISCARD az_iot_provisioning_client_payload_options az_iot_provisioning_client_payload_options_default ( )

Gets the default az_iot_provisioning_client_payload_options.

Call this to obtain an initialized az_iot_provisioning_client_payload_options structure that can be afterwards modified and passed to az_iot_provisioning_client_register_get_request_payload.

Returns: az_iot_provisioning_client_payload_options.

◆ 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`.

Precondition: client must not be NULL.; operation_id must be a valid span of size greater than 0.; mqtt_topic must not be NULL.; mqtt_topic_size must be greater than 0.

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

Return values

AZ_OK	The topic was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ 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`.

Precondition: client must not be NULL.; mqtt_topic must not be NULL.; mqtt_topic_size must be greater than 0.

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

Return values

AZ_OK	The topic was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_iot_provisioning_client_register_get_request_payload()

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
	)

Builds the optional payload for a provisioning request.

Remarks: Use this API to build an MQTT payload during device registration. This call is optional for most scenarios. Some service applications may require custom_payload_property specified during registration to make additional decisions during provisioning time. For example, if you need to register an IoT Plug and Play device you must specify its model_id with this API via the custom_payload_property {"modelId":"your_model_id"}.

Parameters

[in]	client	The az_iot_provisioning_client to use for this call.
[in]	custom_payload_property	[nullable] Custom JSON to be added to this payload. Can be `NULL`.
[in]	options	A reference to an az_iot_provisioning_client_payload_options structure. Must be initialized first by calling az_iot_provisioning_client_payload_options_default() and then populating relevant options with your own values.
[out]	mqtt_payload	A buffer with sufficient capacity to hold the MQTT payload.
[in]	mqtt_payload_size	The size, in bytes of `mqtt_payload`.
[out]	out_mqtt_payload_length	Contains the length, in bytes, written to `mqtt_payload` on success.

Precondition: client must not be NULL.; mqtt_payload must not be NULL.; mqtt_payload_size must be greater than 0.; out_mqtt_payload_length must not be NULL.

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

Return values

AZ_OK	The payload was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ 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`.

Precondition: client must not be NULL.; base64_hmac_sha256_signature must be a valid span of size greater than 0.; token_expiration_epoch_time must be greater than 0.; mqtt_password must not be NULL.; mqtt_password_size must be greater than 0.

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

Return values

AZ_OK	The password was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ 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/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.

Precondition: client must not be NULL.; token_expiration_epoch_time must be greater than 0.; signature must be a valid span of size greater than 0.; out_signature must not be NULL.

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

Return values

AZ_OK	The signature was created successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AZ_IOT_PROVISIONING_CLIENT_REGISTER_SUBSCRIBE_TOPIC

Enumeration Type Documentation

◆ az_iot_provisioning_client_operation_status

Function Documentation

◆ az_iot_provisioning_client_get_client_id()

◆ az_iot_provisioning_client_get_request_payload()

◆ 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_received_topic_and_payload()

◆ az_iot_provisioning_client_payload_options_default()

◆ az_iot_provisioning_client_query_status_get_publish_topic()

◆ az_iot_provisioning_client_register_get_publish_topic()

◆ az_iot_provisioning_client_register_get_request_payload()

◆ az_iot_provisioning_client_sas_get_password()

◆ az_iot_provisioning_client_sas_get_signature()