Data

A data structure for AMQP data. More...

Typedefs
typedef struct pn_data_t	pn_data_t
	An AMQP Data object.

Functions
pn_data_t *	pn_data (size_t capacity)
	Construct a pn_data_t object with the supplied initial capacity.
void	pn_data_free (pn_data_t *data)
	Free a pn_data_t object.
int	pn_data_errno (pn_data_t *data)
	Access the current error code for a given pn_data_t.
pn_error_t *	pn_data_error (pn_data_t *data)
	Access the current error for a given pn_data_t.
void	pn_data_clear (pn_data_t *data)
	Clears a pn_data_t object.
size_t	pn_data_size (pn_data_t *data)
	Returns the total number of nodes contained in a pn_data_t object.
void	pn_data_rewind (pn_data_t *data)
	Clears current node pointer and sets the parent to the root node.
bool	pn_data_next (pn_data_t *data)
	Advances the current node to its next sibling and returns true.
bool	pn_data_prev (pn_data_t *data)
	Moves the current node to its previous sibling and returns true.
bool	pn_data_enter (pn_data_t *data)
	Sets the parent node to the current node and clears the current node.
bool	pn_data_exit (pn_data_t *data)
	Sets the current node to the parent node and the parent node to its own parent.
pn_type_t	pn_data_type (pn_data_t *data)
	Access the type of the current node.
int	pn_data_print (pn_data_t *data)
	Prints the contents of a pn_data_t object using pn_data_format() to stdout.
int	pn_data_format (pn_data_t *data, char *bytes, size_t *size)
	Formats the contents of a pn_data_t object in a human readable way and writes them to the indicated location.
ssize_t	pn_data_encode (pn_data_t *data, char *bytes, size_t size)
	Writes the contents of a data object to the given buffer as an AMQP data stream.
ssize_t	pn_data_encoded_size (pn_data_t *data)
	Returns the number of bytes needed to encode a data object.
ssize_t	pn_data_decode (pn_data_t *data, const char *bytes, size_t size)
	Decodes a single value from the contents of the AMQP data stream into the current data object.
int	pn_data_put_list (pn_data_t *data)
	Puts an empty list value into a pn_data_t.
int	pn_data_put_map (pn_data_t *data)
	Puts an empty map value into a pn_data_t.
int	pn_data_put_array (pn_data_t *data, bool described, pn_type_t type)
	Puts an empty array value into a pn_data_t.
int	pn_data_put_described (pn_data_t *data)
	Puts a described value into a pn_data_t object.
int	pn_data_put_null (pn_data_t *data)
	Puts a PN_NULL value.
int	pn_data_put_bool (pn_data_t *data, bool b)
	Puts a PN_BOOL value.
int	pn_data_put_ubyte (pn_data_t *data, uint8_t ub)
	Puts a PN_UBYTE value.
int	pn_data_put_byte (pn_data_t *data, int8_t b)
	Puts a PN_BYTE value.
int	pn_data_put_ushort (pn_data_t *data, uint16_t us)
	Puts a PN_USHORT value.
int	pn_data_put_short (pn_data_t *data, int16_t s)
	Puts a PN_SHORT value.
int	pn_data_put_uint (pn_data_t *data, uint32_t ui)
	Puts a PN_UINT value.
int	pn_data_put_int (pn_data_t *data, int32_t i)
	Puts a PN_INT value.
int	pn_data_put_char (pn_data_t *data, pn_char_t c)
	Puts a PN_CHAR value.
int	pn_data_put_ulong (pn_data_t *data, uint64_t ul)
	Puts a PN_ULONG value.
int	pn_data_put_long (pn_data_t *data, int64_t l)
	Puts a PN_LONG value.
int	pn_data_put_timestamp (pn_data_t *data, pn_timestamp_t t)
	Puts a PN_TIMESTAMP value.
int	pn_data_put_float (pn_data_t *data, float f)
	Puts a PN_FLOAT value.
int	pn_data_put_double (pn_data_t *data, double d)
	Puts a PN_DOUBLE value.
int	pn_data_put_decimal32 (pn_data_t *data, pn_decimal32_t d)
	Puts a PN_DECIMAL32 value.
int	pn_data_put_decimal64 (pn_data_t *data, pn_decimal64_t d)
	Puts a PN_DECIMAL64 value.
int	pn_data_put_decimal128 (pn_data_t *data, pn_decimal128_t d)
	Puts a PN_DECIMAL128 value.
int	pn_data_put_uuid (pn_data_t *data, pn_uuid_t u)
	Puts a PN_UUID value.
