Data
Codec

A data structure for AMQP data. More...

Collaboration diagram for Data:

## Typedefs

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

## Functions

pn_data_t * | pn_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_t * | pn_data_error (pn_data_t *data)
| Access the current error for a given 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:

- 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);
...
pn_data_enter
bool pn_data_enter(pn_data_t *data)
Sets the parent node to the current node and clears the current node.
pn_data_t
struct pn_data_t pn_data_t
An AMQP Data object.
Definition: codec.h:364
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.
pn_data_put_int
int pn_data_put_int(pn_data_t *data, int32_t i)
Puts a PN_INT value.
pn_data
pn_data_t * pn_data(size_t capacity)
Construct a pn_data_t object with the supplied initial capacity.

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);
...
pn_bytes
pn_bytes_t pn_bytes(size_t size, const char *start)
Create a pn_bytes_t.
pn_data_put_string
int pn_data_put_string(pn_data_t *data, pn_bytes_t string)
Puts a PN_STRING value.

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);
...
PN_INT
@ PN_INT
The signed int AMQP type.
Definition: codec.h:86
pn_data_put_symbol
int pn_data_put_symbol(pn_data_t *data, pn_bytes_t symbol)
Puts a PN_SYMBOL value.
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
  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);
...
PN_STRING
@ PN_STRING
The string AMQP type.
Definition: codec.h:148
pn_data_type
pn_type_t pn_data_type(pn_data_t *data)
Access the type of the current node.
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.
pn_data_next
bool pn_data_next(pn_data_t *data)
Advances the current node to its next sibling and returns true.

.*

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);
...
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.

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);
...
pn_type_t
pn_type_t
Identifies an AMQP type.
Definition: codec.h:47
pn_bytes_t
A const byte buffer.
Definition: types.h:212
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.
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.
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.
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.

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);
}
...
PN_SYMBOL
@ PN_SYMBOL
The symbol AMQP type.
Definition: codec.h:154
pn_data_is_described
bool pn_data_is_described(pn_data_t *data)
Checks if the current node is a described value.
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.

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, raises 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