The middleware IoT Provisioning Client used to connect a device to Azure IoT Device Provisioning. More...

#include "FreeRTOS.h"
#include "azure_iot.h"
#include "azure_iot_result.h"
#include "azure_iot_mqtt_port.h"
#include "azure_iot_transport_interface.h"
#include "azure/iot/az_iot_common.h"
#include "azure/iot/az_iot_provisioning_client.h"
#include "azure/core/_az_cfg_prefix.h"
#include "azure/core/_az_cfg_suffix.h"

Data Structures
struct	AzureIoTProvisioningClientOptions
	The options for the Azure IoT Device Provisioning client. More...

struct	AzureIoTProvisioningClient
	The Azure IoT Device Provisioning client. More...

Macros
#define	azureiotprovisioningRESPONSE_MAX ( azureiotconfigTOPIC_MAX + azureiotconfigPROVISIONING_REQUEST_PAYLOAD_MAX )
	The maximum size of the response buffer.

#define	azureiotprovisioningNO_WAIT ( 0 )
	Do not wait on the function call.

#define	azureiotprovisioningWAIT_FOREVER ( ( uint32_t ) 0xFFFFFFFF )
	Wait as long as it takes to complete the operation (success or failure)

Typedefs
typedef struct AzureIoTProvisioningClientOptions	AzureIoTProvisioningClientOptions_t
	The options for the Azure IoT Device Provisioning client.

typedef struct AzureIoTProvisioningClient	AzureIoTProvisioningClient_t
	The Azure IoT Device Provisioning client.

Functions
AzureIoTResult_t	AzureIoTProvisioningClient_OptionsInit (AzureIoTProvisioningClientOptions_t *pxProvisioningClientOptions)
	Initialize the Azure IoT Provisioning Options with default values. More...

AzureIoTResult_t	AzureIoTProvisioningClient_Init (AzureIoTProvisioningClient_t pxAzureProvClient, const uint8_t pucEndpoint, uint32_t ulEndpointLength, const uint8_t pucIDScope, uint32_t ulIDScopeLength, const uint8_t pucRegistrationID, uint32_t ulRegistrationIDLength, AzureIoTProvisioningClientOptions_t pxProvisioningClientOptions, uint8_t pucBuffer, uint32_t ulBufferLength, AzureIoTGetCurrentTimeFunc_t xGetTimeFunction, const AzureIoTTransportInterface_t *pxTransportInterface)
	Initialize the Azure IoT Provisioning Client. More...

void	AzureIoTProvisioningClient_Deinit (AzureIoTProvisioningClient_t *pxAzureProvClient)
	Deinitialize the Azure IoT Provisioning Client. More...

AzureIoTResult_t	AzureIoTProvisioningClient_SetSymmetricKey (AzureIoTProvisioningClient_t pxAzureProvClient, const uint8_t pucSymmetricKey, uint32_t ulSymmetricKeyLength, AzureIoTGetHMACFunc_t xHmacFunction)
	Set the symmetric key to use for authentication. More...

AzureIoTResult_t	AzureIoTProvisioningClient_Register (AzureIoTProvisioningClient_t *pxAzureProvClient, uint32_t ulTimeoutMilliseconds)
	Begin the provisioning process. More...

AzureIoTResult_t	AzureIoTProvisioningClient_GetDeviceAndHub (AzureIoTProvisioningClient_t pxAzureProvClient, uint8_t pucHubHostname, uint32_t pulHostnameLength, uint8_t pucDeviceID, uint32_t *pulDeviceIDLength)
	After a registration has been completed, get the IoT Hub hostname and device ID. More...

AzureIoTResult_t	AzureIoTProvisioningClient_GetExtendedCode (AzureIoTProvisioningClient_t pxAzureProvClient, uint32_t pulExtendedErrorCode)
	Get extended code for Provisioning failure. More...

