Loading...
Searching...
No Matches
Node API

## Description

The MPack Node API allows you to parse a chunk of MessagePack into a dynamically typed data structure, providing random access to the parsed data.

See Using the Node API for examples.

## Typedefs

typedef struct mpack_node_data_t | mpack_node_data_t
| The storage for nodes in an MPack tree. More...
typedef struct mpack_node_t | mpack_node_t
| A handle to node data in a parsed MPack tree. More...
typedef void(* | mpack_tree_error_t) (mpack_tree_t *tree, mpack_error_t error)
| An error handler function to be called when an error is flagged on the tree. More...
typedef size_t(* | mpack_tree_read_t) (mpack_tree_t *tree, char *buffer, size_t count)
| The MPack tree's read function. More...
typedef struct mpack_tree_t | mpack_tree_t
| An MPack tree parser to parse a blob or stream of MessagePack. More...
typedef void(* | mpack_tree_teardown_t) (mpack_tree_t *tree)
| A teardown function to be called when the tree is destroyed. More...

## Tree Initialization

void | mpack_tree_init_data (mpack_tree_t *tree, const char *data, size_t length)
| Initializes a tree parser with the given data. More...
void | mpack_tree_init (mpack_tree_t *tree, const char *data, size_t length)
| Deprecated. More...
void | mpack_tree_init_stream (mpack_tree_t *tree, mpack_tree_read_t read_fn, void *context, size_t max_message_size, size_t max_message_nodes)
| Initializes a tree parser from an unbounded stream, or a stream of unknown length. More...
void | mpack_tree_init_pool (mpack_tree_t *tree, const char *data, size_t length, mpack_node_data_t *node_pool, size_t node_pool_count)
| Initializes a tree parser with the given data, using the given node data pool to store the results. More...
void | mpack_tree_init_error (mpack_tree_t *tree, mpack_error_t error)
| Initializes an MPack tree directly into an error state. More...
void | mpack_tree_init_filename (mpack_tree_t *tree, const char *filename, size_t max_bytes)
| Initializes a tree to parse the given file. More...
void | mpack_tree_init_file (mpack_tree_t *tree, const char *filename, size_t max_bytes)
| Deprecated. More...
void | mpack_tree_init_stdfile (mpack_tree_t *tree, FILE *stdfile, size_t max_bytes, bool close_when_done)
| Initializes a tree to parse the given libc FILE. More...

## Tree Functions

void | mpack_tree_set_limits (mpack_tree_t *tree, size_t max_message_size, size_t max_message_nodes)
| Sets the maximum byte size and maximum number of nodes allowed per message. More...
void | mpack_tree_parse (mpack_tree_t *tree)
| Parses a MessagePack message into a tree of immutable nodes. More...
bool | mpack_tree_try_parse (mpack_tree_t *tree)
| Attempts to parse a MessagePack message from a non-blocking stream into a tree of immutable nodes. More...
mpack_node_t | mpack_tree_root (mpack_tree_t *tree)
| Returns the root node of the tree, if the tree is not in an error state. More...
mpack_error_t | mpack_tree_error (mpack_tree_t *tree)
| Returns the error state of the tree. More...
size_t | mpack_tree_size (mpack_tree_t *tree)
| Returns the size in bytes of the current parsed message. More...
mpack_error_t | mpack_tree_destroy (mpack_tree_t *tree)
| Destroys the tree. More...
void | mpack_tree_set_context (mpack_tree_t *tree, void *context)
| Sets the custom pointer to pass to the tree callbacks, such as teardown. More...
void * | mpack_tree_context (mpack_tree_t *tree)
| Returns the custom context for tree callbacks. More...
void | mpack_tree_set_error_handler (mpack_tree_t *tree, mpack_tree_error_t error_fn)
| Sets the error function to call when an error is flagged on the tree. More...
void | mpack_tree_set_teardown (mpack_tree_t *tree, mpack_tree_teardown_t teardown)
| Sets the teardown function to call when the tree is destroyed. More...
void | mpack_tree_flag_error (mpack_tree_t *tree, mpack_error_t error)
| Places the tree in the given error state, calling the error callback if one is set. More...

## Node Core Functions

void | mpack_node_flag_error (mpack_node_t node, mpack_error_t error)
| Places the node's tree in the given error state, calling the error callback if one is set. More...
mpack_error_t | mpack_node_error (mpack_node_t node)
| Returns the error state of the node's tree. More...
mpack_tag_t | mpack_node_tag (mpack_node_t node)
| Returns a tag describing the given node, or a nil tag if the tree is in an error state. More...

## Node Primitive Value Functions