int	pn_data_put_binary (pn_data_t *data, pn_bytes_t bytes)
	Puts a PN_BINARY value.
int	pn_data_put_string (pn_data_t *data, pn_bytes_t string)
	Puts a PN_STRING value.
int	pn_data_put_symbol (pn_data_t *data, pn_bytes_t symbol)
	Puts a PN_SYMBOL value.
int	pn_data_put_atom (pn_data_t *data, pn_atom_t atom)
	Puts any scalar value value.
size_t	pn_data_get_list (pn_data_t *data)
	If the current node is a list, return the number of elements, otherwise return zero.
size_t	pn_data_get_map (pn_data_t *data)
	If the current node is a map, return the number of child elements, otherwise return zero.
size_t	pn_data_get_array (pn_data_t *data)
	If the current node is an array, return the number of elements in the array, otherwise return 0.
bool	pn_data_is_array_described (pn_data_t *data)
	Returns true if the current node points to a described array.
pn_type_t	pn_data_get_array_type (pn_data_t *data)
	Return the array type if the current node points to an array, PN_INVALID otherwise.
bool	pn_data_is_described (pn_data_t *data)
	Checks if the current node is a described value.
bool	pn_data_is_null (pn_data_t *data)
	Checks if the current node is a PN_NULL.
bool	pn_data_get_bool (pn_data_t *data)
	If the current node is a PN_BOOL, returns its value.
uint8_t	pn_data_get_ubyte (pn_data_t *data)
	If the current node is a PN_UBYTE, return its value, otherwise return 0.
int8_t	pn_data_get_byte (pn_data_t *data)
	If the current node is a signed byte, returns its value, returns 0 otherwise.
uint16_t	pn_data_get_ushort (pn_data_t *data)
	If the current node is an unsigned short, returns its value, returns 0 otherwise.
int16_t	pn_data_get_short (pn_data_t *data)
	If the current node is a signed short, returns its value, returns 0 otherwise.
uint32_t	pn_data_get_uint (pn_data_t *data)
	If the current node is an unsigned int, returns its value, returns 0 otherwise.
int32_t	pn_data_get_int (pn_data_t *data)
	If the current node is a signed int, returns its value, returns 0 otherwise.
pn_char_t	pn_data_get_char (pn_data_t *data)
	If the current node is a char, returns its value, returns 0 otherwise.
uint64_t	pn_data_get_ulong (pn_data_t *data)
	If the current node is an unsigned long, returns its value, returns 0 otherwise.
int64_t	pn_data_get_long (pn_data_t *data)
	If the current node is an signed long, returns its value, returns 0 otherwise.
pn_timestamp_t	pn_data_get_timestamp (pn_data_t *data)
	If the current node is a timestamp, returns its value, returns 0 otherwise.
float	pn_data_get_float (pn_data_t *data)
	If the current node is a float, returns its value, returns 0 otherwise.
double	pn_data_get_double (pn_data_t *data)
	If the current node is a double, returns its value, returns 0 otherwise.
pn_decimal32_t	pn_data_get_decimal32 (pn_data_t *data)
	If the current node is a decimal32, returns its value, returns 0 otherwise.
pn_decimal64_t	pn_data_get_decimal64 (pn_data_t *data)
	If the current node is a decimal64, returns its value, returns 0 otherwise.
pn_decimal128_t	pn_data_get_decimal128 (pn_data_t *data)
	If the current node is a decimal128, returns its value, returns 0 otherwise.
pn_uuid_t	pn_data_get_uuid (pn_data_t *data)
	If the current node is a UUID, returns its value, returns None otherwise.
pn_bytes_t	pn_data_get_binary (pn_data_t *data)
	If the current node is binary, returns its value, returns "" otherwise.
pn_bytes_t	pn_data_get_string (pn_data_t *data)
	If the current node is a string, returns its value, returns "" otherwise.
pn_bytes_t	pn_data_get_symbol (pn_data_t *data)
	If the current node is a symbol, returns its value, returns "" otherwise.
pn_bytes_t	pn_data_get_bytes (pn_data_t *data)
	If the current node is a symbol, string, or binary, return the bytes representing its value.
pn_atom_t	pn_data_get_atom (pn_data_t *data)
	If the current node is a scalar value, return it as a pn_atom_t.
int	pn_data_copy (pn_data_t *data, pn_data_t *src)
	Copy the contents of another pn_data_t object.
int	pn_data_append (pn_data_t *data, pn_data_t *src)
	Append the contents of another pn_data_t object.
