Definition for the Azure IoT ADU Client. More...

#include <stdint.h>
#include "azure_iot_result.h"
#include "azure_iot_hub_client.h"
#include "azure_iot_json_reader.h"
#include <azure/iot/az_iot_adu_client.h>

Go to the source code of this file.

Data Structures
struct	AzureIoTADUDeviceCustomProperties
	Holds any user-defined custom properties of the device. More...

struct	AzureIoTADUClientDeviceProperties
	ADU Device Properties. More...

struct	AzureIoTADUClientWorkflow
	ADU workflow struct. More...

struct	AzureIoTADUClientStepResult
	The update step result reported by the agent. More...

struct	AzureIoTADUClientInstallResult
	The update result reported by the agent. More...

struct	AzureIoTADUUpdateManifestFileUrl
	A map of file ID to download url. More...

struct	AzureIoTADUUpdateId
	Identity of the update request. More...

struct	AzureIoTADUInstructionStepFile
	The name of a file referenced in the update manifest. More...

struct	AzureIoTADUUpdateManifestFileHash
	Hash value of a given file. More...

struct	AzureIoTADUUpdateManifestFile
	Details of a file referenced in the update request. More...

struct	AzureIoTADUInstructionStep
	A step in the instructions of an ADU update manifest. More...

struct	AzureIoTADUInstructions
	Instructions in the update manifest. More...

struct	AzureIoTADUUpdateManifest
	Structure that holds the parsed contents of the update manifest sent by the ADU service. More...

struct	AzureIoTADUUpdateRequest
	Structure that holds the parsed contents of the ADU request in the Plug and Play writable properties sent by the ADU service. More...

struct	AzureIoTADUClientOptions
	User-defined options for the Azure IoT ADU client. More...

struct	AzureIoTADUClient
	Azure IoT ADU Client (ADU agent) to handle stages of the ADU process. More...

Typedefs
typedef struct AzureIoTADUDeviceCustomProperties	AzureIoTADUDeviceCustomProperties_t
	Holds any user-defined custom properties of the device. More...

typedef struct AzureIoTADUClientDeviceProperties	AzureIoTADUClientDeviceProperties_t
	ADU Device Properties. More...

typedef enum AzureIoTADUAction	AzureIoTADUAction_t
	Actions requested by the ADU Service.

typedef struct AzureIoTADUClientWorkflow	AzureIoTADUClientWorkflow_t
	ADU workflow struct. More...

typedef struct AzureIoTADUClientStepResult	AzureIoTADUClientStepResult_t
	The update step result reported by the agent.

typedef struct AzureIoTADUClientInstallResult	AzureIoTADUClientInstallResult_t
	The update result reported by the agent.

typedef enum AzureIoTADUAgentState	AzureIoTADUAgentState_t
	States of the ADU agent. More...

typedef enum AzureIoTADURequestDecision	AzureIoTADURequestDecision_t
	Decision values for accepting an update request or not.

typedef struct AzureIoTADUUpdateManifestFileUrl	AzureIoTADUUpdateManifestFileUrl_t
	A map of file ID to download url.

typedef struct AzureIoTADUUpdateId	AzureIoTADUUpdateId_t
	Identity of the update request. More...

typedef struct AzureIoTADUInstructionStepFile	AzureIoTADUUpdateManifestInstructionStepFile_t
	The name of a file referenced in the update manifest.

typedef struct AzureIoTADUUpdateManifestFileHash	AzureIoTADUUpdateManifestFileHash_t
	Hash value of a given file.

typedef struct AzureIoTADUUpdateManifestFile	AzureIoTADUUpdateManifestFile_t
	Details of a file referenced in the update request.

typedef struct AzureIoTADUInstructionStep	AzureIoTADUInstructionStep_t
	A step in the instructions of an ADU update manifest.

typedef struct AzureIoTADUInstructions	AzureIoTADUInstructions_t
	Instructions in the update manifest.

typedef struct AzureIoTADUUpdateManifest	AzureIoTADUUpdateManifest_t
	Structure that holds the parsed contents of the update manifest sent by the ADU service.

typedef struct AzureIoTADUUpdateRequest	AzureIoTADUUpdateRequest_t
	Structure that holds the parsed contents of the ADU request in the Plug and Play writable properties sent by the ADU service.