AzureIoTResult_t	AzureIoTProvisioningClient_SetRegistrationPayload (AzureIoTProvisioningClient_t pxAzureProvClient, const uint8_t pucPayload, uint32_t ulPayloadLength)
	Set registration payload. More...

Detailed Description

The middleware IoT Provisioning Client used to connect a device to Azure IoT Device Provisioning.

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.

Function Documentation

◆ AzureIoTProvisioningClient_Deinit()

void AzureIoTProvisioningClient_Deinit ( AzureIoTProvisioningClient_t * pxAzureProvClient )

Deinitialize the Azure IoT Provisioning Client.

Parameters

pxAzureProvClient The AzureIoTProvisioningClient_t * to use for this call.

◆ AzureIoTProvisioningClient_GetDeviceAndHub()

AzureIoTResult_t AzureIoTProvisioningClient_GetDeviceAndHub	(	AzureIoTProvisioningClient_t *	pxAzureProvClient,
		uint8_t *	pucHubHostname,
		uint32_t *	pulHostnameLength,
		uint8_t *	pucDeviceID,
		uint32_t *	pulDeviceIDLength
	)

After a registration has been completed, get the IoT Hub hostname and device ID.

Parameters

[in]	pxAzureProvClient	The AzureIoTProvisioningClient_t * to use for this call.
[out]	pucHubHostname	The pointer to a buffer which will be populated with the IoT Hub hostname.
[out]	pulHostnameLength	The pointer to the `uint32_t` which will be populated with the length of the hostname.
[out]	pucDeviceID	The pointer to a buffer which will be populated with the device ID.
[out]	pulDeviceIDLength	The pointer to the uint32_t which will be populated with the length of the device ID.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTProvisioningClient_GetExtendedCode()

AzureIoTResult_t AzureIoTProvisioningClient_GetExtendedCode	(	AzureIoTProvisioningClient_t *	pxAzureProvClient,
		uint32_t *	pulExtendedErrorCode
	)

Get extended code for Provisioning failure.

Note: Extended code is 6 digit error code last returned via the Provisioning service, when registration is done.

Parameters

[in]	pxAzureProvClient	The AzureIoTProvisioningClient_t * to use for this call.
[out]	pulExtendedErrorCode	The pointer to the uint32_t which will be populated with the extended code.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTProvisioningClient_Init()

AzureIoTResult_t AzureIoTProvisioningClient_Init	(	AzureIoTProvisioningClient_t *	pxAzureProvClient,
		const uint8_t *	pucEndpoint,
		uint32_t	ulEndpointLength,
		const uint8_t *	pucIDScope,
		uint32_t	ulIDScopeLength,
		const uint8_t *	pucRegistrationID,
		uint32_t	ulRegistrationIDLength,
		AzureIoTProvisioningClientOptions_t *	pxProvisioningClientOptions,
		uint8_t *	pucBuffer,
		uint32_t	ulBufferLength,
		AzureIoTGetCurrentTimeFunc_t	xGetTimeFunction,
		const AzureIoTTransportInterface_t *	pxTransportInterface
	)

Initialize the Azure IoT Provisioning Client.

Parameters

[out]	pxAzureProvClient	The AzureIoTProvisioningClient_t * to use for this call.
[in]	pucEndpoint	The IoT Provisioning Hostname.
[in]	ulEndpointLength	The length of the IoT Provisioning Hostname.
[in]	pucIDScope	The ID scope to use for provisioning.
[in]	ulIDScopeLength	The length of the ID scope.
[in]	pucRegistrationID	The registration ID to use for provisioning.
[in]	ulRegistrationIDLength	The length of the registration ID.
[in]	pxProvisioningClientOptions	The AzureIoTProvisioningClientOptions_t for the IoT Provisioning client instance.
[in]	pucBuffer	The buffer to use for MQTT messages.
[in]	ulBufferLength	bufferLength The length of the `pucBuffer`.
[in]	xGetTimeFunction	A function pointer to a function which gives the current epoch time.
[in]	pxTransportInterface	The transport interface to use for the MQTT library.