int	pn_data_appendn (pn_data_t *data, pn_data_t *src, int limit)
	Append up to n values from the contents of another pn_data_t object.
void	pn_data_narrow (pn_data_t *data)
	Modify a pn_data_t object to behave as if the current node is the root node of the tree.
void	pn_data_widen (pn_data_t *data)
	Reverse the effect of pn_data_narrow().
pn_handle_t	pn_data_point (pn_data_t *data)
	Returns a handle for the current navigational state of a pn_data_t so that it can be later restored using pn_data_restore().
bool	pn_data_restore (pn_data_t *data, pn_handle_t point)
	Restores a prior navigational state that was saved using pn_data_point().
void	pn_data_dump (pn_data_t *data)
	Dumps a debug representation of the internal state of the pn_data_t object that includes its navigational state to stdout for debugging purposes.

Detailed Description

A data structure for AMQP data.

Typedef Documentation

pn_data_t

typedef struct pn_data_t pn_data_t

An AMQP Data object.

A pn_data_t object provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data. A pn_data_t object contains a tree of AMQP values. Leaf nodes in this tree correspond to scalars in the AMQP type system such as ints or strings . Non-leaf nodes in this tree correspond to compound values in the AMQP type system such as lists , maps , arrays , or described values. The root node of the tree is the pn_data_t object itself and can have an arbitrary number of children.

A pn_data_t object maintains the notion of the current node and the current parent node. Siblings are ordered within their parent. Values are accessed and/or added by using the pn_data_next(), pn_data_prev(), pn_data_enter(), and pn_data_exit() operations to navigate to the desired location in the tree and using the supplied variety of pn_data_put_* / pn_data_get_* operations to access or add a value of the desired type.

The pn_data_put_* operations will always add a value after the current node in the tree. If the current node has a next sibling the pn_data_put_* operations will overwrite the value on this node. If there is no current node or the current node has no next sibling then one will be added. The pn_data_put_* operations always set the added/modified node to the current node. The pn_data_get_* operations read the value of the current node and do not change which node is current.

The following types of scalar values are supported:

• PN_NULL
• PN_BOOL
• PN_UBYTE
• PN_USHORT
• PN_SHORT
• PN_UINT
• PN_INT
• PN_ULONG
• PN_LONG
• PN_FLOAT
• PN_DOUBLE
• PN_BINARY
• PN_STRING
• PN_SYMBOL

The following types of compound values are supported:

• PN_DESCRIBED
• PN_ARRAY
• PN_LIST
• PN_MAP

Function Documentation

pn_data()

pn_data_t * pn_data

(

size_t

capacity

)

Construct a pn_data_t object with the supplied initial capacity.

A pn_data_t will grow automatically as needed, so an initial capacity of 0 is permitted.

Parameters

capacity

the initial capacity

Returns

the newly constructed pn_data_t

pn_data_free()

void pn_data_free

(

pn_data_t *

data

)

Free a pn_data_t object.

Parameters

data	a pn_data_t object or NULL

pn_data_errno()

int pn_data_errno

(

pn_data_t *

data

)

Access the current error code for a given pn_data_t.

Parameters

data	a pn_data_t object

Returns

the current error code

pn_data_error()

pn_error_t * pn_data_error

(

pn_data_t *

data

)

Access the current error for a given pn_data_t.

Every pn_data_t has an error descriptor that is created with the pn_data_t and dies with the pn_data_t. The error descriptor is updated whenever an operation fails. The pn_data_error() function may be used to access a pn_data_t's error descriptor.

Parameters

data	a pn_data_t object

Returns

a pointer to the pn_data_t's error descriptor

pn_data_clear()

void pn_data_clear

(

pn_data_t *

data

)

Clears a pn_data_t object.

A cleared pn_data_t object is equivalent to a newly constructed one.

Parameters

data	the pn_data_t object to clear

pn_data_size()

size_t pn_data_size

(

pn_data_t *

data

)

Returns the total number of nodes contained in a pn_data_t object.

This includes all parents, children, siblings, grandchildren, etc. In other words the count of all ancestors and descendants of the current node, along with the current node if there is one.

Parameters

data	a pn_data_t object

Returns

the total number of nodes in the pn_data_t object

pn_data_rewind()

void pn_data_rewind

(

pn_data_t *

data

)

Clears current node pointer and sets the parent to the root node.

Clearing the current node sets it before the first node, calling pn_data_next() will advance to the first node.

pn_data_next()

