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

#include <azure/core/az_json.h>
#include <azure/core/az_result.h>
#include <azure/core/az_span.h>
#include <azure/iot/az_iot_hub_client.h>
#include <azure/iot/internal/az_iot_adu_internal.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_adu_update_id
	Identity of the update request. More...

struct	az_iot_adu_device_custom_properties
	Holds any user-defined custom properties for the device. More...

struct	az_iot_adu_client_device_properties
	Holds the ADU agent device properties. More...

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

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

struct	az_iot_adu_client_workflow
	A set of values that indicate which deployment the agent is currently working on. More...

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

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

struct	az_iot_adu_client_update_manifest_instructions_step_handler_properties
	User-defined properties for handling an update request. More...

struct	az_iot_adu_client_update_manifest_instructions_step
	Step in the instructions of an update manifest. More...

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

struct	az_iot_adu_client_update_manifest_file_hash
	Hash value for a given file. More...

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

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

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

struct	az_iot_adu_client
	Structure that holds the state of the Azure IoT ADU client. More...

Macros
#define	AZ_IOT_ADU_CLIENT_AGENT_MODEL_ID "dtmi:azure:iot:deviceUpdateContractModel;2"
	Define the ADU agent model ID. More...

#define	AZ_IOT_ADU_CLIENT_AGENT_VERSION "DU;agent/1.0.0"
	ADU Agent Version.

#define	AZ_IOT_ADU_CLIENT_PROPERTIES_COMPONENT_NAME "deviceUpdate"
	ADU PnP Component Name.

#define	AZ_IOT_ADU_CLIENT_AGENT_DEFAULT_COMPATIBILITY_PROPERTIES "manufacturer,model"
	Default Agent Compatibility Properties.

Enumerations
enum	az_iot_adu_client_request_decision { AZ_IOT_ADU_CLIENT_REQUEST_DECISION_ACCEPT = 200, AZ_IOT_ADU_CLIENT_REQUEST_DECISION_REJECT = 406 }
	Decision codes to accept or reject a received update deployment. More...

enum	az_iot_adu_client_agent_state { AZ_IOT_ADU_CLIENT_AGENT_STATE_IDLE = 0, AZ_IOT_ADU_CLIENT_AGENT_STATE_DEPLOYMENT_IN_PROGRESS = 6, AZ_IOT_ADU_CLIENT_AGENT_STATE_FAILED = 255 }
	Agent states used to notify the ADU service of current state. More...

enum	az_iot_adu_client_service_action { AZ_IOT_ADU_CLIENT_SERVICE_ACTION_APPLY_DEPLOYMENT = 3, AZ_IOT_ADU_CLIENT_SERVICE_ACTION_CANCEL = 255 }
	Actions specified by the service for the agent to process. More...

Functions
AZ_NODISCARD az_iot_adu_client_options	az_iot_adu_client_options_default ()
	Gets the default Azure IoT ADU Client options. More...

AZ_NODISCARD az_iot_adu_client_device_properties	az_iot_adu_client_device_properties_default ()
	Gets the default az_iot_adu_client_device_properties. More...

AZ_NODISCARD az_result	az_iot_adu_client_init (az_iot_adu_client client, az_iot_adu_client_options options)
	Initializes an Azure IoT ADU Client. More...

AZ_NODISCARD bool	az_iot_adu_client_is_component_device_update (az_iot_adu_client *client, az_span component_name)
	Verifies if the Azure Plug-and-Play writable properties component is for ADU device update. More...

AZ_NODISCARD az_result	az_iot_adu_client_get_agent_state_payload (az_iot_adu_client client, az_iot_adu_client_device_properties device_properties, az_iot_adu_client_agent_state agent_state, az_iot_adu_client_workflow workflow, az_iot_adu_client_install_result last_install_result, az_json_writer *ref_json_writer)
	Generates the Azure Plug-and-Play (reported) properties payload with the state of the ADU agent. More...

AZ_NODISCARD az_result	az_iot_adu_client_parse_service_properties (az_iot_adu_client client, az_json_reader ref_json_reader, az_iot_adu_client_update_request *update_request)
	Parses the json content from the ADU service writable properties into a pre-defined structure. More...

