The JSON writer used by the middleware for PnP properties. More...

#include <stdbool.h>
#include <stdint.h>
#include "azure_iot_result.h"
#include "azure/core/az_json.h"
#include "azure/core/_az_cfg_prefix.h"
#include "azure/core/_az_cfg_suffix.h"

Data Structures
struct	AzureIoTJSONWriter
	The struct to use for Azure IoT JSON writer functionality. More...

Typedefs
typedef struct AzureIoTJSONWriter	AzureIoTJSONWriter_t
	The struct to use for Azure IoT JSON writer functionality.

Functions
AzureIoTResult_t	AzureIoTJSONWriter_Init (AzureIoTJSONWriter_t pxWriter, uint8_t pucBuffer, uint32_t ulBufferSize)
	Initializes an AzureIoTJSONWriter_t which writes JSON text into a buffer passed. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendPropertyWithInt32Value (AzureIoTJSONWriter_t pxWriter, const uint8_t pucPropertyName, uint32_t ulPropertyNameLength, int32_t lValue)
	Appends the UTF-8 property name and value where value is int32. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendPropertyWithDoubleValue (AzureIoTJSONWriter_t pxWriter, const uint8_t pucPropertyName, uint32_t ulPropertyNameLength, double xValue, uint16_t usFractionalDigits)
	Appends the UTF-8 property name and value where value is double. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendPropertyWithBoolValue (AzureIoTJSONWriter_t pxWriter, const uint8_t pucPropertyName, uint32_t ulPropertyNameLength, bool usValue)
	Appends the UTF-8 property name and value where value is boolean. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendPropertyWithStringValue (AzureIoTJSONWriter_t pxWriter, const uint8_t pucPropertyName, uint32_t ulPropertyNameLength, const uint8_t *pucValue, uint32_t ulValueLen)
	Appends the UTF-8 property name and value where value is string. More...

int32_t	AzureIoTJSONWriter_GetBytesUsed (AzureIoTJSONWriter_t *pxWriter)
	Returns the length containing the JSON text written to the underlying buffer. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendString (AzureIoTJSONWriter_t pxWriter, const uint8_t pucValue, uint32_t ulValueLen)
	Appends the UTF-8 text value (as a JSON string) into the buffer. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendJSONText (AzureIoTJSONWriter_t pxWriter, const uint8_t pucJSON, uint32_t ulJSONLen)
	Appends an existing UTF-8 encoded JSON text into the buffer, useful for appending nested JSON. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendPropertyName (AzureIoTJSONWriter_t pxWriter, const uint8_t pusValue, uint32_t ulValueLen)
	Appends the UTF-8 property name (as a JSON string) which is the first part of a name/value pair of a JSON object. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendBool (AzureIoTJSONWriter_t *pxWriter, bool xValue)
	Appends a boolean value (as a JSON literal `true` or `false`). More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendInt32 (AzureIoTJSONWriter_t *pxWriter, int32_t lValue)
	Appends an `int32_t` number value. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendDouble (AzureIoTJSONWriter_t *pxWriter, double xValue, uint16_t usFractionalDigits)
	Appends a `double` number value. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendNull (AzureIoTJSONWriter_t *pxWriter)
	Appends the JSON literal `null`. More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendBeginObject (AzureIoTJSONWriter_t *pxWriter)
	Appends the beginning of a JSON object (i.e. `{`). More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendBeginArray (AzureIoTJSONWriter_t *pxWriter)
	Appends the beginning of a JSON array (i.e. `[`). More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendEndObject (AzureIoTJSONWriter_t *pxWriter)
	Appends the end of the current JSON object (i.e. `}`). More...

AzureIoTResult_t	AzureIoTJSONWriter_AppendEndArray (AzureIoTJSONWriter_t *pxWriter)
	Appends the end of the current JSON array (i.e. `]`). More...

Detailed Description

The JSON writer used by the middleware for PnP properties.

Note: 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.

Function Documentation

◆ AzureIoTJSONWriter_AppendBeginArray()

AzureIoTResult_t AzureIoTJSONWriter_AppendBeginArray ( AzureIoTJSONWriter_t * pxWriter )

