az_iot_hub_client_properties.h File Reference

Definition for the IoT Plug and Play properties writer and parsing routines. More...

#include <stdbool.h>
#include <stdint.h>
#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/core/_az_cfg_prefix.h>
#include <azure/core/_az_cfg_suffix.h>

Go to the source code of this file.

Enumerations
enum	az_iot_hub_client_property_type { AZ_IOT_HUB_CLIENT_PROPERTY_REPORTED_FROM_DEVICE, AZ_IOT_HUB_CLIENT_PROPERTY_WRITABLE }
	Property type. More...

Functions
AZ_NODISCARD az_result	az_iot_hub_client_properties_writer_begin_component (az_iot_hub_client const *client, az_json_writer *ref_json_writer, az_span component_name)
	Append the necessary characters to a reported properties JSON payload belonging to a component. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_writer_end_component (az_iot_hub_client const *client, az_json_writer *ref_json_writer)
	Append the necessary characters to end a reported properties JSON payload belonging to a component. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_writer_begin_response_status (az_iot_hub_client const *client, az_json_writer *ref_json_writer, az_span property_name, int32_t status_code, int32_t version, az_span description)
	Begin a property response to a writable property request from the service. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_writer_end_response_status (az_iot_hub_client const *client, az_json_writer *ref_json_writer)
	End a properties response payload with confirmation status. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_get_properties_version (az_iot_hub_client const *client, az_json_reader *ref_json_reader, az_iot_hub_client_properties_message_type message_type, int32_t *out_version)
	Read the IoT Plug and Play property version. More...
AZ_NODISCARD az_result	az_iot_hub_client_properties_get_next_component_property (az_iot_hub_client const *client, az_json_reader *ref_json_reader, az_iot_hub_client_properties_message_type message_type, az_iot_hub_client_property_type property_type, az_span *out_component_name)
	Iteratively read the IoT Plug and Play component properties. More...

Detailed Description

Definition for the IoT Plug and Play properties writer and parsing routines.

Enumeration Type Documentation

az_iot_hub_client_property_type

enum az_iot_hub_client_property_type

Property type.

Enumerator
AZ_IOT_HUB_CLIENT_PROPERTY_REPORTED_FROM_DEVICE	Property was originally reported from the device.
AZ_IOT_HUB_CLIENT_PROPERTY_WRITABLE	Property was received from the service.

Function Documentation

az_iot_hub_client_properties_get_next_component_property()

AZ_NODISCARD az_result az_iot_hub_client_properties_get_next_component_property	(	az_iot_hub_client const *	client,
		az_json_reader *	ref_json_reader,
		az_iot_hub_client_properties_message_type	message_type,
		az_iot_hub_client_property_type	property_type,
		az_span *	out_component_name
	)

Iteratively read the IoT Plug and Play component properties.

Note that between calls, the az_span pointed to by out_component_name shall not be modified, only checked and compared. Internally, the az_span is only changed if the component name changes in the JSON document and is not necessarily set every invocation of the function.

On success, the ref_json_reader will be set on a valid property name. After checking the property name, the reader can be advanced to the property value by calling az_json_reader_next_token(). Note that on the subsequent call to this API, it is expected that the json reader will be placed AFTER the read property name and value. That means that after reading the property value (including single values or complex objects), the user must call az_json_reader_next_token().

Below is a code snippet which you can use as a starting point:

while (az_result_succeeded(az_iot_hub_client_properties_get_next_component_property(
      &hub_client, &jr, message_type, AZ_IOT_HUB_CLIENT_PROPERTY_WRITABLE, &component_name)))
{
  // Check if property is of interest (substitute user_property for your own property name)
  if (az_json_token_is_text_equal(&jr.token, user_property))
  {
    az_json_reader_next_token(&jr);
 
    // Get the property value here
    // Example: az_json_token_get_int32(&jr.token, &user_int);
 
    // Skip to next property value
    az_json_reader_next_token(&jr);
  }
  else
  {
    // The JSON reader must be advanced regardless of whether the property
    // is of interest or not.
    az_json_reader_next_token(&jr);
 
    // Skip children in case the property value is an object
    az_json_reader_skip_children(&jr);
    az_json_reader_next_token(&jr);
  }
}

Warning

If you need to retrieve more than one property_type, you should first complete the scan of all components for the first property type (until the API returns AZ_ERROR_IOT_END_OF_PROPERTIES). Then you must call az_json_reader_init() again after this call and before the next call to az_iot_hub_client_properties_get_next_component_property with the different property_type.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in,out]	ref_json_reader	The az_json_reader to parse through. The ownership of iterating through this json reader is shared between the user and this API.
[in]	message_type	The az_iot_hub_client_properties_message_type representing the message type associated with the payload.
[in]	property_type	The az_iot_hub_client_property_type to scan for.
[out]	out_component_name	The az_span* representing the value of the component.

Precondition

client must not be NULL.

ref_json_reader must not be NULL.

out_component_name must not be NULL. It must point to an az_span instance.

message_type must be AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_WRITABLE_UPDATED or AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_GET_RESPONSE.

property_type must be AZ_IOT_HUB_CLIENT_PROPERTY_REPORTED_FROM_DEVICE or AZ_IOT_HUB_CLIENT_PROPERTY_WRITABLE.

If AZ_IOT_HUB_CLIENT_PROPERTY_REPORTED_FROM_DEVICE is specified in property_type, then message_type must be AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_GET_RESPONSE.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	If the function returned a valid az_json_reader pointing to the property name and the az_span with a component name.
AZ_ERROR_JSON_INVALID_STATE	If the json reader is passed in at an unexpected location.
AZ_ERROR_IOT_END_OF_PROPERTIES	If there are no more properties left for the component.