mpack_type_t | mpack_node_type (mpack_node_t node)
| Returns the type of the node. More...
bool | mpack_node_is_nil (mpack_node_t node)
| Returns true if the given node is a nil node; false otherwise. More...
bool | mpack_node_is_missing (mpack_node_t node)
| Returns true if the given node handle indicates a missing node; false otherwise. More...
void | mpack_node_nil (mpack_node_t node)
| Checks that the given node is of nil type, raising mpack_error_type otherwise. More...
void | mpack_node_missing (mpack_node_t node)
| Checks that the given node indicates a missing node, raising mpack_error_type otherwise. More...
bool | mpack_node_bool (mpack_node_t node)
| Returns the bool value of the node. More...
void | mpack_node_true (mpack_node_t node)
| Checks if the given node is of bool type with value true, raising mpack_error_type otherwise. More...
void | mpack_node_false (mpack_node_t node)
| Checks if the given node is of bool type with value false, raising mpack_error_type otherwise. More...
uint8_t | mpack_node_u8 (mpack_node_t node)
| Returns the 8-bit unsigned value of the node. More...
int8_t | mpack_node_i8 (mpack_node_t node)
| Returns the 8-bit signed value of the node. More...
uint16_t | mpack_node_u16 (mpack_node_t node)
| Returns the 16-bit unsigned value of the node. More...
int16_t | mpack_node_i16 (mpack_node_t node)
| Returns the 16-bit signed value of the node. More...
uint32_t | mpack_node_u32 (mpack_node_t node)
| Returns the 32-bit unsigned value of the node. More...
int32_t | mpack_node_i32 (mpack_node_t node)
| Returns the 32-bit signed value of the node. More...
uint64_t | mpack_node_u64 (mpack_node_t node)
| Returns the 64-bit unsigned value of the node. More...
int64_t | mpack_node_i64 (mpack_node_t node)
| Returns the 64-bit signed value of the node. More...
unsigned int | mpack_node_uint (mpack_node_t node)
| Returns the unsigned int value of the node. More...
int | mpack_node_int (mpack_node_t node)
| Returns the int value of the node. More...
float | mpack_node_float (mpack_node_t node)
| Returns the float value of the node. More...
double | mpack_node_double (mpack_node_t node)
| Returns the double value of the node. More...
float | mpack_node_float_strict (mpack_node_t node)
| Returns the float value of the node. More...
double | mpack_node_double_strict (mpack_node_t node)
| Returns the double value of the node. More...
mpack_timestamp_t | mpack_node_timestamp (mpack_node_t node)
| Returns a timestamp. More...
int64_t | mpack_node_timestamp_seconds (mpack_node_t node)
| Returns a timestamp's (signed) seconds since 1970-01-01T00:00:00Z. More...
uint32_t | mpack_node_timestamp_nanoseconds (mpack_node_t node)
| Returns a timestamp's additional nanoseconds. More...

## Node String and Data Functions

void | mpack_node_check_utf8 (mpack_node_t node)
| Checks that the given node contains a valid UTF-8 string. More...
void | mpack_node_check_utf8_cstr (mpack_node_t node)
| Checks that the given node contains a valid UTF-8 string with no NUL bytes. More...
int8_t | mpack_node_exttype (mpack_node_t node)
| Returns the extension type of the given ext node. More...
size_t | mpack_node_bin_size (mpack_node_t node)
| Returns the number of bytes in the given bin node. More...
uint32_t | mpack_node_data_len (mpack_node_t node)
| Returns the length of the given str, bin or ext node. More...
size_t | mpack_node_strlen (mpack_node_t node)
| Returns the length in bytes of the given string node. More...
const char * | mpack_node_str (mpack_node_t node)
| Returns a pointer to the data contained by this node, ensuring the node is a string. More...
const char * | mpack_node_data (mpack_node_t node)
| Returns a pointer to the data contained by this node. More...
const char * | mpack_node_bin_data (mpack_node_t node)
| Returns a pointer to the data contained by this bin node. More...
size_t | mpack_node_copy_data (mpack_node_t node, char *buffer, size_t bufsize)
| Copies the bytes contained by this node into the given buffer, returning the number of bytes in the node. More...
size_t | mpack_node_copy_utf8 (mpack_node_t node, char *buffer, size_t bufsize)
| Checks that the given node contains a valid UTF-8 string and copies the string into the given buffer, returning the number of bytes in the string. More...
void | mpack_node_copy_cstr (mpack_node_t node, char *buffer, size_t size)
| Checks that the given node contains a string with no NUL bytes, copies the string into the given buffer, and adds a null terminator. More...
void | mpack_node_copy_utf8_cstr (mpack_node_t node, char *buffer, size_t size)
| Checks that the given node contains a valid UTF-8 string with no NUL bytes, copies the string into the given buffer, and adds a null terminator. More...
char * | mpack_node_data_alloc (mpack_node_t node, size_t maxsize)
| Allocates a new chunk of data using MPACK_MALLOC() with the bytes contained by this node. More...
char * | mpack_node_cstr_alloc (mpack_node_t node, size_t maxsize)
| Allocates a new null-terminated string using MPACK_MALLOC() with the string contained by this node. More...
char * | mpack_node_utf8_cstr_alloc (mpack_node_t node, size_t maxsize)
| Allocates a new null-terminated string using MPACK_MALLOC() with the UTF-8 string contained by this node. More...
size_t | mpack_node_enum (mpack_node_t node, const char *strings[], size_t count)
| Searches the given string array for a string matching the given node and returns its index. More...
size_t | mpack_node_enum_optional (mpack_node_t node, const char *strings[], size_t count)
| Searches the given string array for a string matching the given node, returning its index or count if no strings match. More...

## Compound Node Functions

size_t | mpack_node_array_length (mpack_node_t node)
| Returns the length of the given array node. More...
mpack_node_t | mpack_node_array_at (mpack_node_t node, size_t index)
| Returns the node in the given array at the given index. More...
size_t | mpack_node_map_count (mpack_node_t node)
| Returns the number of key/value pairs in the given map node. More...
mpack_node_t | mpack_node_map_key_at (mpack_node_t node, size_t index)
| Returns the key node in the given map at the given index. More...
mpack_node_t | mpack_node_map_value_at (mpack_node_t node, size_t index)
| Returns the value node in the given map at the given index. More...
mpack_node_t | mpack_node_map_int (mpack_node_t node, int64_t num)
| Returns the value node in the given map for the given integer key. More...
mpack_node_t | mpack_node_map_int_optional (mpack_node_t node, int64_t num)
| Returns the value node in the given map for the given integer key, or a missing node if the map does not contain the given key. More...
mpack_node_t | mpack_node_map_uint (mpack_node_t node, uint64_t num)
| Returns the value node in the given map for the given unsigned integer key. More...
mpack_node_t | mpack_node_map_uint_optional (mpack_node_t node, uint64_t num)
| Returns the value node in the given map for the given unsigned integer key, or a missing node if the map does not contain the given key. More...
mpack_node_t | mpack_node_map_str (mpack_node_t node, const char *str, size_t length)
| Returns the value node in the given map for the given string key. More...
mpack_node_t | mpack_node_map_str_optional (mpack_node_t node, const char *str, size_t length)
| Returns the value node in the given map for the given string key, or a missing node if the map does not contain the given key. More...
mpack_node_t | mpack_node_map_cstr (mpack_node_t node, const char *cstr)
| Returns the value node in the given map for the given null-terminated string key. More...
mpack_node_t | mpack_node_map_cstr_optional (mpack_node_t node, const char *cstr)
| Returns the value node in the given map for the given null-terminated string key, or a missing node if the map does not contain the given key. More...
bool | mpack_node_map_contains_int (mpack_node_t node, int64_t num)
| Returns true if the given node map contains exactly one entry with the given integer key. More...
bool | mpack_node_map_contains_uint (mpack_node_t node, uint64_t num)
| Returns true if the given node map contains exactly one entry with the given unsigned integer key. More...
bool | mpack_node_map_contains_str (mpack_node_t node, const char *str, size_t length)
| Returns true if the given node map contains exactly one entry with the given string key. More...
bool | mpack_node_map_contains_cstr (mpack_node_t node, const char *cstr)
| Returns true if the given node map contains exactly one entry with the given null-terminated string key. More...