Appends the beginning of a JSON array (i.e. [).

Parameters

[in] pxWriter A pointer to an AzureIoTJSONWriter_t.

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

Return values

eAzureIoTSuccess Array start was appended successfully.

◆ AzureIoTJSONWriter_AppendBeginObject()

AzureIoTResult_t AzureIoTJSONWriter_AppendBeginObject ( AzureIoTJSONWriter_t * pxWriter )

Appends the beginning of a JSON object (i.e. {).

Parameters

[in] pxWriter A pointer to an AzureIoTJSONWriter_t.

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

Return values

eAzureIoTSuccess Object start was appended successfully.

◆ AzureIoTJSONWriter_AppendBool()

AzureIoTResult_t AzureIoTJSONWriter_AppendBool	(	AzureIoTJSONWriter_t *	pxWriter,
		bool	xValue
	)

Appends a boolean value (as a JSON literal true or false).

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	xValue	The value to be written as a JSON literal `true` or `false`.

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

Return values

eAzureIoTSuccess The bool was appended successfully.

◆ AzureIoTJSONWriter_AppendDouble()

AzureIoTResult_t AzureIoTJSONWriter_AppendDouble	(	AzureIoTJSONWriter_t *	pxWriter,
		double	xValue,
		uint16_t	usFractionalDigits
	)

Appends a double number value.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	xValue	The value to be written as a JSON number.
[in]	usFractionalDigits	The number of digits of the `value` to write after the decimal point and truncate the rest.

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

Return values

eAzureIoTSuccess The number was appended successfully.

Remarks: Only finite double values are supported. Values such as NAN and INFINITY are not allowed and would lead to invalid JSON being written.; Non-significant trailing zeros (after the decimal point) are not written, even if usFractionalDigits is large enough to allow the zero padding.; The usFractionalDigits must be between 0 and 15 (inclusive). Any value passed in that is larger will be clamped down to 15.

◆ AzureIoTJSONWriter_AppendEndArray()

AzureIoTResult_t AzureIoTJSONWriter_AppendEndArray ( AzureIoTJSONWriter_t * pxWriter )

Appends the end of the current JSON array (i.e. ]).

Parameters

[in] pxWriter A pointer to an AzureIoTJSONWriter_t.

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

Return values

eAzureIoTSuccess Array end was appended successfully.

◆ AzureIoTJSONWriter_AppendEndObject()

AzureIoTResult_t AzureIoTJSONWriter_AppendEndObject ( AzureIoTJSONWriter_t * pxWriter )

Appends the end of the current JSON object (i.e. }).

Parameters

[in] pxWriter A pointer to an AzureIoTJSONWriter_t.

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

Return values

eAzureIoTSuccess Object end was appended successfully.

◆ AzureIoTJSONWriter_AppendInt32()

AzureIoTResult_t AzureIoTJSONWriter_AppendInt32	(	AzureIoTJSONWriter_t *	pxWriter,
		int32_t	lValue
	)

Appends an int32_t number value.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	lValue	The value to be written as a JSON number.

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

Return values

eAzureIoTSuccess The number was appended successfully.

◆ AzureIoTJSONWriter_AppendJSONText()

AzureIoTResult_t AzureIoTJSONWriter_AppendJSONText	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pucJSON,
		uint32_t	ulJSONLen
	)

Appends an existing UTF-8 encoded JSON text into the buffer, useful for appending nested JSON.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pucJSON	A pointer to single, possibly nested, valid, UTF-8 encoded, JSON value to be written as is, without any formatting or spacing changes. No modifications are made to this text, including escaping.
[in]	ulJSONLen	Length of `pucJSON`.

Remarks: A single, possibly nested, JSON value is one that starts and ends with {} or [] or is a single primitive token. The JSON cannot start with an end object or array, or a property name, or be incomplete.; The function validates that the provided JSON to be appended is valid and properly escaped, and fails otherwise.

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

Return values

eAzureIoTSuccess The provided json_text was appended successfully.

◆ AzureIoTJSONWriter_AppendNull()

AzureIoTResult_t AzureIoTJSONWriter_AppendNull ( AzureIoTJSONWriter_t * pxWriter )

Appends the JSON literal null.

Parameters

[in] pxWriter A pointer to an AzureIoTJSONWriter_t.

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

Return values

eAzureIoTSuccess null was appended successfully.

◆ AzureIoTJSONWriter_AppendPropertyName()

AzureIoTResult_t AzureIoTJSONWriter_AppendPropertyName	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pusValue,
		uint32_t	ulValueLen
	)

Appends the UTF-8 property name (as a JSON string) which is the first part of a name/value pair of a JSON object.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pusValue	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.
[in]	ulValueLen	Length of name.

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

Return values

eAzureIoTSuccess The property name was appended successfully.

◆ AzureIoTJSONWriter_AppendPropertyWithBoolValue()

AzureIoTResult_t AzureIoTJSONWriter_AppendPropertyWithBoolValue	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pucPropertyName,
		uint32_t	ulPropertyNameLength,
		bool	usValue
	)

Appends the UTF-8 property name and value where value is boolean.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pucPropertyName	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.
[in]	ulPropertyNameLength	Length of pucPropertyName.
[in]	usValue	The value to be written as a JSON literal `true` or `false`.

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

Return values

eAzureIoTSuccess The property name and bool value was appended successfully.

