APIs that serialize and deserialize properties modeled with DTDLv2. More...

#include "umock_c/umock_c_prod.h"
#include <stddef.h>
#include "iothub_client_core_common.h"

Data Structures
struct	IOTHUB_CLIENT_PROPERTY_REPORTED
	This struct defines properties reported from the client. This corresponds to what DTDLv2 calls a "read-only property." This structure is filled out by the application and can be serialized into a payload for IoT Hub via `IoTHubClient_Properties_Serializer_CreateReported()`. More...

struct	IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE
	This struct represents the response to a writable property that the client will return. This structure is filled out by the application and can be serialized into a payload for IoT Hub via `IoTHubClient_Properties_Serializer_CreateWritableResponse()`. More...

struct	IOTHUB_CLIENT_PROPERTY_PARSED
	This struct represents a property from IoT Hub. It is generated by IoTHubClient_Deserialize_Properties() while deserializing a property payload. More...

Macros
#define	IOTHUB_CLIENT_PROPERTY_REPORTED_STRUCT_VERSION_1 1
	Current version of `IOTHUB_CLIENT_PROPERTY_REPORTED` structure.

#define	IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE_STRUCT_VERSION_1 1
	Current version of `IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE` structure.

#define	IOTHUB_CLIENT_PROPERTY_PARSED_STRUCT_VERSION_1 1
	Current version of `IOTHUB_CLIENT_PROPERTY_PARSED` structure.

Typedefs
typedef struct IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_TAG *	IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE
	Handle used during deserialization of IoT Plug and Play properties.

Enumerations
enum	IOTHUB_CLIENT_PROPERTY_TYPE { IOTHUB_CLIENT_PROPERTY_TYPE_REPORTED_FROM_CLIENT , IOTHUB_CLIENT_PROPERTY_TYPE_WRITABLE , IOTHUB_CLIENT_PROPERTY_VALUE_STRING }
	Enumeration that indicates whether a given property from the service was originally reported from the client (and hence the client application sees what the last reported value IoT Hub has) or whether this is a writable property that the service is requesting configuration for.

enum	IOTHUB_CLIENT_PROPERTY_TYPE { IOTHUB_CLIENT_PROPERTY_TYPE_REPORTED_FROM_CLIENT , IOTHUB_CLIENT_PROPERTY_TYPE_WRITABLE , IOTHUB_CLIENT_PROPERTY_VALUE_STRING }

Functions
IOTHUB_CLIENT_RESULT	IoTHubClient_Properties_Serializer_CreateReported (const IOTHUB_CLIENT_PROPERTY_REPORTED properties, size_t numProperties, const char componentName, unsigned char *serializedProperties, size_t serializedPropertiesLength)
	Serializes reported properties into the required format for sending to IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubClient_Properties_Serializer_CreateWritableResponse (const IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE properties, size_t numProperties, const char componentName, unsigned char *serializedProperties, size_t serializedPropertiesLength)
	Serializes the response to writable properties into bytes for sending to IoT Hub. More...

void	IoTHubClient_Properties_Serializer_Destroy (unsigned char *serializedProperties)
	Frees serialized properties that were initially allocated with IoTHubClient_Properties_Serializer_CreateReported() or IoTHubClient_Properties_Serializer_CreateWritableResponse(). More...

IOTHUB_CLIENT_RESULT	IoTHubClient_Properties_Deserializer_Create (IOTHUB_CLIENT_PROPERTY_PAYLOAD_TYPE payloadType, const unsigned char payload, size_t payloadLength, IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE propertiesDeserializerHandle)
	Setup a deserialization handle to parse through Plug and Play properties received from IoT Hub. More...

IOTHUB_CLIENT_RESULT	IoTHubClient_Properties_Deserializer_GetVersion (IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE propertiesDeserializerHandle, int *propertiesVersion)
	Retrieves the version associated with the properties payload. More...

IOTHUB_CLIENT_RESULT	IoTHubClient_Properties_Deserializer_GetNext (IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE propertiesDeserializerHandle, IOTHUB_CLIENT_PROPERTY_PARSED property, bool propertySpecified)
	Gets the next property during iteration. More...

void	IoTHubClient_Properties_DeserializerProperty_Destroy (IOTHUB_CLIENT_PROPERTY_PARSED *property)
	Frees memory allocated by IoTHubClient_Properties_Deserializer_GetNext(). More...

void	IoTHubClient_Properties_Deserializer_Destroy (IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE propertiesDeserializerHandle)
	Frees memory allocated by IoTHubClient_Properties_Deserializer_Create(). More...

Detailed Description

APIs that serialize and deserialize properties modeled with DTDLv2.

IoT Plug and Play devices are defined using the DTDLv2 modeling language described at https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/dtdlv2.md.

Azure IoT Hub defines a set of conventions for parsing and creating DTDLv2 properties that can be sent between Azure IoT Hub and devices connected to the Hub.