## Typedef Documentation

## mpack_node_data_t

typedef struct mpack_node_data_t mpack_node_data_t

The storage for nodes in an MPack tree.

You only need to use this if you intend to provide your own storage for nodes instead of letting the tree allocate it.

mpack_node_data_t is 16 bytes on most common architectures (32-bit and 64-bit.)

## mpack_node_t

typedef struct mpack_node_t mpack_node_t

A handle to node data in a parsed MPack tree.

Nodes represent either primitive values or compound types. If a node is a compound type, it contains a pointer to its child nodes, or a pointer to its underlying data.

Nodes are immutable.

Note
  mpack_node_t is an opaque reference to the node data, not the node data itself. (It contains pointers to both the node data and the tree.) It is passed by value in the Node API.

## mpack_tree_error_t

typedef void(* mpack_tree_error_t) (mpack_tree_t *tree, mpack_error_t error)

An error handler function to be called when an error is flagged on the tree.

The error handler will only be called once on the first error flagged; any subsequent node reads and errors are ignored, and the tree is permanently in that error state.

MPack is safe against non-local jumps out of error handler callbacks. This means you are allowed to longjmp or throw an exception (in C++, Objective-C, or with SEH) out of this callback.

Bear in mind when using longjmp that local non-volatile variables that have changed are undefined when setjmp() returns, so you can't put the tree on the stack in the same activation frame as the setjmp without declaring it volatile.

You must still eventually destroy the tree. It is not destroyed automatically when an error is flagged. It is safe to destroy the tree within this error callback, but you will either need to perform a non-local jump, or store something in your context to identify that the tree is destroyed since any future accesses to it cause undefined behavior.

## mpack_tree_read_t

typedef size_t(* mpack_tree_read_t) (mpack_tree_t *tree, char *buffer, size_t count)

The MPack tree's read function.

It should fill the buffer with as many bytes as are immediately available up to the given `count`, returning the number of bytes written to the buffer.

In case of error, it should flag an appropriate error on the reader (usually mpack_error_io.)

The blocking or non-blocking behaviour of the read should match whether you are using mpack_tree_parse() or mpack_tree_try_parse().

If you are using mpack_tree_parse(), the read should block until at least one byte is read. If you return 0, mpack_tree_parse() will raise mpack_error_io.

If you are using mpack_tree_try_parse(), the read function can always return 0, and must never block waiting for data (otherwise mpack_tree_try_parse() would be equivalent to mpack_tree_parse().) When you return 0, mpack_tree_try_parse() will return false without flagging an error.

## mpack_tree_t

typedef struct mpack_tree_t mpack_tree_t

An MPack tree parser to parse a blob or stream of MessagePack.

When a message is parsed, the tree contains a single root node which contains all parsed data. The tree and its nodes are immutable.

## mpack_tree_teardown_t

typedef void(* mpack_tree_teardown_t) (mpack_tree_t *tree)

A teardown function to be called when the tree is destroyed.

## Function Documentation

## mpack_node_array_at()

mpack_node_t mpack_node_array_at | ( | mpack_node_t | node,
|  | size_t | index
| ) |  |

Returns the node in the given array at the given index.

If the node is not an array, mpack_error_type is raised and a nil node is returned. If the given index is out of bounds, mpack_error_data is raised and a nil node is returned.

## mpack_node_array_length()

size_t mpack_node_array_length | ( | mpack_node_t | node | ) |

Returns the length of the given array node.

Raises mpack_error_type and returns 0 if the given node is not an array.

## mpack_node_bin_data()

const char * mpack_node_bin_data | ( | mpack_node_t | node | ) |

Returns a pointer to the data contained by this bin node.

The pointer is valid as long as the data backing the tree is valid.

If this node is not a bin, mpack_error_type is raised and `NULL` is returned.

## mpack_node_bin_size()

size_t mpack_node_bin_size | ( | mpack_node_t | node | ) |

Returns the number of bytes in the given bin node.

This returns zero if the tree is in an error state.

If this node is not a bin, mpack_error_type is raised and zero is returned.

## mpack_node_bool()

bool mpack_node_bool | ( | mpack_node_t | node | ) |

Returns the bool value of the node.

If this node is not of the correct type, false is returned and mpack_error_type is raised.

## mpack_node_check_utf8()

void mpack_node_check_utf8 | ( | mpack_node_t | node | ) |

Checks that the given node contains a valid UTF-8 string.

If the string is invalid, this flags an error, which would cause subsequent calls to mpack_node_str() to return NULL and mpack_node_strlen() to return zero. So you can check the node for error immediately after calling this, or you can call those functions to use the data anyway and check for errors later.

Exceptions

  mpack_error_type | If this node is not a string or does not contain valid UTF-8.

Parameters

  node | The string node to test

See also
  mpack_node_str()
  mpack_node_strlen()

## mpack_node_check_utf8_cstr()

void mpack_node_check_utf8_cstr | ( | mpack_node_t | node | ) |