◆ AzureIoTJSONWriter_AppendPropertyWithDoubleValue()

AzureIoTResult_t AzureIoTJSONWriter_AppendPropertyWithDoubleValue	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pucPropertyName,
		uint32_t	ulPropertyNameLength,
		double	xValue,
		uint16_t	usFractionalDigits
	)

Appends the UTF-8 property name and value where value is double.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pucPropertyName	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.
[in]	ulPropertyNameLength	Length of pucPropertyName.
[in]	xValue	The value to be written as a JSON number.
[in]	usFractionalDigits	The number of digits of the value to write after the decimal point and truncate the rest.

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

Return values

eAzureIoTSuccess The property name and double value was appended successfully.

◆ AzureIoTJSONWriter_AppendPropertyWithInt32Value()

AzureIoTResult_t AzureIoTJSONWriter_AppendPropertyWithInt32Value	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pucPropertyName,
		uint32_t	ulPropertyNameLength,
		int32_t	lValue
	)

Appends the UTF-8 property name and value where value is int32.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pucPropertyName	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.
[in]	ulPropertyNameLength	Length of pucPropertyName.
[in]	lValue	The value to be written as a JSON number.

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

Return values

eAzureIoTSuccess The property name and int32 value was appended successfully.

◆ AzureIoTJSONWriter_AppendPropertyWithStringValue()

AzureIoTResult_t AzureIoTJSONWriter_AppendPropertyWithStringValue	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pucPropertyName,
		uint32_t	ulPropertyNameLength,
		const uint8_t *	pucValue,
		uint32_t	ulValueLen
	)

Appends the UTF-8 property name and value where value is string.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pucPropertyName	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.
[in]	ulPropertyNameLength	Length of pucPropertyName.
[in]	pucValue	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.
[in]	ulValueLen	Length of value.

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

Return values

eAzureIoTSuccess The property name and string value was appended successfully.

◆ AzureIoTJSONWriter_AppendString()

AzureIoTResult_t AzureIoTJSONWriter_AppendString	(	AzureIoTJSONWriter_t *	pxWriter,
		const uint8_t *	pucValue,
		uint32_t	ulValueLen
	)

Appends the UTF-8 text value (as a JSON string) into the buffer.

Parameters

[in]	pxWriter	A pointer to an AzureIoTJSONWriter_t.
[in]	pucValue	Pointer of UCHAR buffer that contains UTF-8 encoded value to be written as a JSON string. The value is escaped before writing.
[in]	ulValueLen	Length of value.

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

Return values

eAzureIoTSuccess The string value was appended successfully.

◆ AzureIoTJSONWriter_GetBytesUsed()

int32_t AzureIoTJSONWriter_GetBytesUsed ( AzureIoTJSONWriter_t * pxWriter )

Returns the length containing the JSON text written to the underlying buffer.

Parameters

[in] pxWriter A pointer to an AzureIoTJSONWriter_t.

Returns: An int32_t containing the length of JSON text built so far. Will return -1 if there was an error.

◆ AzureIoTJSONWriter_Init()

AzureIoTResult_t AzureIoTJSONWriter_Init	(	AzureIoTJSONWriter_t *	pxWriter,
		uint8_t *	pucBuffer,
		uint32_t	ulBufferSize
	)

Initializes an AzureIoTJSONWriter_t which writes JSON text into a buffer passed.

Parameters

[out]	pxWriter	A pointer to an AzureIoTJSONWriter_t the instance to initialize.
[in]	pucBuffer	A buffer pointer to which JSON text will be written.
[in]	ulBufferSize	Length of buffer.

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

Return values

eAzureIoTSuccess Successfully initialized JSON writer.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation

◆ AzureIoTJSONWriter_AppendBeginArray()

◆ AzureIoTJSONWriter_AppendBeginObject()

◆ AzureIoTJSONWriter_AppendBool()

◆ AzureIoTJSONWriter_AppendDouble()

◆ AzureIoTJSONWriter_AppendEndArray()

◆ AzureIoTJSONWriter_AppendEndObject()

◆ AzureIoTJSONWriter_AppendInt32()

◆ AzureIoTJSONWriter_AppendJSONText()

◆ AzureIoTJSONWriter_AppendNull()

◆ AzureIoTJSONWriter_AppendPropertyName()

◆ AzureIoTJSONWriter_AppendPropertyWithBoolValue()

◆ AzureIoTJSONWriter_AppendPropertyWithDoubleValue()

◆ AzureIoTJSONWriter_AppendPropertyWithInt32Value()

◆ AzureIoTJSONWriter_AppendPropertyWithStringValue()

◆ AzureIoTJSONWriter_AppendString()

◆ AzureIoTJSONWriter_GetBytesUsed()

◆ AzureIoTJSONWriter_Init()