AZ_NODISCARD az_result	az_iot_adu_client_get_service_properties_response (az_iot_adu_client client, int32_t version, az_iot_adu_client_request_decision status, az_json_writer ref_json_writer)
	Generates the payload necessary to respond to the service after receiving incoming properties. More...

AZ_NODISCARD az_result	az_iot_adu_client_parse_update_manifest (az_iot_adu_client client, az_json_reader ref_json_reader, az_iot_adu_client_update_manifest *update_manifest)
	Parses the json content from the ADU service update manifest into a pre-defined structure. More...

Detailed Description

Definition for the Azure IoT ADU Client.

Note: More details about Azure Device Update can be found online at https://docs.microsoft.com/azure/iot-hub-device-update/understand-device-update; 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_ADU_CLIENT_AGENT_MODEL_ID

#define AZ_IOT_ADU_CLIENT_AGENT_MODEL_ID "dtmi:azure:iot:deviceUpdateContractModel;2"

Define the ADU agent model ID.

https://github.com/Azure/iot-plugandplay-models/blob/main/dtmi/azure/iot/deviceupdatecontractmodel-2.json

Enumeration Type Documentation

◆ az_iot_adu_client_agent_state

enum az_iot_adu_client_agent_state

Agent states used to notify the ADU service of current state.

Enumerator
AZ_IOT_ADU_CLIENT_AGENT_STATE_IDLE	ADU Agent State (Idle)
AZ_IOT_ADU_CLIENT_AGENT_STATE_DEPLOYMENT_IN_PROGRESS	ADU Agent State (In Progress)
AZ_IOT_ADU_CLIENT_AGENT_STATE_FAILED	ADU Agent State (Failed)

◆ az_iot_adu_client_request_decision

enum az_iot_adu_client_request_decision

Decision codes to accept or reject a received update deployment.

Enumerator
AZ_IOT_ADU_CLIENT_REQUEST_DECISION_ACCEPT	ADU Service Response (Accept)
AZ_IOT_ADU_CLIENT_REQUEST_DECISION_REJECT	ADU Service Response (Reject)

◆ az_iot_adu_client_service_action

enum az_iot_adu_client_service_action

Actions specified by the service for the agent to process.

Enumerator
AZ_IOT_ADU_CLIENT_SERVICE_ACTION_APPLY_DEPLOYMENT	ADU Service Action (Apply)
AZ_IOT_ADU_CLIENT_SERVICE_ACTION_CANCEL	ADU Service Action (Cancel)

Function Documentation

◆ az_iot_adu_client_device_properties_default()

AZ_NODISCARD az_iot_adu_client_device_properties az_iot_adu_client_device_properties_default ( )

Gets the default az_iot_adu_client_device_properties.

Call this to obtain an initialized az_iot_adu_client_device_properties structure that can be afterwards modified and passed to necessary APIs.

Returns: az_iot_adu_client_device_properties.

◆ az_iot_adu_client_get_agent_state_payload()

AZ_NODISCARD az_result az_iot_adu_client_get_agent_state_payload	(	az_iot_adu_client *	client,
		az_iot_adu_client_device_properties *	device_properties,
		az_iot_adu_client_agent_state	agent_state,
		az_iot_adu_client_workflow *	workflow,
		az_iot_adu_client_install_result *	last_install_result,
		az_json_writer *	ref_json_writer
	)

Generates the Azure Plug-and-Play (reported) properties payload with the state of the ADU agent.

Parameters

[in]	client	The az_iot_adu_client to use for this call.
[in]	device_properties	A pointer to a az_iot_adu_client_device_properties structure with all the details of the device, as required by the ADU service.
[in]	agent_state	An integer value indicating the current state of the ADU agent. Use the values defined by the az_iot_adu_client_agent_state. Please see the ADU online documentation for more details.
[in]	workflow	A pointer to a az_iot_adu_client_workflow instance indicating the current ADU workflow being processed, if an ADU service workflow was received. Use NULL if no device update is in progress.
[in]	last_install_result	A pointer to a az_iot_adu_client_install_result instance with the results of the current or past device update workflow, if available. Use NULL if no results are available.
[in,out]	ref_json_writer	An az_json_writer initialized with the memory where to write the property payload.

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

◆ az_iot_adu_client_get_service_properties_response()