az_iot_hub_client_properties_get_properties_version()

AZ_NODISCARD az_result az_iot_hub_client_properties_get_properties_version	(	az_iot_hub_client const *	client,
		az_json_reader *	ref_json_reader,
		az_iot_hub_client_properties_message_type	message_type,
		int32_t *	out_version
	)

Read the IoT Plug and Play property version.

Warning

This modifies the state of the json reader. To then use the same json reader with az_iot_hub_client_properties_get_next_component_property(), you must call az_json_reader_init() again after this call and before the call to az_iot_hub_client_properties_get_next_component_property() or make an additional copy before calling this API.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in,out]	ref_json_reader	The pointer to the az_json_reader used to parse through the JSON payload.
[in]	message_type	The az_iot_hub_client_properties_message_type representing the message type associated with the payload.
[out]	out_version	The numeric version of the properties in the JSON payload.

Precondition

client must not be NULL.

ref_json_reader must not be NULL.

message_type must be AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_WRITABLE_UPDATED or AZ_IOT_HUB_CLIENT_PROPERTIES_MESSAGE_TYPE_GET_RESPONSE.

out_version must not be NULL.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

If the function returned a valid version.

az_iot_hub_client_properties_writer_begin_component()

AZ_NODISCARD az_result az_iot_hub_client_properties_writer_begin_component	(	az_iot_hub_client const *	client,
		az_json_writer *	ref_json_writer,
		az_span	component_name
	)

Append the necessary characters to a reported properties JSON payload belonging to a component.

The payload will be of the form:

"<component_name>": {
    "__t": "c",
    "temperature": 23
}

Note

This API only writes the metadata for a component's properties. The application itself must specify the payload contents between calls to this API and az_iot_hub_client_properties_writer_end_component() using ref_json_writer to specify the JSON payload.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in,out]	ref_json_writer	The az_json_writer to append the necessary characters for an IoT Plug and Play component.
[in]	component_name	The component name associated with the reported properties.

Precondition

client must not be NULL.

ref_json_writer must not be NULL.

component_name must be a valid, non-empty az_span.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The JSON payload was prefixed successfully.

az_iot_hub_client_properties_writer_begin_response_status()

AZ_NODISCARD az_result az_iot_hub_client_properties_writer_begin_response_status	(	az_iot_hub_client const *	client,
		az_json_writer *	ref_json_writer,
		az_span	property_name,
		int32_t	status_code,
		int32_t	version,
		az_span	description
	)

Begin a property response to a writable property request from the service.

This API should be used in response to an incoming writable properties. More details can be found here:

https://docs.microsoft.com/azure/iot-pnp/concepts-convention#writable-properties

The payload will be of the form:

Without component

{
  "<property_name>":{
    "ac": <status_code>,
    "av": <version>,
    "ad": "<description>",
    "value": <user_value>
  }
}

With component

{
  "<component_name>": {
    "__t": "c",
    "<property_name>": {
      "ac": <status_code>,
      "av": <version>,
      "ad": "<description>",
      "value": <user_value>
    }
  }
}

To send a status for properties belonging to a component, first call the az_iot_hub_client_properties_writer_begin_component() API to prefix the payload with the necessary identification. The API call flow would look like the following with the listed JSON payload being generated.

az_iot_hub_client_properties_writer_begin_component()
az_iot_hub_client_properties_writer_begin_response_status()
// Append user value here (<user_value>) using ref_json_writer directly.
az_iot_hub_client_properties_writer_end_response_status()
az_iot_hub_client_properties_writer_end_component()

Note

This API only writes the metadata for the properties response. The application itself must specify the payload contents between calls to this API and az_iot_hub_client_properties_writer_end_response_status() using ref_json_writer to specify the JSON payload.

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in,out]	ref_json_writer	The initialized az_json_writer to append data to.
[in]	property_name	The name of the property to write a response payload for.
[in]	status_code	The HTTP-like status code to respond with. See az_iot_status for possible supported values.
[in]	version	The version of the property the application is acknowledging. This can be retrieved from the service request by calling az_iot_hub_client_properties_get_properties_version.
[in]	description	An optional description detailing the context or any details about the acknowledgement. This can be AZ_SPAN_EMPTY.

Precondition

client must not be NULL.

ref_json_writer must not be NULL.

property_name must be a valid, non-empty az_span.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The JSON payload was prefixed successfully.

az_iot_hub_client_properties_writer_end_component()

AZ_NODISCARD az_result az_iot_hub_client_properties_writer_end_component	(	az_iot_hub_client const *	client,
		az_json_writer *	ref_json_writer
	)

Append the necessary characters to end a reported properties JSON payload belonging to a component.

Note

This API should be used in conjunction with az_iot_hub_client_properties_writer_begin_component().

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in,out]	ref_json_writer	The az_json_writer to append the necessary characters for an IoT Plug and Play component.

Precondition

client must not be NULL.

ref_json_writer must not be NULL.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The JSON payload was suffixed successfully.

az_iot_hub_client_properties_writer_end_response_status()

AZ_NODISCARD az_result az_iot_hub_client_properties_writer_end_response_status	(	az_iot_hub_client const *	client,
		az_json_writer *	ref_json_writer
	)

End a properties response payload with confirmation status.

Note

This API should be used in conjunction with az_iot_hub_client_properties_writer_begin_response_status().

Parameters

[in]	client	The az_iot_hub_client to use for this call.
[in,out]	ref_json_writer	The initialized az_json_writer to append data to.

Precondition

client must not be NULL.

ref_json_writer must not be NULL.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK

The JSON payload was suffixed successfully.