Qpid Proton C API  0.18.1
Data

A data structure for AMQP data. More...

Typedefs

typedef struct pn_data_t pn_data_t
 An AMQP Data object. More...
 

Functions

pn_data_tpn_data (size_t capacity)
 Construct a pn_data_t object with the supplied initial capacity. More...
 
void pn_data_free (pn_data_t *data)
 Free a pn_data_t object. More...
 
int pn_data_errno (pn_data_t *data)
 Access the current error code for a given pn_data_t. More...
 
pn_error_tpn_data_error (pn_data_t *data)
 Access the current error for a givn pn_data_t. More...
 
void pn_data_clear (pn_data_t *data)
 Clears a pn_data_t object. More...
 
size_t pn_data_size (pn_data_t *data)
 Returns the total number of nodes contained in a pn_data_t object. More...
 
void pn_data_rewind (pn_data_t *data)
 Clears current node pointer and sets the parent to the root node. More...
 
bool pn_data_next (pn_data_t *data)
 Advances the current node to its next sibling and returns true. More...
 
bool pn_data_prev (pn_data_t *data)
 Moves the current node to its previous sibling and returns true. More...
 
bool pn_data_enter (pn_data_t *data)
 Sets the parent node to the current node and clears the current node. More...
 
bool pn_data_exit (pn_data_t *data)
 Sets the current node to the parent node and the parent node to its own parent. More...
 
pn_type_t pn_data_type (pn_data_t *data)
 Access the type of the current node. More...
 
int pn_data_print (pn_data_t *data)
 Prints the contents of a pn_data_t object using pn_data_format() to stdout. More...
 
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. More...
 
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. More...
 
ssize_t pn_data_encoded_size (pn_data_t *data)
 Returns the number of bytes needed to encode a data object. More...
 
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. More...
 
int pn_data_put_list (pn_data_t *data)
 Puts an empty list value into a pn_data_t. More...
 
int pn_data_put_map (pn_data_t *data)
 Puts an empty map value into a pn_data_t. More...
 
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. More...
 
int pn_data_put_described (pn_data_t *data)
 Puts a described value into a pn_data_t object. More...
 
int pn_data_put_null (pn_data_t *data)
 Puts a PN_NULL value. More...
 
int pn_data_put_bool (pn_data_t *data, bool b)
 Puts a PN_BOOL value. More...
 
int pn_data_put_ubyte (pn_data_t *data, uint8_t ub)
 Puts a PN_UBYTE value. More...
 
int pn_data_put_byte (pn_data_t *data, int8_t b)
 Puts a PN_BYTE value. More...
 
int pn_data_put_ushort (pn_data_t *data, uint16_t us)
 Puts a PN_USHORT value. More...
 
int pn_data_put_short (pn_data_t *data, int16_t s)
 Puts a PN_SHORT value. More...
 
int pn_data_put_uint (pn_data_t *data, uint32_t ui)
 Puts a PN_UINT value. More...
 
int pn_data_put_int (pn_data_t *data, int32_t i)
 Puts a PN_INT value. More...
 
int pn_data_put_char (pn_data_t *data, pn_char_t c)
 Puts a PN_CHAR value. More...
 
int pn_data_put_ulong (pn_data_t *data, uint64_t ul)
 Puts a PN_ULONG value. More...
 
int pn_data_put_long (pn_data_t *data, int64_t l)
 Puts a PN_LONG value. More...
 
int pn_data_put_timestamp (pn_data_t *data, pn_timestamp_t t)
 Puts a PN_TIMESTAMP value. More...
 
int pn_data_put_float (pn_data_t *data, float f)
 Puts a PN_FLOAT value. More...
 
int pn_data_put_double (pn_data_t *data, double d)
 Puts a PN_DOUBLE value. More...
 
int pn_data_put_decimal32 (pn_data_t *data, pn_decimal32_t d)
 Puts a PN_DECIMAL32 value. More...
 
int pn_data_put_decimal64 (pn_data_t *data, pn_decimal64_t d)
 Puts a PN_DECIMAL64 value. More...
 
int pn_data_put_decimal128 (pn_data_t *data, pn_decimal128_t d)
 Puts a PN_DECIMAL128 value. More...
 