AZ_NODISCARD az_result az_iot_adu_client_get_service_properties_response	(	az_iot_adu_client *	client,
		int32_t	version,
		az_iot_adu_client_request_decision	status,
		az_json_writer *	ref_json_writer
	)

Generates the payload necessary to respond to the service after receiving incoming properties.

Parameters

[in]	client	The az_iot_adu_client to use for this call.
[in]	version	Version of the writable properties.
[in]	status	Azure Plug-and-Play status code for the writable properties acknowledgement.
[in]	ref_json_writer	An az_json_writer pointing to the memory buffer where to write the resulting Azure Plug-and-Play properties.

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

◆ az_iot_adu_client_init()

AZ_NODISCARD az_result az_iot_adu_client_init	(	az_iot_adu_client *	client,
		az_iot_adu_client_options *	options
	)

Initializes an Azure IoT ADU Client.

Parameters

client	The az_iot_adu_client to use for this call.
options	A reference to an az_iot_adu_client_options structure. If `NULL` is passed, the adu client will use the default options. If using custom options, please initialize first by calling az_iot_adu_client_options_default() and then populating relevant options with your own values.

Precondition: client must not be NULL.

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

◆ az_iot_adu_client_is_component_device_update()

AZ_NODISCARD bool az_iot_adu_client_is_component_device_update	(	az_iot_adu_client *	client,
		az_span	component_name
	)

Verifies if the Azure Plug-and-Play writable properties component is for ADU device update.

Parameters

[in]	client	The az_iot_adu_client to use for this call.
[in]	component_name	az_span pointing to the component name in the writable properties.

Returns: A boolean indicating if the component name is for ADU device update.

◆ az_iot_adu_client_options_default()

AZ_NODISCARD az_iot_adu_client_options az_iot_adu_client_options_default ( )

Gets the default Azure IoT ADU Client options.

Call this to obtain an initialized az_iot_adu_client_options structure that can be afterwards modified and passed to az_iot_adu_client_init.

Returns: az_iot_adu_client_options.

◆ az_iot_adu_client_parse_service_properties()

AZ_NODISCARD az_result az_iot_adu_client_parse_service_properties	(	az_iot_adu_client *	client,
		az_json_reader *	ref_json_reader,
		az_iot_adu_client_update_request *	update_request
	)

Parses the json content from the ADU service writable properties into a pre-defined structure.

Parameters

[in]	client	The az_iot_adu_client to use for this call.
[in]	ref_json_reader	A az_json_reader initialized with the ADU service writable properties json, set to the beginning of the json object that is the value of the ADU component.
[out]	update_request	A pointer to the az_iot_adu_client_update_request structure where to store the parsed contents read from the `ref_json_reader` json reader. In summary, this structure holds az_span instances that point to the actual data parsed from `ref_json_reader` and copied to `buffer`.

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

◆ az_iot_adu_client_parse_update_manifest()

AZ_NODISCARD az_result az_iot_adu_client_parse_update_manifest	(	az_iot_adu_client *	client,
		az_json_reader *	ref_json_reader,
		az_iot_adu_client_update_manifest *	update_manifest
	)

Parses the json content from the ADU service update manifest into a pre-defined structure.

Parameters

[in]	client	The az_iot_adu_client to use for this call.
[in]	ref_json_reader	ADU update manifest, as initialized json reader.
[out]	update_manifest	The structure where the parsed values of the manifest are stored. Values are not copied from `payload`, the fields of the structure just point to the positions in `payload` where the data is present, except for numeric and boolean values (which are parsed into the respective data types).

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

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AZ_IOT_ADU_CLIENT_AGENT_MODEL_ID

Enumeration Type Documentation

◆ az_iot_adu_client_agent_state

◆ az_iot_adu_client_request_decision

◆ az_iot_adu_client_service_action

Function Documentation

◆ az_iot_adu_client_device_properties_default()

◆ az_iot_adu_client_get_agent_state_payload()

◆ az_iot_adu_client_get_service_properties_response()

◆ az_iot_adu_client_init()

◆ az_iot_adu_client_is_component_device_update()

◆ az_iot_adu_client_options_default()

◆ az_iot_adu_client_parse_service_properties()

◆ az_iot_adu_client_parse_update_manifest()