Checks that the given node contains a valid UTF-8 string with no NUL bytes.

This does not check that the string has a null-terminator! It only checks whether the string could safely be represented as a C-string by appending a null-terminator. (If the string does already contain a null-terminator, this will flag an error.)

This is performed automatically by other UTF-8 cstr helper functions. Only call this if you will do something else with the data directly, but you still want to ensure it will be valid as a UTF-8 C-string.

Exceptions

  mpack_error_type | If this node is not a string, does not contain valid UTF-8, or contains a NUL byte.

Parameters

  node | The string node to test

See also
  mpack_node_str()
  mpack_node_strlen()
  mpack_node_copy_utf8_cstr()
  mpack_node_utf8_cstr_alloc()

## mpack_node_copy_cstr()

void mpack_node_copy_cstr | ( | mpack_node_t | node,
|  | char * | buffer,
|  | size_t | size
| ) |  |

Checks that the given node contains a string with no NUL bytes, copies the string into the given buffer, and adds a null terminator.

If this node is not of a string type, mpack_error_type is raised. If the string does not fit, mpack_error_data is raised.

If any error occurs, the buffer will contain an empty null-terminated string.

Parameters

  node | The string node from which to copy data
  buffer | A buffer in which to copy the node's string
  size | The size of the given buffer

## mpack_node_copy_data()

size_t mpack_node_copy_data | ( | mpack_node_t | node,
|  | char * | buffer,
|  | size_t | bufsize
| ) |  |

Copies the bytes contained by this node into the given buffer, returning the number of bytes in the node.

Exceptions

  mpack_error_type | If this node is not a str, bin or ext type
  mpack_error_too_big | If the string does not fit in the given buffer

Parameters

  node | The string node from which to copy data
  buffer | A buffer in which to copy the node's bytes
  bufsize | The size of the given buffer

Returns
  The number of bytes in the node, or zero if an error occurs.

## mpack_node_copy_utf8()

size_t mpack_node_copy_utf8 | ( | mpack_node_t | node,
|  | char * | buffer,
|  | size_t | bufsize
| ) |  |

Checks that the given node contains a valid UTF-8 string and copies the string into the given buffer, returning the number of bytes in the string.

Exceptions

  mpack_error_type | If this node is not a string
  mpack_error_too_big | If the string does not fit in the given buffer

Parameters

  node | The string node from which to copy data
  buffer | A buffer in which to copy the node's bytes
  bufsize | The size of the given buffer

Returns
  The number of bytes in the node, or zero if an error occurs.

## mpack_node_copy_utf8_cstr()

void mpack_node_copy_utf8_cstr | ( | mpack_node_t | node,
|  | char * | buffer,
|  | size_t | size
| ) |  |

Checks that the given node contains a valid UTF-8 string with no NUL bytes, copies the string into the given buffer, and adds a null terminator.

If this node is not of a string type, mpack_error_type is raised. If the string does not fit, mpack_error_data is raised.

If any error occurs, the buffer will contain an empty null-terminated string.

Parameters

  node | The string node from which to copy data
  buffer | A buffer in which to copy the node's string
  size | The size of the given buffer

## mpack_node_cstr_alloc()

char * mpack_node_cstr_alloc | ( | mpack_node_t | node,
|  | size_t | maxsize
| ) |  |

Allocates a new null-terminated string using MPACK_MALLOC() with the string contained by this node.

The allocated string must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.)

Exceptions

  mpack_error_type | If this node is not a string or contains NUL bytes
  mpack_error_too_big | If the size of the string plus null-terminator is larger than the given maximum size
  mpack_error_memory | If an allocation failure occurs

Parameters

  node | The node from which to allocate and copy string data
  maxsize | The maximum size to allocate, including the null-terminator

Returns
  The allocated string, or NULL if any error occurs.

## mpack_node_data()

const char * mpack_node_data | ( | mpack_node_t | node | ) |

Returns a pointer to the data contained by this node.

Note
  Strings are not null-terminated! Use one of the cstr functions to get a null-terminated string.

The pointer is valid as long as the data backing the tree is valid.

If this node is not of a str, bin or ext, mpack_error_type is raised, and `NULL` is returned.

See also
  mpack_node_copy_cstr()
  mpack_node_cstr_alloc()
  mpack_node_utf8_cstr_alloc()

## mpack_node_data_alloc()

char * mpack_node_data_alloc | ( | mpack_node_t | node,
|  | size_t | maxsize
| ) |  |

Allocates a new chunk of data using MPACK_MALLOC() with the bytes contained by this node.

The allocated data must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.)

Exceptions

  mpack_error_type | If this node is not a str, bin or ext type
  mpack_error_too_big | If the size of the data is larger than the given maximum size
  mpack_error_memory | If an allocation failure occurs

Parameters

  node | The node from which to allocate and copy data
  maxsize | The maximum size to allocate

Returns
  The allocated data, or NULL if any error occurs.

## mpack_node_data_len()

uint32_t mpack_node_data_len | ( | mpack_node_t | node | ) |

Returns the length of the given str, bin or ext node.

This returns zero if the tree is in an error state.

If this node is not a str, bin or ext, mpack_error_type is raised and zero is returned.

## mpack_node_double()

double mpack_node_double | ( | mpack_node_t | node | ) |

Returns the double value of the node.

The underlying value can be an integer, float or double; the value is converted to a double.

Note
  Reading a very large integer with this function can incur a loss of precision.

Exceptions

  mpack_error_type | if the underlying value is not a float, double or integer.

## mpack_node_double_strict()

double mpack_node_double_strict | ( | mpack_node_t | node | ) |

Returns the double value of the node.

The underlying value must be a float or double, not an integer. This ensures no loss of precision can occur.

Exceptions

  mpack_error_type | if the underlying value is not a float or double.

## mpack_node_enum()

size_t mpack_node_enum | ( | mpack_node_t | node,
|  | const char * | strings[],
|  | size_t | count
| ) |  |