The format is JSON based. It is possible to manually serialize and deserialize this payload following the documented convention. These APIs make this process easier.
When serializing a property to be sent to IoT Hub, your application provides a C structure and the API returns a byte stream to be sent.

When receiving properties from IoT Hub, the deserialization API converts a raw stream into an easier to process C structure with the JSON parsed out.

These APIs do not invoke any network I/O. To actually send and receive data, these APIs will typically be paired with a corresponding IoT Hub device or module client.

Pseudocode to demonstrate the relationship for serializing properties and clients: // Converts C structure into serialized stream.
IOTHUB_CLIENT_PROPERTY_REPORTED reportedProps = { ... }; // Specific to your application IoTHubClient_Properties_Serializer_CreateReported(&reportedProps, &serializedByteStream); // Send the data IoTHubDeviceClient_LL_SendPropertiesAsync(deviceHandle, serializedByteStream);

Pseudocode to demonstrate the relationship for deserializing properties and clients: // Request all device properties from IoT Hub IoTHubDeviceClient_LL_GetPropertiesAsync(deviceHandle, &yourAppCallback); // Time passes as request is processed... // ... // Your application's IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK is eventually invoked.
// Your application then will setup the deserializer handle based on the data from the network. // rawDataFromIoTHub below corresponds to data your IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK // receives.

void yourAppCallback(rawDataFromIoTHub, ...) // your IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK implementation { // Create handle used in deserialization process below IoTHubClient_Properties_Deserializer_Create(rawDataFromIoTHub, &deserializationHandle)

// Enumerate each received property. deserializedProperty will be of type // IOTHUB_CLIENT_PROPERTY_PARSED and is much easier to process than raw JSON. while (IoTHubClient_Properties_Deserializer_GetNext(&deserializationHandle, &deserializedProperty)) { // Application processes deserializedProperty according to modeling rules // ... // Free memory allocated by IoTHubClient_Properties_Deserializer_GetNext IoTHubClient_Properties_DeserializerProperty_Destroy(&deserializedProperty); } // Free memory allocated by IoTHubClient_Properties_Deserializer_Create IoTHubClient_Properties_Deserializer_Destroy(deserializationHandle); }

Function Documentation

◆ IoTHubClient_Properties_Deserializer_Create()

IOTHUB_CLIENT_RESULT IoTHubClient_Properties_Deserializer_Create	(	IOTHUB_CLIENT_PROPERTY_PAYLOAD_TYPE	payloadType,
		const unsigned char *	payload,
		size_t	payloadLength,
		IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE *	propertiesDeserializerHandle
	)

Setup a deserialization handle to parse through Plug and Play properties received from IoT Hub.

Parameters

[in]	payloadType	Whether the payload is a full set of properties or only a set of updated writable properties.
[in]	payload	Payload containing properties from Azure IoT that is to be deserialized.
[in]	payloadLength	Length of `payload`.
[out]	propertiesDeserializerHandle	Returned handle used for subsequent iteration calls.

Remarks: Applications typically will invoke this API in their IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK implementation. Many of the parameters this function takes should come directly from the IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK itself.

Applications must call IoTHubClient_Properties_Deserializer_Destroy() to free propertiesDeserializerHandle on completion.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubClient_Properties_Deserializer_Destroy()

void IoTHubClient_Properties_Deserializer_Destroy ( IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE propertiesDeserializerHandle )

Frees memory allocated by IoTHubClient_Properties_Deserializer_Create().

Parameters

propertiesDeserializerHandle IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE initially allocated by IoTHubClient_Properties_Deserializer_Create() to be freed.

Remarks: After an application calls IoTHubClient_Properties_Deserializer_Destroy(), any previous IOTHUB_CLIENT_PROPERTY_PARSED structures that were retrieved via IoTHubClient_Properties_Deserializer_GetNext() become invalid.

◆ IoTHubClient_Properties_Deserializer_GetNext()

IOTHUB_CLIENT_RESULT IoTHubClient_Properties_Deserializer_GetNext	(	IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE	propertiesDeserializerHandle,
		IOTHUB_CLIENT_PROPERTY_PARSED *	property,
		bool *	propertySpecified
	)

Gets the next property during iteration.

Parameters

[in]	propertiesDeserializerHandle	Deserialization handle returned by `IoTHubClient_Properties_Deserializer_Create()`.
[out]	property	`IOTHUB_CLIENT_PROPERTY_PARSED` containing a deserialized representation of the properties.
[out]	propertySpecified	Returned value indicating whether a property was found or not. If false, this indicates all components have been iterated over.

Remarks: Applications must call IoTHubClient_Properties_DeserializerProperty_Destroy() to free the property returned by this call. The property structure becomes invalid after IoTHubClient_Properties_DeserializerProperty_Destroy() has been called.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubClient_Properties_Deserializer_GetVersion()