Returns: AzureIoTResult_t

◆ AzureIoTProvisioningClient_OptionsInit()

AzureIoTResult_t AzureIoTProvisioningClient_OptionsInit ( AzureIoTProvisioningClientOptions_t * pxProvisioningClientOptions )

Initialize the Azure IoT Provisioning Options with default values.

Parameters

[out] pxProvisioningClientOptions The AzureIoTProvisioningClientOptions_t instance to set with default values.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTProvisioningClient_Register()

AzureIoTResult_t AzureIoTProvisioningClient_Register	(	AzureIoTProvisioningClient_t *	pxAzureProvClient,
		uint32_t	ulTimeoutMilliseconds
	)

Begin the provisioning process.

The initial call to this function will issue the request to the service to provision this device. If this function is called with the same pxAzureProvClient after a previous call to it returned "eAzureIoTErrorPending", then the function will simply poll to see if the registration has succeeded or failed. After a successful result, AzureIoTProvisioningClient_GetDeviceAndHub() can be called to get the IoT Hub and device ID.

Parameters

[in]	pxAzureProvClient	The AzureIoTProvisioningClient_t * to use for this call.
[in]	ulTimeoutMilliseconds	Timeout in milliseconds to wait for registration to finish.

Returns

An AzureIoTResult_t with the result of the operation.

eAzureIoTErrorPending registration is still in progess.
eAzureIoTErrorOutOfMemory registration failed because the device is out of memory.
eAzureIoTErrorServerError registration failed because of a server error.
eAzureIoTErrorFailed registration failed because of an internal error.
eAzureIoTSuccess registration is completed.

◆ AzureIoTProvisioningClient_SetRegistrationPayload()

AzureIoTResult_t AzureIoTProvisioningClient_SetRegistrationPayload	(	AzureIoTProvisioningClient_t *	pxAzureProvClient,
		const uint8_t *	pucPayload,
		uint32_t	ulPayloadLength
	)

Set registration payload.

This routine sets registration payload, which is JSON object.

Parameters

[in]	pxAzureProvClient	The AzureIoTProvisioningClient_t * to use for this call.
[in]	pucPayload	A pointer to registration payload.
[in]	ulPayloadLength	Length of `payload`. Does not include the `NULL` terminator.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTProvisioningClient_SetSymmetricKey()

AzureIoTResult_t AzureIoTProvisioningClient_SetSymmetricKey	(	AzureIoTProvisioningClient_t *	pxAzureProvClient,
		const uint8_t *	pucSymmetricKey,
		uint32_t	ulSymmetricKeyLength,
		AzureIoTGetHMACFunc_t	xHmacFunction
	)

Set the symmetric key to use for authentication.

Note: For X509 cert based authentication, application configures its transport with client side certificate.

Parameters

[in]	pxAzureProvClient	The AzureIoTProvisioningClient_t * to use for this call.
[in]	pucSymmetricKey	The symmetric key to use for the connection.
[in]	ulSymmetricKeyLength	The length of the `pucSymmetricKey`.
[in]	xHmacFunction	The AzureIoTGetHMACFunc_t function pointer to a function which computes the HMAC256 over a set of bytes.

Returns: An AzureIoTResult_t with the result of the operation.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ AzureIoTProvisioningClient_Deinit()

◆ AzureIoTProvisioningClient_GetDeviceAndHub()

◆ AzureIoTProvisioningClient_GetExtendedCode()

◆ AzureIoTProvisioningClient_Init()

◆ AzureIoTProvisioningClient_OptionsInit()

◆ AzureIoTProvisioningClient_Register()

◆ AzureIoTProvisioningClient_SetRegistrationPayload()

◆ AzureIoTProvisioningClient_SetSymmetricKey()