Searches the given string array for a string matching the given node and returns its index.

If the node does not match any of the given strings, mpack_error_type is flagged. Use mpack_node_enum_optional() if you want to allow values other than the given strings.

If any error occurs or if the tree is in an error state, count is returned.

This can be used to quickly parse a string into an enum when the enum values range from 0 to count-1. If the last value in the enum is a special "count" value, it can be passed as the count, and the return value can be cast directly to the enum type.

typedef enum { APPLE , BANANA , ORANGE , COUNT} fruit_t;
const char* fruits[] = {"apple", "banana", "orange"};
fruit_t fruit = (fruit_t)mpack_node_enum(node, fruits, COUNT);
mpack_node_enum
size_t mpack_node_enum(mpack_node_t node, const char *strings[], size_t count)
Searches the given string array for a string matching the given node and returns its index.

Parameters

  node | The node
  strings | An array of expected strings of length count
  count | The number of strings

Returns
  The index of the matched string, or count in case of error

## mpack_node_enum_optional()

size_t mpack_node_enum_optional | ( | mpack_node_t | node,
|  | const char * | strings[],
|  | size_t | count
| ) |  |

Searches the given string array for a string matching the given node, returning its index or count if no strings match.

If the value is not a string, or it does not match any of the given strings, count is returned and no error is flagged.

If any error occurs or if the tree is in an error state, count is returned.

This can be used to quickly parse a string into an enum when the enum values range from 0 to count-1. If the last value in the enum is a special "count" value, it can be passed as the count, and the return value can be cast directly to the enum type.

typedef enum { APPLE , BANANA , ORANGE , COUNT} fruit_t;
const char* fruits[] = {"apple", "banana", "orange"};
fruit_t fruit = (fruit_t)mpack_node_enum_optional(node, fruits, COUNT);
mpack_node_enum_optional
size_t mpack_node_enum_optional(mpack_node_t node, const char *strings[], size_t count)
Searches the given string array for a string matching the given node, returning its index or count if...

Parameters

  node | The node
  strings | An array of expected strings of length count
  count | The number of strings

Returns
  The index of the matched string, or count in case of error

## mpack_node_error()

mpack_error_t mpack_node_error | ( | mpack_node_t | node | ) |

Returns the error state of the node's tree.

## mpack_node_exttype()

int8_t mpack_node_exttype | ( | mpack_node_t | node | ) |

Returns the extension type of the given ext node.

This returns zero if the tree is in an error state.

Note
  This requires MPACK_EXTENSIONS.

## mpack_node_false()

void mpack_node_false | ( | mpack_node_t | node | ) |

Checks if the given node is of bool type with value false, raising mpack_error_type otherwise.

## mpack_node_flag_error()

void mpack_node_flag_error | ( | mpack_node_t | node,
|  | mpack_error_t | error
| ) |  |

Places the node's tree in the given error state, calling the error callback if one is set.

This allows you to externally flag errors, for example if you are validating data as you read it.

If the tree is already in an error state, this call is ignored and no error callback is called.

## mpack_node_float()

float mpack_node_float | ( | mpack_node_t | node | ) |

Returns the float value of the node.

The underlying value can be an integer, float or double; the value is converted to a float.

Note
  Reading a double or a large integer with this function can incur a loss of precision.

Exceptions

  mpack_error_type | if the underlying value is not a float, double or integer.

## mpack_node_float_strict()

float mpack_node_float_strict | ( | mpack_node_t | node | ) |

Returns the float value of the node.

The underlying value must be a float, not a double or an integer. This ensures no loss of precision can occur.

Exceptions

  mpack_error_type | if the underlying value is not a float.

## mpack_node_i16()

int16_t mpack_node_i16 | ( | mpack_node_t | node | ) |

Returns the 16-bit signed value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_i32()

int32_t mpack_node_i32 | ( | mpack_node_t | node | ) |

Returns the 32-bit signed value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_i64()

int64_t mpack_node_i64 | ( | mpack_node_t | node | ) |

Returns the 64-bit signed value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_i8()

int8_t mpack_node_i8 | ( | mpack_node_t | node | ) |

Returns the 8-bit signed value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_int()

int mpack_node_int | ( | mpack_node_t | node | ) |

Returns the int value of the node.

Returns zero if an error occurs.

Exceptions

  mpack_error_type | If the node is not an integer type or does not fit in the range of an int

## mpack_node_is_missing()

bool mpack_node_is_missing | ( | mpack_node_t | node | ) |

Returns true if the given node handle indicates a missing node; false otherwise.

To ensure that a node is missing and flag an error otherwise, use mpack_node_missing().

## mpack_node_is_nil()

bool mpack_node_is_nil | ( | mpack_node_t | node | ) |

Returns true if the given node is a nil node; false otherwise.

To ensure that a node is nil and flag an error otherwise, use mpack_node_nil().

## mpack_node_map_contains_cstr()

bool mpack_node_map_contains_cstr | ( | mpack_node_t | node,
|  | const char * | cstr
| ) |  |

Returns true if the given node map contains exactly one entry with the given null-terminated string key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

## mpack_node_map_contains_int()

bool mpack_node_map_contains_int | ( | mpack_node_t | node,
|  | int64_t | num
| ) |  |

Returns true if the given node map contains exactly one entry with the given integer key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

## mpack_node_map_contains_str()

bool mpack_node_map_contains_str | ( | mpack_node_t | node,
|  | const char * | str,
|  | size_t | length
| ) |  |

Returns true if the given node map contains exactly one entry with the given string key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

## mpack_node_map_contains_uint()

bool mpack_node_map_contains_uint | ( | mpack_node_t | node,
|  | uint64_t | num
| ) |  |

Returns true if the given node map contains exactly one entry with the given unsigned integer key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

## mpack_node_map_count()

size_t mpack_node_map_count | ( | mpack_node_t | node | ) |

Returns the number of key/value pairs in the given map node.