bool pn_data_next

(

pn_data_t *

data

)

Advances the current node to its next sibling and returns true.

If there is no next sibling the current node remains unchanged and false is returned.

Parameters

data	a pn_data_t object

Returns

true iff the current node was changed

pn_data_prev()

bool pn_data_prev

(

pn_data_t *

data

)

Moves the current node to its previous sibling and returns true.

If there is no previous sibling the current node remains unchanged and false is returned.

Parameters

data	a pn_data_t object

Returns

true iff the current node was changed

pn_data_enter()

bool pn_data_enter

(

pn_data_t *

data

)

Sets the parent node to the current node and clears the current node.

Clearing the current node sets it before the first child, calling pn_data_next() advances to the first child. This operation will return false if there is no current node or if the current node is not a compound type.

Parameters

data	a pn_data_object

Returns

true iff the pointers to the current/parent nodes are changed

Examples

direct.c, and send.c.

pn_data_exit()

bool pn_data_exit

(

pn_data_t *

data

)

Sets the current node to the parent node and the parent node to its own parent.

This operation will return false if there is no current node or parent node.

Parameters

data	a pn_data object

Returns

true iff the pointers to the current/parent nodes are changed

Examples

direct.c, and send.c.

pn_data_type()

pn_type_t pn_data_type

(

pn_data_t *

data

)

Access the type of the current node.

Returns PN_INVALID if there is no current node.

Parameters

data	a data object

Returns

the type of the current node

pn_data_print()

int pn_data_print

(

pn_data_t *

data

)

Prints the contents of a pn_data_t object using pn_data_format() to stdout.

Parameters

data	a pn_data_t object

Returns

zero on success or an error on failure

pn_data_format()

int pn_data_format	(	pn_data_t *	data,
		char *	bytes,
		size_t *	size
	)

Formats the contents of a pn_data_t object in a human readable way and writes them to the indicated location.

The size pointer must hold the amount of free space following the bytes pointer, and upon success will be updated to indicate how much space has been used.

Parameters

data	a pn_data_t object
bytes	a buffer to write the output to
size	a pointer to the size of the buffer

Returns

zero on success, or an error on failure

pn_data_encode()

ssize_t pn_data_encode	(	pn_data_t *	data,
		char *	bytes,
		size_t	size
	)

Writes the contents of a data object to the given buffer as an AMQP data stream.

Parameters

data	the data object to encode
bytes	the buffer for encoded data
size	the size of the buffer

Returns

the size of the encoded data on success or an error code on failure

pn_data_encoded_size()

ssize_t pn_data_encoded_size

(

pn_data_t *

data

)

Returns the number of bytes needed to encode a data object.

Parameters

data	the data object

Returns

the size of the encoded data or an error code if data is invalid.

pn_data_decode()

ssize_t pn_data_decode	(	pn_data_t *	data,
		const char *	bytes,
		size_t	size
	)

Decodes a single value from the contents of the AMQP data stream into the current data object.

Note that if the pn_data_t object is pointing to a current node, the decoded value will overwrite the current one. If the pn_data_t object has no current node then a node will be appended to the current parent. If there is no current parent then a node will be appended to the pn_data_t itself.

Upon success, this operation returns the number of bytes consumed from the AMQP data stream. Upon failure, this operation returns an error code.

Parameters

data	a pn_data_t object
bytes	a pointer to an encoded AMQP data stream
size	the size of the encoded AMQP data stream

Returns

the number of bytes consumed from the AMQP data stream or an error code

pn_data_put_list()

int pn_data_put_list

(

pn_data_t *

data

)

Puts an empty list value into a pn_data_t.

Elements may be filled by entering the list node using pn_data_enter() and using pn_data_put_* to add the desired contents. Once done, pn_data_exit() may be used to return to the current level in the tree and put more values.

pn_data_t *data = pn_data(0);
...
pn_data_put_list(data);
pn_data_enter(data);
pn_data_put_int(data, 1);
pn_data_put_int(data, 2);
pn_data_put_int(data, 3);
pn_data_exit(data);
...

Parameters

data	a pn_data_t object

Returns

zero on success or an error code on failure

pn_data_put_map()

int pn_data_put_map

(

pn_data_t *

data

)

Puts an empty map value into a pn_data_t.

Elements may be filled by entering the map node and putting alternating key value pairs.

pn_data_t *data = pn_data(0);
...
pn_data_put_map(data);
pn_data_enter(data);
pn_data_put_string(data, pn_bytes(3, "key"));
pn_data_put_string(data, pn_bytes(5, "value"));
pn_data_exit(data);
...