typedef struct AzureIoTADUClientOptions	AzureIoTADUClientOptions_t
	User-defined options for the Azure IoT ADU client.

typedef struct AzureIoTADUClient	AzureIoTADUClient_t
	Azure IoT ADU Client (ADU agent) to handle stages of the ADU process.

Enumerations
enum	AzureIoTADUAction { eAzureIoTADUActionApplyDownload = 3 , eAzureIoTADUActionCancel = 255 }
	Actions requested by the ADU Service.

enum	AzureIoTADUAgentState { eAzureIoTADUAgentStateIdle = 0 , eAzureIoTADUAgentStateDeploymentInProgress = 6 , eAzureIoTADUAgentStateFailed = 255 , eAzureIoTADUAgentStateError }
	States of the ADU agent. More...

enum	AzureIoTADURequestDecision { eAzureIoTADURequestDecisionAccept , eAzureIoTADURequestDecisionReject }
	Decision values for accepting an update request or not.

Functions
AzureIoTResult_t	AzureIoTADUClient_OptionsInit (AzureIoTADUClientOptions_t *pxADUClientOptions)
	Initialize the Azure IoT ADU Options with default values. More...

AzureIoTResult_t	AzureIoTADUClient_Init (AzureIoTADUClient_t pxAzureIoTADUClient, AzureIoTADUClientOptions_t pxADUClientOptions)
	Initialize the Azure IoT ADU Client. More...

AzureIoTResult_t	AzureIoTADUClient_DevicePropertiesInit (AzureIoTADUClientDeviceProperties_t *pxADUDeviceProperties)
	Initialize the Azure IoT Device Properties with default values. More...

bool	AzureIoTADUClient_IsADUComponent (AzureIoTADUClient_t pxAzureIoTADUClient, const uint8_t pucComponentName, uint32_t ulComponentNameLength)
	Returns whether the component is the ADU component. More...

AzureIoTResult_t	AzureIoTADUClient_ParseRequest (AzureIoTADUClient_t pxAzureIoTADUClient, AzureIoTJSONReader_t pxReader, AzureIoTADUUpdateRequest_t *pxAduUpdateRequest)
	Parse the ADU update request into the requisite structure. More...

AzureIoTResult_t	AzureIoTADUClient_SendResponse (AzureIoTADUClient_t pxAzureIoTADUClient, AzureIoTHubClient_t pxAzureIoTHubClient, AzureIoTADURequestDecision_t xRequestDecision, uint32_t ulPropertyVersion, uint8_t pucWritablePropertyResponseBuffer, uint32_t ulWritablePropertyResponseBufferSize, uint32_t pulRequestId)
	Updates the ADU Agent Client with ADU service device update properties. More...

AzureIoTResult_t	AzureIoTADUClient_SendAgentState (AzureIoTADUClient_t pxAzureIoTADUClient, AzureIoTHubClient_t pxAzureIoTHubClient, AzureIoTADUClientDeviceProperties_t pxDeviceProperties, AzureIoTADUUpdateRequest_t pxAduUpdateRequest, AzureIoTADUAgentState_t xAgentState, AzureIoTADUClientInstallResult_t pxUpdateResults, uint8_t pucBuffer, uint32_t ulBufferSize, uint32_t *pulRequestId)
	Sends the current state of the Azure IoT ADU agent. More...

Variables
const uint8_t *	AzureIoTADUModelID
	The DTMI specifying the capabilities for the Azure Device Update client. More...

const uint32_t	AzureIoTADUModelIDLength
	The length of AzureIoTADUModelID.

Detailed Description

Definition for the Azure IoT ADU Client.

Typedef Documentation

◆ AzureIoTADUAgentState_t

typedef enum AzureIoTADUAgentState AzureIoTADUAgentState_t

States of the ADU agent.

Remarks: State is reported in response to an update request Action.

https://docs.microsoft.com/en-us/azure/iot-hub-device-update/device-update-plug-and-play#state

◆ AzureIoTADUClientDeviceProperties_t

typedef struct AzureIoTADUClientDeviceProperties AzureIoTADUClientDeviceProperties_t

ADU Device Properties.

https://docs.microsoft.com/en-us/azure/iot-hub-device-update/understand-device-update#device-update-agent

Note: AzureIoTADUClient_DevicePropertiesInit() should be called first to initialize this struct.

◆ AzureIoTADUClientWorkflow_t