Raises mpack_error_type and returns 0 if the given node is not a map.

## mpack_node_map_cstr()

mpack_node_t mpack_node_map_cstr | ( | mpack_node_t | node,
|  | const char * | cstr
| ) |  |

Returns the value node in the given map for the given null-terminated string key.

The key must exist within the map. Use mpack_node_map_cstr_optional() to check for optional keys.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node does not contain exactly one entry with the given key

Returns
  The value node for the given key, or a nil node in case of error

## mpack_node_map_cstr_optional()

mpack_node_t mpack_node_map_cstr_optional | ( | mpack_node_t | node,
|  | const char * | cstr
| ) |  |

Returns the value node in the given map for the given null-terminated string key, or a missing node if the map does not contain the given key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

Returns
  The value node for the given key, or a missing node if the key does not exist, or a nil node in case of error

See also
  mpack_node_is_missing()

## mpack_node_map_int()

mpack_node_t mpack_node_map_int | ( | mpack_node_t | node,
|  | int64_t | num
| ) |  |

Returns the value node in the given map for the given integer key.

The key must exist within the map. Use mpack_node_map_int_optional() to check for optional keys.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node does not contain exactly one entry with the given key

Returns
  The value node for the given key, or a nil node in case of error

## mpack_node_map_int_optional()

mpack_node_t mpack_node_map_int_optional | ( | mpack_node_t | node,
|  | int64_t | num
| ) |  |

Returns the value node in the given map for the given integer key, or a missing node if the map does not contain the given key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

Returns
  The value node for the given key, or a missing node if the key does not exist, or a nil node in case of error

See also
  mpack_node_is_missing()

## mpack_node_map_key_at()

mpack_node_t mpack_node_map_key_at | ( | mpack_node_t | node,
|  | size_t | index
| ) |  |

Returns the key node in the given map at the given index.

A nil node is returned in case of error.

Exceptions

  mpack_error_type | if the node is not a map
  mpack_error_data | if the given index is out of bounds

## mpack_node_map_str()

mpack_node_t mpack_node_map_str | ( | mpack_node_t | node,
|  | const char * | str,
|  | size_t | length
| ) |  |

Returns the value node in the given map for the given string key.

The key must exist within the map. Use mpack_node_map_str_optional() to check for optional keys.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node does not contain exactly one entry with the given key

Returns
  The value node for the given key, or a nil node in case of error

## mpack_node_map_str_optional()

mpack_node_t mpack_node_map_str_optional | ( | mpack_node_t | node,
|  | const char * | str,
|  | size_t | length
| ) |  |

Returns the value node in the given map for the given string key, or a missing node if the map does not contain the given key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

Returns
  The value node for the given key, or a missing node if the key does not exist, or a nil node in case of error

See also
  mpack_node_is_missing()

## mpack_node_map_uint()

mpack_node_t mpack_node_map_uint | ( | mpack_node_t | node,
|  | uint64_t | num
| ) |  |

Returns the value node in the given map for the given unsigned integer key.

The key must exist within the map. Use mpack_node_map_uint_optional() to check for optional keys.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node does not contain exactly one entry with the given key

Returns
  The value node for the given key, or a nil node in case of error

## mpack_node_map_uint_optional()

mpack_node_t mpack_node_map_uint_optional | ( | mpack_node_t | node,
|  | uint64_t | num
| ) |  |

Returns the value node in the given map for the given unsigned integer key, or a missing node if the map does not contain the given key.

The key must be unique. An error is flagged if the node has multiple entries with the given key.

Exceptions

  mpack_error_type | If the node is not a map
  mpack_error_data | If the node contains more than one entry with the given key

Returns
  The value node for the given key, or a missing node if the key does not exist, or a nil node in case of error

See also
  mpack_node_is_missing()

## mpack_node_map_value_at()

mpack_node_t mpack_node_map_value_at | ( | mpack_node_t | node,
|  | size_t | index
| ) |  |

Returns the value node in the given map at the given index.

A nil node is returned in case of error.

Exceptions

  mpack_error_type | if the node is not a map
  mpack_error_data | if the given index is out of bounds

## mpack_node_missing()

void mpack_node_missing | ( | mpack_node_t | node | ) |

Checks that the given node indicates a missing node, raising mpack_error_type otherwise.

Use mpack_node_is_missing() to return whether the node is missing.

## mpack_node_nil()

void mpack_node_nil | ( | mpack_node_t | node | ) |

Checks that the given node is of nil type, raising mpack_error_type otherwise.

Use mpack_node_is_nil() to return whether the node is nil.

## mpack_node_str()

const char * mpack_node_str | ( | mpack_node_t | node | ) |

Returns a pointer to the data contained by this node, ensuring the node is a string.

Warning
  Strings are not null-terminated! Use one of the cstr functions to get a null-terminated string.

The pointer is valid as long as the data backing the tree is valid.

If this node is not a string, mpack_error_type is raised and `NULL` is returned.

See also
  mpack_node_copy_cstr()
  mpack_node_cstr_alloc()
  mpack_node_utf8_cstr_alloc()

## mpack_node_strlen()

size_t mpack_node_strlen | ( | mpack_node_t | node | ) |

Returns the length in bytes of the given string node.

This does not include any null-terminator.

This returns zero if the tree is in an error state.

If this node is not a str, mpack_error_type is raised and zero is returned.

## mpack_node_tag()

mpack_tag_t mpack_node_tag | ( | mpack_node_t | node | ) |

Returns a tag describing the given node, or a nil tag if the tree is in an error state.

## mpack_node_timestamp()

mpack_timestamp_t mpack_node_timestamp | ( | mpack_node_t | node | ) |

Returns a timestamp.

Note
  This requires MPACK_EXTENSIONS.

Exceptions

  mpack_error_type | if the underlying value is not a timestamp.

## mpack_node_timestamp_nanoseconds()

uint32_t mpack_node_timestamp_nanoseconds | ( | mpack_node_t | node | ) |