Parameters

data	a pn_data_t object

Returns

zero on success or an error code on failure

Examples

direct.c, and send.c.

pn_data_put_array()

int pn_data_put_array	(	pn_data_t *	data,
		bool	described,
		pn_type_t	type
	)

Puts an empty array value into a pn_data_t.

Elements may be filled by entering the array node and putting the element values. The values must all be of the specified array element type. If an array is described then the first child value of the array is the descriptor and may be of any type.

pn_data_t *data = pn_data(0);
...
pn_data_put_array(data, false, PN_INT);
pn_data_enter(data);
pn_data_put_int(data, 1);
pn_data_put_int(data, 2);
pn_data_put_int(data, 3);
pn_data_exit(data);
...
pn_data_put_array(data, True, Data.DOUBLE);
pn_data_enter(data);
pn_data_put_symbol(data, "array-descriptor");
pn_data_put_double(data, 1.1);
pn_data_put_double(data, 1.2);
pn_data_put_double(data, 1.3);
pn_data_exit(data);
...

Parameters

data	a pn_data_t object
described	specifies whether the array is described
type	the type of the array

Returns

zero on success or an error code on failure

pn_data_put_described()

int pn_data_put_described

(

pn_data_t *

data

)

Puts a described value into a pn_data_t object.

A described node has two children, the descriptor and the value. These are specified by entering the node and putting the desired values.

pn_data_t *data = pn_data(0);
...
pn_data_put_described(data);
pn_data_enter(data);
pn_data_put_symbol(data, pn_bytes(16, "value-descriptor"));
pn_data_put_string(data, pn_bytes(9, "the value"));
pn_data_exit(data);
...

Parameters

data	a pn_data_t object

Returns

zero on success or an error code on failure

pn_data_put_null()

int pn_data_put_null

(

pn_data_t *

data

)

Puts a PN_NULL value.

Parameters

data	a pn_data_t object

Returns

zero on success or an error code on failure

pn_data_put_bool()

int pn_data_put_bool	(	pn_data_t *	data,
		bool	b
	)

Puts a PN_BOOL value.

Parameters

data	a pn_data_t object
b	the value

Returns

zero on success or an error code on failure

pn_data_put_ubyte()

int pn_data_put_ubyte	(	pn_data_t *	data,
		uint8_t	ub
	)

Puts a PN_UBYTE value.

Parameters

data	a pn_data_t object
ub	the value

Returns

zero on success or an error code on failure

pn_data_put_byte()

int pn_data_put_byte	(	pn_data_t *	data,
		int8_t	b
	)

Puts a PN_BYTE value.

Parameters

data	a pn_data_t object
b	the value

Returns

zero on success or an error code on failure

pn_data_put_ushort()

int pn_data_put_ushort	(	pn_data_t *	data,
		uint16_t	us
	)

Puts a PN_USHORT value.

Parameters

data	a pn_data_t object
us	the value

Returns

zero on success or an error code on failure

pn_data_put_short()

int pn_data_put_short	(	pn_data_t *	data,
		int16_t	s
	)

Puts a PN_SHORT value.

Parameters

data	a pn_data_t object
s	the value

Returns

zero on success or an error code on failure

pn_data_put_uint()

int pn_data_put_uint	(	pn_data_t *	data,
		uint32_t	ui
	)

Puts a PN_UINT value.

Parameters

data	a pn_data_t object
ui	the value

Returns

zero on success or an error code on failure

pn_data_put_int()

int pn_data_put_int	(	pn_data_t *	data,
		int32_t	i
	)

Puts a PN_INT value.

Parameters

data	a pn_data_t object
i	the value

Returns

zero on success or an error code on failure

Examples

direct.c, and send.c.

pn_data_put_char()

int pn_data_put_char	(	pn_data_t *	data,
		pn_char_t	c
	)

Puts a PN_CHAR value.

Parameters

data	a pn_data_t object
c	the value

Returns

zero on success or an error code on failure

pn_data_put_ulong()

int pn_data_put_ulong	(	pn_data_t *	data,
		uint64_t	ul
	)

Puts a PN_ULONG value.

Parameters

data	a pn_data_t object
ul	the value

Returns

zero on success or an error code on failure

pn_data_put_long()

int pn_data_put_long	(	pn_data_t *	data,
		int64_t	l
	)

Puts a PN_LONG value.

Parameters

data	a pn_data_t object
l	the value

Returns

zero on success or an error code on failure