IOTHUB_CLIENT_RESULT IoTHubClient_Properties_Deserializer_GetVersion	(	IOTHUB_CLIENT_PROPERTIES_DESERIALIZER_HANDLE	propertiesDeserializerHandle,
		int *	propertiesVersion
	)

Retrieves the version associated with the properties payload.

Parameters

[in]	propertiesDeserializerHandle	Deserialization handle returned by `IoTHubClient_Properties_Deserializer_Create()`.
[out]	propertiesVersion	Version of the writable properties received. This is used when acknowledging a writable property update.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubClient_Properties_DeserializerProperty_Destroy()

void IoTHubClient_Properties_DeserializerProperty_Destroy ( IOTHUB_CLIENT_PROPERTY_PARSED * property )

Frees memory allocated by IoTHubClient_Properties_Deserializer_GetNext().

Parameters

property IOTHUB_CLIENT_PROPERTY_PARSED initially allocated by IoTHubClient_Properties_Deserializer_Create() to be freed.

◆ IoTHubClient_Properties_Serializer_CreateReported()

IOTHUB_CLIENT_RESULT IoTHubClient_Properties_Serializer_CreateReported	(	const IOTHUB_CLIENT_PROPERTY_REPORTED *	properties,
		size_t	numProperties,
		const char *	componentName,
		unsigned char **	serializedProperties,
		size_t *	serializedPropertiesLength
	)

Serializes reported properties into the required format for sending to IoT Hub.

Parameters

[in]	properties	Pointer to IOTHUB_CLIENT_PROPERTY_REPORTED to be serialized.
[in]	numProperties	Number of elements contained in `properties`.
[in]	componentName	Optional component name these properties are part of. May be NULL for default component.
[out]	serializedProperties	Serialized output of `properties` for sending to IoT Hub. The application must release this memory using `IoTHubClient_Properties_Serializer_Destroy()`. Note: This is NOT a null-terminated string.
[out]	serializedPropertiesLength	Length of serializedProperties.

Remarks: Applications can also manually construct the payload based on the convention rules. This API is an easier to use alternative, so the application can use the more convenient IOTHUB_CLIENT_PROPERTY_REPORTED structure instead of raw serialization.

This API does not perform any network I/O. It only translates IOTHUB_CLIENT_PROPERTY_REPORTED into a byte array. Applications should use APIs such as IoTHubDeviceClient_LL_SendPropertiesAsync() to send the serialized data.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubClient_Properties_Serializer_CreateWritableResponse()

IOTHUB_CLIENT_RESULT IoTHubClient_Properties_Serializer_CreateWritableResponse	(	const IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE *	properties,
		size_t	numProperties,
		const char *	componentName,
		unsigned char **	serializedProperties,
		size_t *	serializedPropertiesLength
	)

Serializes the response to writable properties into bytes for sending to IoT Hub.

Parameters

[in]	properties	Pointer to IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE to be serialized.
[in]	numProperties	Number of elements contained in `properties`.
[in]	componentName	Optional component name these properties are part of. May be NULL for default component.
[out]	serializedProperties	Serialized output of `properties` for sending to IoT Hub. The application must release this memory using `IoTHubClient_Properties_Serializer_Destroy()`. Note: This is NOT a null-terminated string.
[out]	serializedPropertiesLength	Length of serializedProperties.

Remarks: Applications typically will invoke this API when processing a property from service (IOTHUB_CLIENT_PROPERTIES_RECEIVED_CALLBACK) to indicate whether properties have been accepted or rejected by the client. For example, if the service requested DesiredTemp=50, then the application could fill out the fields in an IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE structure indicating whether the request can be processed or whether there was a failure.

Applications can also manually construct the payload based on the convention rules. This API is an easier to use alternative, so the application can use the more convenient IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE structure instead of raw serialization.

This API does not perform any network I/O. It only translates IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE into a byte array. Applications should use APIs such as IoTHubDeviceClient_LL_SendPropertiesAsync() to send the serialized data.

Returns: IOTHUB_CLIENT_OK upon success or an error code upon failure.

◆ IoTHubClient_Properties_Serializer_Destroy()

void IoTHubClient_Properties_Serializer_Destroy ( unsigned char * serializedProperties )

Frees serialized properties that were initially allocated with IoTHubClient_Properties_Serializer_CreateReported() or IoTHubClient_Properties_Serializer_CreateWritableResponse().

Parameters

[in] serializedProperties Properties to free.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation

◆ IoTHubClient_Properties_Deserializer_Create()

◆ IoTHubClient_Properties_Deserializer_Destroy()

◆ IoTHubClient_Properties_Deserializer_GetNext()

◆ IoTHubClient_Properties_Deserializer_GetVersion()

◆ IoTHubClient_Properties_DeserializerProperty_Destroy()

◆ IoTHubClient_Properties_Serializer_CreateReported()

◆ IoTHubClient_Properties_Serializer_CreateWritableResponse()

◆ IoTHubClient_Properties_Serializer_Destroy()