Returns a timestamp's additional nanoseconds.

Note
  This requires MPACK_EXTENSIONS.

Returns
  A nanosecond count between 0 and 999,999,999 inclusive.

Exceptions

  mpack_error_type | if the underlying value is not a timestamp.

## mpack_node_timestamp_seconds()

int64_t mpack_node_timestamp_seconds | ( | mpack_node_t | node | ) |

Returns a timestamp's (signed) seconds since 1970-01-01T00:00:00Z.

Note
  This requires MPACK_EXTENSIONS.

Exceptions

  mpack_error_type | if the underlying value is not a timestamp.

## mpack_node_true()

void mpack_node_true | ( | mpack_node_t | node | ) |

Checks if the given node is of bool type with value true, raising mpack_error_type otherwise.

## mpack_node_type()

mpack_type_t mpack_node_type | ( | mpack_node_t | node | ) |

Returns the type of the node.

## mpack_node_u16()

uint16_t mpack_node_u16 | ( | mpack_node_t | node | ) |

Returns the 16-bit unsigned value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_u32()

uint32_t mpack_node_u32 | ( | mpack_node_t | node | ) |

Returns the 32-bit unsigned value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_u64()

uint64_t mpack_node_u64 | ( | mpack_node_t | node | ) |

Returns the 64-bit unsigned value of the node.

If this node is not of a compatible type, mpack_error_type is raised, and zero is returned.

## mpack_node_u8()

uint8_t mpack_node_u8 | ( | mpack_node_t | node | ) |

Returns the 8-bit unsigned value of the node.

If this node is not of a compatible type, mpack_error_type is raised and zero is returned.

## mpack_node_uint()

unsigned int mpack_node_uint | ( | mpack_node_t | node | ) |

Returns the unsigned int value of the node.

Returns zero if an error occurs.

Exceptions

  mpack_error_type | If the node is not an integer type or does not fit in the range of an unsigned int

## mpack_node_utf8_cstr_alloc()

char * mpack_node_utf8_cstr_alloc | ( | mpack_node_t | node,
|  | size_t | maxsize
| ) |  |

Allocates a new null-terminated string using MPACK_MALLOC() with the UTF-8 string contained by this node.

The allocated string must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.)

Exceptions

  mpack_error_type | If this node is not a string, is not valid UTF-8, or contains NUL bytes
  mpack_error_too_big | If the size of the string plus null-terminator is larger than the given maximum size
  mpack_error_memory | If an allocation failure occurs

Parameters

  node | The node from which to allocate and copy string data
  maxsize | The maximum size to allocate, including the null-terminator

Returns
  The allocated string, or NULL if any error occurs.

## mpack_tree_context()

void * mpack_tree_context | ( | mpack_tree_t * | tree | ) |

Returns the custom context for tree callbacks.

See also
  mpack_tree_set_context
  mpack_tree_init_stream

## mpack_tree_destroy()

mpack_error_t mpack_tree_destroy | ( | mpack_tree_t * | tree | ) |

Destroys the tree.

## mpack_tree_error()

mpack_error_t mpack_tree_error | ( | mpack_tree_t * | tree | ) |

Returns the error state of the tree.

## mpack_tree_flag_error()

void mpack_tree_flag_error | ( | mpack_tree_t * | tree,
|  | mpack_error_t | error
| ) |  |

Places the tree in the given error state, calling the error callback if one is set.

This allows you to externally flag errors, for example if you are validating data as you read it.

If the tree is already in an error state, this call is ignored and no error callback is called.

## mpack_tree_init()

void mpack_tree_init | ( | mpack_tree_t * | tree,
|  | const char * | data,
|  | size_t | length
| ) |  |

Deprecated.

Deprecated:
  Renamed to mpack_tree_init_data().

## mpack_tree_init_data()

void mpack_tree_init_data | ( | mpack_tree_t * | tree,
|  | const char * | data,
|  | size_t | length
| ) |  |

Initializes a tree parser with the given data.

Configure the tree if desired, then call mpack_tree_parse() to parse it. The tree will allocate pages of nodes as needed and will free them when destroyed.

The tree must be destroyed with mpack_tree_destroy().

Any string or blob data types reference the original data, so the given data pointer must remain valid until after the tree is destroyed.

## mpack_tree_init_error()

void mpack_tree_init_error | ( | mpack_tree_t * | tree,
|  | mpack_error_t | error
| ) |  |

Initializes an MPack tree directly into an error state.

Use this if you are writing a wrapper to another `mpack_tree_init*()` function which can fail its setup.

## mpack_tree_init_file()

void mpack_tree_init_file | ( | mpack_tree_t * | tree,
|  | const char * | filename,
|  | size_t | max_bytes
| ) |  |

Deprecated.

Deprecated:
  Renamed to mpack_tree_init_filename().

## mpack_tree_init_filename()

void mpack_tree_init_filename | ( | mpack_tree_t * | tree,
|  | const char * | filename,
|  | size_t | max_bytes
| ) |  |

Initializes a tree to parse the given file.

The tree must be destroyed with mpack_tree_destroy(), even if parsing fails.

The file is opened, loaded fully into memory, and closed before this call returns.

Parameters

  tree | The tree to initialize
  filename | The filename passed to fopen() to read the file
  max_bytes | The maximum size of file to load, or 0 for unlimited size.

## mpack_tree_init_pool()

void mpack_tree_init_pool | ( | mpack_tree_t * | tree,
|  | const char * | data,
|  | size_t | length,
|  | mpack_node_data_t * | node_pool,
|  | size_t | node_pool_count
| ) |  |

Initializes a tree parser with the given data, using the given node data pool to store the results.

Configure the tree if desired, then call mpack_tree_parse() to parse it.

If the data does not fit in the pool, mpack_error_too_big will be flagged on the tree.

The tree must be destroyed with mpack_tree_destroy(), even if parsing fails.

## mpack_tree_init_stdfile()

