Azure IoT C SDK
Data Structures | Macros | Typedefs | Enumerations | Functions
iothub_client_properties.h File Reference

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"

Go to the source code of this file.

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]payloadTypeWhether the payload is a full set of properties or only a set of updated writable properties.
[in]payloadPayload containing properties from Azure IoT that is to be deserialized.
[in]payloadLengthLength of payload.
[out]propertiesDeserializerHandleReturned 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
propertiesDeserializerHandleIOTHUB_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]propertiesDeserializerHandleDeserialization handle returned by IoTHubClient_Properties_Deserializer_Create().
[out]propertyIOTHUB_CLIENT_PROPERTY_PARSED containing a deserialized representation of the properties.
[out]propertySpecifiedReturned 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]propertiesDeserializerHandleDeserialization handle returned by IoTHubClient_Properties_Deserializer_Create().
[out]propertiesVersionVersion 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
propertyIOTHUB_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]propertiesPointer to IOTHUB_CLIENT_PROPERTY_REPORTED to be serialized.
[in]numPropertiesNumber of elements contained in properties.
[in]componentNameOptional component name these properties are part of. May be NULL for default component.
[out]serializedPropertiesSerialized 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]serializedPropertiesLengthLength 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]propertiesPointer to IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE to be serialized.
[in]numPropertiesNumber of elements contained in properties.
[in]componentNameOptional component name these properties are part of. May be NULL for default component.
[out]serializedPropertiesSerialized 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]serializedPropertiesLengthLength 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]serializedPropertiesProperties to free.