typedef struct AzureIoTADUClientWorkflow AzureIoTADUClientWorkflow_t

ADU workflow struct.

Remarks: Format: { "action": 3, "id": "someguid", "retryTimestamp": "2020-04-22T12:12:12.0000000+00:00" }

https://docs.microsoft.com/en-us/azure/iot-hub-device-update/understand-device-update#device-update-agent

◆ AzureIoTADUDeviceCustomProperties_t

typedef struct AzureIoTADUDeviceCustomProperties AzureIoTADUDeviceCustomProperties_t

Holds any user-defined custom properties of the device.

Remarks: Implementer can define other device properties to be used for the compatibility check while targeting the update deployment.

◆ AzureIoTADUUpdateId_t

typedef struct AzureIoTADUUpdateId AzureIoTADUUpdateId_t

Identity of the update request.

Remarks: This version refers to the update request itself. For verifying if an update request is applicable to an ADU agent, use the update manifest instructions steps "installed criteria".

Enumeration Type Documentation

◆ AzureIoTADUAgentState

enum AzureIoTADUAgentState

States of the ADU agent.

Remarks: State is reported in response to an update request Action.

https://docs.microsoft.com/en-us/azure/iot-hub-device-update/device-update-plug-and-play#state

Function Documentation

◆ AzureIoTADUClient_DevicePropertiesInit()

AzureIoTResult_t AzureIoTADUClient_DevicePropertiesInit ( AzureIoTADUClientDeviceProperties_t * pxADUDeviceProperties )

Initialize the Azure IoT Device Properties with default values.

Parameters

[out] pxADUDeviceProperties The AzureIoTADUClientDeviceProperties_t instance to set with default values.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTADUClient_Init()

AzureIoTResult_t AzureIoTADUClient_Init	(	AzureIoTADUClient_t *	pxAzureIoTADUClient,
		AzureIoTADUClientOptions_t *	pxADUClientOptions
	)

Initialize the Azure IoT ADU Client.

Parameters

[in]	pxAzureIoTADUClient	The AzureIoTADUClient_t * to use for this call.
[in]	pxADUClientOptions	The AzureIoTADUClientOptions_t for the IoT ADU client instance.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTADUClient_IsADUComponent()

bool AzureIoTADUClient_IsADUComponent	(	AzureIoTADUClient_t *	pxAzureIoTADUClient,
		const uint8_t *	pucComponentName,
		uint32_t	ulComponentNameLength
	)

Returns whether the component is the ADU component.

Note: If it is, user should follow by parsing the component with the AzureIoTHubClient_ADUProcessComponent() call. The properties will be processed into the AzureIoTADUClient.

Parameters

[in]	pxAzureIoTADUClient	The AzureIoTADUClient_t * to use for this call.
[in]	pucComponentName	Name of writable properties component to be checked.
[in]	ulComponentNameLength	Length of `pucComponentName`.

Returns: A boolean value indicating if the writable properties component is from ADU service.

◆ AzureIoTADUClient_OptionsInit()

AzureIoTResult_t AzureIoTADUClient_OptionsInit ( AzureIoTADUClientOptions_t * pxADUClientOptions )

Initialize the Azure IoT ADU Options with default values.

Parameters

[out] pxADUClientOptions The AzureIoTADUClientOptions_t instance to set with default values.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTADUClient_ParseRequest()

AzureIoTResult_t AzureIoTADUClient_ParseRequest	(	AzureIoTADUClient_t *	pxAzureIoTADUClient,
		AzureIoTJSONReader_t *	pxReader,
		AzureIoTADUUpdateRequest_t *	pxAduUpdateRequest
	)

Parse the ADU update request into the requisite structure.

The JSON reader returned to the caller from AzureIoTHubClientProperties_GetNextComponentProperty() should be passed to this API.

Parameters

[in]	pxAzureIoTADUClient	The AzureIoTADUClient_t * to use for this call.
[in,out]	pxReader	The initialized JSON reader positioned at the beginning of the ADU subcomponent property.
[out]	pxAduUpdateRequest	The AzureIoTADUUpdateRequest_t into which the properties will be parsed.

Returns: AzureIoTResult_t An AzureIoTResult_t with the result of the operation.

◆ AzureIoTADUClient_SendAgentState()