void mpack_tree_init_stdfile | ( | mpack_tree_t * | tree,
|  | FILE * | stdfile,
|  | size_t | max_bytes,
|  | bool | close_when_done
| ) |  |

Initializes a tree to parse the given libc FILE.

This can be used to read from stdin, or from a file opened separately.

The tree must be destroyed with mpack_tree_destroy(), even if parsing fails.

The FILE is fully loaded fully into memory (and closed if requested) before this call returns.

Parameters

  tree | The tree to initialize.
  stdfile | The FILE.
  max_bytes | The maximum size of file to load, or 0 for unlimited size.
  close_when_done | If true, fclose() will be called on the FILE when it is no longer needed. If false, the file will not be closed when reading is done.

Warning
  The tree will read all data in the FILE before parsing it. If this is used on stdin, the parser will block until it is closed, even if a complete message has been written to it!

## mpack_tree_init_stream()

void mpack_tree_init_stream | ( | mpack_tree_t * | tree,
|  | mpack_tree_read_t | read_fn,
|  | void * | context,
|  | size_t | max_message_size,
|  | size_t | max_message_nodes
| ) |  |

Initializes a tree parser from an unbounded stream, or a stream of unknown length.

The parser can be used to read a single message from a stream of unknown length, or multiple messages from an unbounded stream, allowing it to be used for RPC communication. Call mpack_tree_parse() to parse a message from a blocking stream, or mpack_tree_try_parse() for a non-blocking stream.

The stream will use a growable internal buffer to store the most recent message, as well as allocated pages of nodes for the parse tree.

Maximum allowances for message size and node count must be specified in this function (since the stream is unbounded.) They can be changed later with mpack_tree_set_limits().

Parameters

  tree | The tree parser
  read_fn | The read function
  context | The context for the read function
  max_message_size | The maximum size of a message in bytes
  max_message_nodes | The maximum number of nodes per message. See mpack_node_data_t for the size of nodes.

See also
  mpack_tree_read_t
  mpack_reader_context()

## mpack_tree_parse()

void mpack_tree_parse | ( | mpack_tree_t * | tree | ) |

Parses a MessagePack message into a tree of immutable nodes.

If successful, the root node will be available under mpack_tree_root(). If not, an appropriate error will be flagged.

This can be called repeatedly to parse a series of messages from a data source. When this is called, all previous nodes from this tree and their contents (including the root node) are invalidated.

If this is called with a stream (see mpack_tree_init_stream()), the stream must block until data is available. (Otherwise, if this is called on a non-blocking stream, parsing will fail with mpack_error_io when the fill function returns 0.)

There is no way to recover a tree in an error state. It must be destroyed.

## mpack_tree_root()

mpack_node_t mpack_tree_root | ( | mpack_tree_t * | tree | ) |

Returns the root node of the tree, if the tree is not in an error state.

Returns a nil node otherwise.

Warning
  You must call mpack_tree_parse() before calling this. If mpack_tree_parse() was never called, the tree will assert.

## mpack_tree_set_context()

void mpack_tree_set_context | ( | mpack_tree_t * | tree,
|  | void * | context
| ) |  |

Sets the custom pointer to pass to the tree callbacks, such as teardown.

Parameters

  tree | The MPack tree.
  context | User data to pass to the tree callbacks.

See also
  mpack_reader_context()

## mpack_tree_set_error_handler()

void mpack_tree_set_error_handler | ( | mpack_tree_t * | tree,
|  | mpack_tree_error_t | error_fn
| ) |  |

Sets the error function to call when an error is flagged on the tree.

This should normally be used with mpack_tree_set_context() to register a custom pointer to pass to the error function.

See the definition of mpack_tree_error_t for more information about what you can do from an error callback.

See also
  mpack_tree_error_t

Parameters

  tree | The MPack tree.
  error_fn | The function to call when an error is flagged on the tree.

## mpack_tree_set_limits()

void mpack_tree_set_limits | ( | mpack_tree_t * | tree,
|  | size_t | max_message_size,
|  | size_t | max_message_nodes
| ) |  |

Sets the maximum byte size and maximum number of nodes allowed per message.

The default is SIZE_MAX (no limit) unless mpack_tree_init_stream() is called (where maximums are required.)

If a pool of nodes is used, the node limit is the lesser of this limit and the pool size.

Parameters

  tree | The tree parser
  max_message_size | The maximum size of a message in bytes
  max_message_nodes | The maximum number of nodes per message. See mpack_node_data_t for the size of nodes.

## mpack_tree_set_teardown()

void mpack_tree_set_teardown | ( | mpack_tree_t * | tree,
|  | mpack_tree_teardown_t | teardown
| ) |  |

Sets the teardown function to call when the tree is destroyed.

This should normally be used with mpack_tree_set_context() to register a custom pointer to pass to the teardown function.

Parameters

  tree | The MPack tree.
  teardown | The function to call when the tree is destroyed.

## mpack_tree_size()

size_t mpack_tree_size | ( | mpack_tree_t * | tree | ) |

Returns the size in bytes of the current parsed message.

If there is something in the buffer after the MessagePack object, this can be used to find it.

This is zero if an error occurred during tree parsing (since the portion of the data that the first complete object occupies cannot be determined if the data is invalid or corrupted.)

## mpack_tree_try_parse()

bool mpack_tree_try_parse | ( | mpack_tree_t * | tree | ) |

Attempts to parse a MessagePack message from a non-blocking stream into a tree of immutable nodes.

A non-blocking read function must have been passed to the tree in mpack_tree_init_stream().

If this returns true, a message is available under mpack_tree_root(). The tree nodes and data will be valid until the next time a parse is started.

If this returns false, no message is available, because either not enough data is available yet or an error has occurred. You must check the tree for errors whenever this returns false. If there is no error, you should try again later when more data is available. (You will want to select()/poll() on the underlying socket or use some other asynchronous mechanism to determine when it has data.)

There is no way to recover a tree in an error state. It must be destroyed.

See also
  mpack_tree_init_stream()