Azure IoT middleware for FreeRTOS
Data Structures | Typedefs | Enumerations | Functions | Variables
azure_iot_adu_client.h File Reference

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

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

◆ 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

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

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

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]pxADUDevicePropertiesThe 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]pxAzureIoTADUClientThe AzureIoTADUClient_t * to use for this call.
[in]pxADUClientOptionsThe 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]pxAzureIoTADUClientThe AzureIoTADUClient_t * to use for this call.
[in]pucComponentNameName of writable properties component to be checked.
[in]ulComponentNameLengthLength 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]pxADUClientOptionsThe 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]pxAzureIoTADUClientThe AzureIoTADUClient_t * to use for this call.
[in,out]pxReaderThe initialized JSON reader positioned at the beginning of the ADU subcomponent property.
[out]pxAduUpdateRequestThe 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]pxAzureIoTADUClientThe AzureIoTADUClient_t * to use for this call.
[in]pxAzureIoTHubClientThe AzureIoTHubClient_t * to use for this call.
[in]pxDevicePropertiesThe device information which will be used to generate the payload.
[in]pxAduUpdateRequestThe current AzureIoTADUUpdateRequest_t. This can be NULL if there isn't currently an update request.
[in]xAgentStateThe current AzureIoTADUAgentState_t.
[in]pxUpdateResultsThe current AzureIoTADUClientInstallResult_t. This can be NULL if there aren't any results from an update.
[out]pucBufferThe buffer into which the generated payload will be placed.
[in]ulBufferSizeThe length of pucBuffer.
[in]pulRequestIdAn 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]pxAzureIoTADUClientThe AzureIoTADUClient_t * to use for this call.
[in]pxAzureIoTHubClientThe AzureIoTHubClient_t * to use for this call.
[in]xRequestDecisionThe AzureIoTADURequestDecision_t for this response.
[in]ulPropertyVersionVersion of the writable properties.
[out]pucWritablePropertyResponseBufferA pointer to the memory buffer where to write the resulting Azure Plug-and-Play properties acknowledgement payload.
[in]ulWritablePropertyResponseBufferSizeSize of pucWritablePropertyResponseBuffer.
[in]pulRequestIdPointer 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.