AzureIoTResult_t AzureIoTADUClient_SendAgentState	(	AzureIoTADUClient_t *	pxAzureIoTADUClient,
		AzureIoTHubClient_t *	pxAzureIoTHubClient,
		AzureIoTADUClientDeviceProperties_t *	pxDeviceProperties,
		AzureIoTADUUpdateRequest_t *	pxAduUpdateRequest,
		AzureIoTADUAgentState_t	xAgentState,
		AzureIoTADUClientInstallResult_t *	pxUpdateResults,
		uint8_t *	pucBuffer,
		uint32_t	ulBufferSize,
		uint32_t *	pulRequestId
	)

Sends the current state of the Azure IoT ADU agent.

Parameters

[in]	pxAzureIoTADUClient	The AzureIoTADUClient_t * to use for this call.
[in]	pxAzureIoTHubClient	The AzureIoTHubClient_t * to use for this call.
[in]	pxDeviceProperties	The device information which will be used to generate the payload.
[in]	pxAduUpdateRequest	The current AzureIoTADUUpdateRequest_t. This can be `NULL` if there isn't currently an update request.
[in]	xAgentState	The current AzureIoTADUAgentState_t.
[in]	pxUpdateResults	The current AzureIoTADUClientInstallResult_t. This can be `NULL` if there aren't any results from an update.
[out]	pucBuffer	The buffer into which the generated payload will be placed.
[in]	ulBufferSize	The length of `pucBuffer`.
[in]	pulRequestId	An optional request id to be used for the publish. This can be `NULL`.

Returns: An AzureIoTResult_t with the result of the operation.

◆ AzureIoTADUClient_SendResponse()

AzureIoTResult_t AzureIoTADUClient_SendResponse	(	AzureIoTADUClient_t *	pxAzureIoTADUClient,
		AzureIoTHubClient_t *	pxAzureIoTHubClient,
		AzureIoTADURequestDecision_t	xRequestDecision,
		uint32_t	ulPropertyVersion,
		uint8_t *	pucWritablePropertyResponseBuffer,
		uint32_t	ulWritablePropertyResponseBufferSize,
		uint32_t *	pulRequestId
	)

Updates the ADU Agent Client with ADU service device update properties.

Remarks: It must be called whenever writable properties are received containing ADU service properties (verified with AzureIoTADUClient_IsADUComponent). It effectively parses the properties (aka, the device update request) from ADU and sets the state machine to perform the update process if the the update request is applicable (e.g., if the version is not already installed). This function also provides the payload to acknowledge the ADU service Azure Plug-and-Play writable properties.

Parameters

[in]	pxAzureIoTADUClient	The AzureIoTADUClient_t * to use for this call.
[in]	pxAzureIoTHubClient	The AzureIoTHubClient_t * to use for this call.
[in]	xRequestDecision	The AzureIoTADURequestDecision_t for this response.
[in]	ulPropertyVersion	Version of the writable properties.
[out]	pucWritablePropertyResponseBuffer	A pointer to the memory buffer where to write the resulting Azure Plug-and-Play properties acknowledgement payload.
[in]	ulWritablePropertyResponseBufferSize	Size of `pucWritablePropertyResponseBuffer`.
[in]	pulRequestId	Pointer to request id to use for the operation.

Returns: An AzureIoTResult_t with the result of the operation.

Variable Documentation

◆ AzureIoTADUModelID

const uint8_t* AzureIoTADUModelID

extern

The DTMI specifying the capabilities for the Azure Device Update client.

This may be used in the AzureIoTHubClientOptions_t as the pucModelID.

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ AzureIoTADUAgentState_t

◆ AzureIoTADUClientDeviceProperties_t

◆ AzureIoTADUClientWorkflow_t

◆ AzureIoTADUDeviceCustomProperties_t

◆ AzureIoTADUUpdateId_t

Enumeration Type Documentation

◆ AzureIoTADUAgentState

Function Documentation

◆ AzureIoTADUClient_DevicePropertiesInit()

◆ AzureIoTADUClient_Init()

◆ AzureIoTADUClient_IsADUComponent()

◆ AzureIoTADUClient_OptionsInit()

◆ AzureIoTADUClient_ParseRequest()

◆ AzureIoTADUClient_SendAgentState()

◆ AzureIoTADUClient_SendResponse()

Variable Documentation

◆ AzureIoTADUModelID