pn_data_put_timestamp()

int pn_data_put_timestamp	(	pn_data_t *	data,
		pn_timestamp_t	t
	)

Puts a PN_TIMESTAMP value.

Parameters

data	a pn_data_t object
t	the value

Returns

zero on success or an error code on failure

pn_data_put_float()

int pn_data_put_float	(	pn_data_t *	data,
		float	f
	)

Puts a PN_FLOAT value.

Parameters

data	a pn_data_t object
f	the value

Returns

zero on success or an error code on failure

pn_data_put_double()

int pn_data_put_double	(	pn_data_t *	data,
		double	d
	)

Puts a PN_DOUBLE value.

Parameters

data	a pn_data_t object
d	the value

Returns

zero on success or an error code on failure

pn_data_put_decimal32()

int pn_data_put_decimal32	(	pn_data_t *	data,
		pn_decimal32_t	d
	)

Puts a PN_DECIMAL32 value.

Parameters

data	a pn_data_t object
d	the value

Returns

zero on success or an error code on failure

pn_data_put_decimal64()

int pn_data_put_decimal64	(	pn_data_t *	data,
		pn_decimal64_t	d
	)

Puts a PN_DECIMAL64 value.

Parameters

data	a pn_data_t object
d	the value

Returns

zero on success or an error code on failure

pn_data_put_decimal128()

int pn_data_put_decimal128	(	pn_data_t *	data,
		pn_decimal128_t	d
	)

Puts a PN_DECIMAL128 value.

Parameters

data	a pn_data_t object
d	the value

Returns

zero on success or an error code on failure

pn_data_put_uuid()

int pn_data_put_uuid	(	pn_data_t *	data,
		pn_uuid_t	u
	)

Puts a PN_UUID value.

Parameters

data	a pn_data_t object
u	the value

Returns

zero on success or an error code on failure

pn_data_put_binary()

int pn_data_put_binary	(	pn_data_t *	data,
		pn_bytes_t	bytes
	)

Puts a PN_BINARY value.

The bytes referenced by the pn_bytes_t argument are copied and stored inside the pn_data_t object.

Parameters

data	a pn_data_t object
bytes	the value

Returns

zero on success or an error code on failure

pn_data_put_string()

int pn_data_put_string	(	pn_data_t *	data,
		pn_bytes_t	string
	)

Puts a PN_STRING value.

The bytes referenced by the pn_bytes_t argument are copied and stored inside the pn_data_t object.

Parameters

data	a pn_data_t object
string	utf8 encoded unicode

Returns

zero on success or an error code on failure

Examples

direct.c, and send.c.

pn_data_put_symbol()

int pn_data_put_symbol	(	pn_data_t *	data,
		pn_bytes_t	symbol
	)

Puts a PN_SYMBOL value.

The bytes referenced by the pn_bytes_t argument are copied and stored inside the pn_data_t object.

Parameters

data	a pn_data_t object
symbol	ascii encoded symbol

Returns

zero on success or an error code on failure

pn_data_put_atom()

int pn_data_put_atom	(	pn_data_t *	data,
		pn_atom_t	atom
	)

Puts any scalar value value.

Parameters

data	a pn_data_t object
atom	the value

Returns

zero on success or an error code on failure

pn_data_get_list()

size_t pn_data_get_list

(

pn_data_t *

data

)

If the current node is a list, return the number of elements, otherwise return zero.

List elements can be accessed by entering the list.