int pn_data_put_uuid (pn_data_t *data, pn_uuid_t u)
 Puts a PN_UUID value. More...
 
int pn_data_put_binary (pn_data_t *data, pn_bytes_t bytes)
 Puts a PN_BINARY value. More...
 
int pn_data_put_string (pn_data_t *data, pn_bytes_t string)
 Puts a PN_STRING value. More...
 
int pn_data_put_symbol (pn_data_t *data, pn_bytes_t symbol)
 Puts a PN_SYMBOL value. More...
 
int pn_data_put_atom (pn_data_t *data, pn_atom_t atom)
 Puts any scalar value value. More...
 
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. More...
 
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. More...
 
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. More...
 
bool pn_data_is_array_described (pn_data_t *data)
 Returns true if the current node points to a described array. More...
 
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. More...
 
bool pn_data_is_described (pn_data_t *data)
 Checks if the current node is a described value. More...
 
bool pn_data_is_null (pn_data_t *data)
 Checks if the current node is a PN_NULL. More...
 
bool pn_data_get_bool (pn_data_t *data)
 If the current node is a PN_BOOL, returns its value. More...
 
uint8_t pn_data_get_ubyte (pn_data_t *data)
 If the current node is a PN_UBYTE, return its value, otherwise return 0. More...
 
int8_t pn_data_get_byte (pn_data_t *data)
 If the current node is a signed byte, returns its value, returns 0 otherwise. More...
 
uint16_t pn_data_get_ushort (pn_data_t *data)
 If the current node is an unsigned short, returns its value, returns 0 otherwise. More...
 
int16_t pn_data_get_short (pn_data_t *data)
 If the current node is a signed short, returns its value, returns 0 otherwise. More...
 
uint32_t pn_data_get_uint (pn_data_t *data)
 If the current node is an unsigned int, returns its value, returns 0 otherwise. More...
 
int32_t pn_data_get_int (pn_data_t *data)
 If the current node is a signed int, returns its value, returns 0 otherwise. More...
 
pn_char_t pn_data_get_char (pn_data_t *data)
 If the current node is a char, returns its value, returns 0 otherwise. More...
 
uint64_t pn_data_get_ulong (pn_data_t *data)
 If the current node is an unsigned long, returns its value, returns 0 otherwise. More...
 
int64_t pn_data_get_long (pn_data_t *data)
 If the current node is an signed long, returns its value, returns 0 otherwise. More...
 
pn_timestamp_t pn_data_get_timestamp (pn_data_t *data)
 If the current node is a timestamp, returns its value, returns 0 otherwise. More...
 
float pn_data_get_float (pn_data_t *data)
 If the current node is a float, returns its value, raises 0 otherwise. More...
 
double pn_data_get_double (pn_data_t *data)
 If the current node is a double, returns its value, returns 0 otherwise. More...
 
pn_decimal32_t pn_data_get_decimal32 (pn_data_t *data)
 If the current node is a decimal32, returns its value, returns 0 otherwise. More...
 
pn_decimal64_t pn_data_get_decimal64 (pn_data_t *data)
 If the current node is a decimal64, returns its value, returns 0 otherwise. More...
 
pn_decimal128_t pn_data_get_decimal128 (pn_data_t *data)
 If the current node is a decimal128, returns its value, returns 0 otherwise. More...
 
pn_uuid_t pn_data_get_uuid (pn_data_t *data)
 If the current node is a UUID, returns its value, returns None otherwise. More...
 
pn_bytes_t pn_data_get_binary (pn_data_t *data)
 If the current node is binary, returns its value, returns "" otherwise. More...
 
pn_bytes_t pn_data_get_string (pn_data_t *data)
 If the current node is a string, returns its value, returns "" otherwise. More...
 
pn_bytes_t pn_data_get_symbol (pn_data_t *data)
 If the current node is a symbol, returns its value, returns "" otherwise. More...
 
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. More...
 
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. More...
 
int pn_data_copy (pn_data_t *data, pn_data_t *src)
 Copy the contents of another pn_data_t object. More...
 
int pn_data_append (pn_data_t *data, pn_data_t *src)
 Append the contents of another pn_data_t object. More...
 
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. More...
 
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. More...
 
void pn_data_widen (pn_data_t *data)
 Reverse the effect of pn_data_narrow(). More...
 
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(). More...
 
bool pn_data_restore (pn_data_t *data, pn_handle_t point)
 Restores a prior navigational state that was saved using pn_data_point(). More...
 
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. More...
 

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:

The following types of compound values are supported:

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
capacitythe 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
dataa 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
dataa 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 givn 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
dataa 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
datathe 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 ancesters and descendents of the current node, along with the current node if there is one.

Parameters
dataa 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
dataa 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
dataa 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
dataa pn_data_object
Returns
true iff the pointers to the current/parent nodes are changed

◆ 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
dataa pn_data object
Returns
true iff the pointers to the current/parent nodes are changed

◆ 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
dataa 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
dataa 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
dataa pn_data_t object
bytesa buffer to write the output to
sizea pointer to the size of the buffer
Returns
zero on succes, 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
datathe data object to encode
bytesthe buffer for encoded data
sizethe 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
datathe 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
dataa pn_data_t object
bytesa pointer to an encoded AMQP data stream
sizethe 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_put_int(data, 1);
pn_data_put_int(data, 2);
pn_data_put_int(data, 3);
...
Parameters
dataa 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_put_string(data, pn_bytes(3, "key"));
pn_data_put_string(data, pn_bytes(5, "value"));
...
Parameters
dataa pn_data_t object
Returns
zero on success or an error code on failure

◆ 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_put_int(data, 1);
pn_data_put_int(data, 2);
pn_data_put_int(data, 3);
...
pn_data_put_array(data, True, Data.DOUBLE);
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);
...
Parameters
dataa pn_data_t object
describedspecifies whether the array is described
typethe 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_put_symbol(data, pn_bytes(16, "value-descriptor"));
pn_data_put_string(data, pn_bytes(9, "the value"));
...
Parameters
dataa 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
dataa 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
dataa pn_data_t object
bthe 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
dataa pn_data_t object
ubthe 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
dataa pn_data_t object
bthe 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
dataa pn_data_t object
usthe 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
dataa pn_data_t object
sthe 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
dataa pn_data_t object
uithe 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
dataa pn_data_t object
ithe value
Returns
zero on success or an error code on failure

◆ pn_data_put_char()

int pn_data_put_char ( pn_data_t data,
pn_char_t  c 
)

Puts a PN_CHAR value.

Parameters
dataa pn_data_t object
cthe 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
dataa pn_data_t object
ulthe 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
dataa pn_data_t object
lthe 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
dataa pn_data_t object
tthe 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
dataa pn_data_t object
fthe 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
dataa pn_data_t object
dthe 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
dataa pn_data_t object
dthe 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
dataa pn_data_t object
dthe 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
dataa pn_data_t object
dthe 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
dataa pn_data_t object
uthe 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
dataa pn_data_t object
bytesthe 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
dataa pn_data_t object
stringutf8 encoded unicode
Returns
zero on success or an error code on failure

◆ 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
dataa pn_data_t object
symbolascii 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
dataa pn_data_t object
atomthe 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);
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;
}
}
...

.*

Parameters
dataa 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);
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;
...
}
}
...
}
...
Parameters
dataa 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);
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
...
}
}
...
Parameters
dataa 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
dataa 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
dataa 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
pn_data_next(data);
assert(pn_data_type(data) == PN_SYMBOL);
pn_data_next(data);
assert(pn_data_type(data) == PN_STRING);
pn_data_exit(data);
}
...
Parameters
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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, raises 0 otherwise.

Parameters
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa 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
dataa pn_data_t object
srcthe sourc 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
dataa pn_data_t object
srcthe sourc 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
dataa pn_data_t object
srcthe sourc pn_data_t to append from
limitthe 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
dataa pn_data_t object

◆ pn_data_widen()

void pn_data_widen ( pn_data_t data)

Reverse the effect of pn_data_narrow().

Parameters
dataa 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
dataa 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
dataa pn_data_t object
pointa 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
dataa pn_data_t object that is behaving in a confusing way