...
size_t count = pn_data_get_list(data);
pn_data_enter(data);
for (size_t i = 0; i < count; i++) {
    if (pn_data_next(data)) {
      switch (pn_data_type(data)) {
      case PN_STRING:
        ...
        break;
      case PN_INT:
        ...
        break;
     }
}
pn_data_exit(data);
...

.*

Parameters

data	a pn_data_t object

Returns

the size of a list node

pn_data_get_map()

size_t pn_data_get_map

(

pn_data_t *

data

)

If the current node is a map, return the number of child elements, otherwise return zero.

Key value pairs can be accessed by entering the map.

...
size_t count = pn_data_get_map(data);
pn_data_enter(data);
for (size_t i = 0; i < count/2; i++) {
  // read key
  if (pn_data_next(data)) {
    switch (pn_data_type(data)) {
      case PN_STRING:
        ...
      break;
      ...
    }
  }
  ...
  // read value
  if (pn_data_next(data)) {
    switch (pn_data_type(data)) {
      case PN_INT:
        ...
      break;
      ...
    }
  }
  ...
}
pn_data_exit(data);
...

Parameters

data	a pn_data_t object

Returns

the number of child elements of a map node

pn_data_get_array()

size_t pn_data_get_array

(

pn_data_t *

data

)

If the current node is an array, return the number of elements in the array, otherwise return 0.

Array data can be accessed by entering the array. If the array is described, the first child node will be the descriptor, and the remaining count child nodes will be the elements of the array.

...
size_t count = pn_data_get_array(data);
bool described = pn_data_is_array_described(data);
pn_type_t type = pn_data_get_array_type(data);
 
pn_data_enter(data);
 
if (described && pn_data_next(data)) {
    // the descriptor could be another type, but let's assume it's a symbol
    pn_bytes_t descriptor = pn_data_get_symbol(data);
}
 
for (size_t i = 0; i < count; i++) {
  if (pn_data_next(data)) {
      // all elements will be values of the array type retrieved above
      ...
  }
}
pn_data_exit(data);
...

Parameters

data	a pn_data_t object

Returns

the number of elements of an array node

pn_data_is_array_described()

bool pn_data_is_array_described

(

pn_data_t *

data

)

Returns true if the current node points to a described array.

Parameters

data	a pn_data_t object

Returns

true if the current node points to a described array

pn_data_get_array_type()

pn_type_t pn_data_get_array_type

(

pn_data_t *

data

)

Return the array type if the current node points to an array, PN_INVALID otherwise.

Parameters

data	a pn_data_t object

Returns

the element type of an array node

pn_data_is_described()

bool pn_data_is_described

(

pn_data_t *

data

)

Checks if the current node is a described value.

The descriptor and value may be accessed by entering the described value node.

...
// read a symbolically described string
if (pn_data_is_described(data)) {
  pn_data_enter(data);
  pn_data_next(data);
  assert(pn_data_type(data) == PN_SYMBOL);
  pn_bytes_t symbol = pn_data_get_symbol(data);
  pn_data_next(data);
  assert(pn_data_type(data) == PN_STRING);
  pn_bytes_t utf8 = pn_data_get_string(data);
  pn_data_exit(data);
}
...

Parameters

data	a pn_data_t object

Returns

true if the current node is a described type

pn_data_is_null()

bool pn_data_is_null

(

pn_data_t *

data

)

Checks if the current node is a PN_NULL.

Parameters

data	a pn_data_t object

Returns

true iff the current node is PN_NULL

pn_data_get_bool()

bool pn_data_get_bool

(

pn_data_t *

data

)

If the current node is a PN_BOOL, returns its value.

Parameters

data	a pn_data_t object

pn_data_get_ubyte()

uint8_t pn_data_get_ubyte

(

pn_data_t *

data

)

If the current node is a PN_UBYTE, return its value, otherwise return 0.

Parameters

data	a pn_data_t object

pn_data_get_byte()

int8_t pn_data_get_byte

(

pn_data_t *

data

)

If the current node is a signed byte, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_ushort()

uint16_t pn_data_get_ushort

(

pn_data_t *

data

)

If the current node is an unsigned short, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_short()

int16_t pn_data_get_short

(

pn_data_t *

data

)

If the current node is a signed short, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_uint()

uint32_t pn_data_get_uint

(

pn_data_t *

data

)

If the current node is an unsigned int, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_int()

int32_t pn_data_get_int

(

pn_data_t *

data

)

If the current node is a signed int, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_char()

pn_char_t pn_data_get_char

(

pn_data_t *

data

)

If the current node is a char, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_ulong()

uint64_t pn_data_get_ulong

(

pn_data_t *

data

)

If the current node is an unsigned long, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_long()

int64_t pn_data_get_long

(

pn_data_t *

data

)

If the current node is an signed long, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_timestamp()

pn_timestamp_t pn_data_get_timestamp

(

pn_data_t *

data

)

If the current node is a timestamp, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_float()

float pn_data_get_float

(

pn_data_t *

data

)

If the current node is a float, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_double()

double pn_data_get_double

(

pn_data_t *

data

)

If the current node is a double, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_decimal32()

pn_decimal32_t pn_data_get_decimal32

(

pn_data_t *

data

)

If the current node is a decimal32, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_decimal64()

pn_decimal64_t pn_data_get_decimal64

(

pn_data_t *

data

)

If the current node is a decimal64, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_decimal128()

pn_decimal128_t pn_data_get_decimal128

(

pn_data_t *

data

)

If the current node is a decimal128, returns its value, returns 0 otherwise.

Parameters

data	a pn_data_t object

pn_data_get_uuid()

pn_uuid_t pn_data_get_uuid

(

pn_data_t *

data

)

If the current node is a UUID, returns its value, returns None otherwise.

Parameters

data	a pn_data_t object

Returns

a uuid value

pn_data_get_binary()

pn_bytes_t pn_data_get_binary

(

pn_data_t *

data

)

If the current node is binary, returns its value, returns "" otherwise.

The pn_bytes_t returned will point to memory held inside the pn_data_t. When the pn_data_t is cleared or freed, this memory will be reclaimed.

Parameters

data	a pn_data_t object

pn_data_get_string()

pn_bytes_t pn_data_get_string

(

pn_data_t *

data

)

If the current node is a string, returns its value, returns "" otherwise.

The pn_bytes_t returned will point to memory held inside the pn_data_t. When the pn_data_t is cleared or freed, this memory will be reclaimed.

Parameters

data	a pn_data_t object

Returns

a pn_bytes_t pointing to utf8

pn_data_get_symbol()

pn_bytes_t pn_data_get_symbol

(

pn_data_t *

data

)

If the current node is a symbol, returns its value, returns "" otherwise.

The pn_bytes_t returned will point to memory held inside the pn_data_t. When the pn_data_t is cleared or freed, this memory will be reclaimed.

Parameters

data	a pn_data_t object

Returns

a pn_bytes_t pointing to ascii

pn_data_get_bytes()

pn_bytes_t pn_data_get_bytes

(

pn_data_t *

data

)

If the current node is a symbol, string, or binary, return the bytes representing its value.

The pn_bytes_t returned will point to memory held inside the pn_data_t. When the pn_data_t is cleared or freed, this memory will be reclaimed.

Parameters

data	a pn_data_t object

Returns

a pn_bytes_t pointing to the node's value

pn_data_get_atom()

pn_atom_t pn_data_get_atom

(

pn_data_t *

data

)

If the current node is a scalar value, return it as a pn_atom_t.

Parameters

data	a pn_data_t object

Returns

the value of the current node as pn_atom_t

pn_data_copy()

int pn_data_copy	(	pn_data_t *	data,
		pn_data_t *	src
	)

Copy the contents of another pn_data_t object.

Any values in the data object will be lost.

Parameters

data	a pn_data_t object
src	the source pn_data_t to copy from

Returns

zero on success or an error code on failure

pn_data_append()

int pn_data_append	(	pn_data_t *	data,
		pn_data_t *	src
	)

Append the contents of another pn_data_t object.

Parameters

data	a pn_data_t object
src	the source pn_data_t to append from

Returns

zero on success or an error code on failure

pn_data_appendn()

int pn_data_appendn	(	pn_data_t *	data,
		pn_data_t *	src,
		int	limit
	)

Append up to n values from the contents of another pn_data_t object.

Parameters

data	a pn_data_t object
src	the source pn_data_t to append from
limit	the maximum number of values to append

Returns

zero on success or an error code on failure

pn_data_narrow()

void pn_data_narrow

(

pn_data_t *

data

)

Modify a pn_data_t object to behave as if the current node is the root node of the tree.

This impacts the behaviour of pn_data_rewind(), pn_data_next(), pn_data_prev(), and anything else that depends on the navigational state of the pn_data_t object. Use pn_data_widen() to reverse the effect of this operation.

Parameters

data	a pn_data_t object

pn_data_widen()

void pn_data_widen

(

pn_data_t *

data

)

Reverse the effect of pn_data_narrow().

Parameters

data	a pn_data_t object

pn_data_point()

pn_handle_t pn_data_point

(

pn_data_t *

data

)

Returns a handle for the current navigational state of a pn_data_t so that it can be later restored using pn_data_restore().

Parameters

data	a pn_data_t object

Returns

a handle for the current navigational state

pn_data_restore()

bool pn_data_restore	(	pn_data_t *	data,
		pn_handle_t	point
	)

Restores a prior navigational state that was saved using pn_data_point().

If the data object has been modified in such a way that the prior navigational state cannot be restored, then this will return false and the navigational state will remain unchanged, otherwise it will return true.

Parameters

data	a pn_data_t object
point	a handle referencing the saved navigational state

Returns

true iff the prior navigational state was restored

pn_data_dump()

void pn_data_dump

(

pn_data_t *

data

)

Dumps a debug representation of the internal state of the pn_data_t object that includes its navigational state to stdout for debugging purposes.

Parameters

data	a pn_data_t object that is behaving in a confusing way