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. More...

Typedefs
typedef struct mpack_node_t	mpack_node_t
	A handle to node data in a parsed MPack tree. More...

typedef struct mpack_node_data_t	mpack_node_data_t
	The storage for nodes in an MPack tree. 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_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 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...

MPACK_INLINE 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...

MPACK_INLINE 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_INLINE mpack_error_t	mpack_tree_error (mpack_tree_t *tree)
	Returns the error state of the tree. More...

MPACK_INLINE 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...

MPACK_INLINE 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...

MPACK_INLINE void *	mpack_tree_context (mpack_tree_t *tree)
	Returns the custom context for tree callbacks. More...

MPACK_INLINE 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...

MPACK_INLINE 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_INLINE 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...

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

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

Detailed 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 docs/node.md for examples.

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 map, 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 map, 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);

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

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_INLINE mpack_error_t mpack_node_error ( mpack_node_t node )

Returns the error state of the node's tree.

◆ 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_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()

MPACK_INLINE 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_INLINE 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()

MPACK_INLINE 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()

MPACK_INLINE 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()

MPACK_INLINE 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()

MPACK_INLINE 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()

MPACK_INLINE 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()

MPACK_INLINE 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()

Typedefs

Tree Initialization

Tree Functions

Node Core Functions

Node Primitive Value Functions

Node String and Data Functions

Compound Node Functions

Detailed Description

Typedef Documentation

◆ mpack_node_data_t

◆ mpack_node_t

◆ mpack_tree_error_t

◆ mpack_tree_read_t

◆ mpack_tree_t

◆ mpack_tree_teardown_t

Function Documentation

◆ mpack_node_array_at()

◆ mpack_node_array_length()

◆ mpack_node_bin_data()

◆ mpack_node_bin_size()

◆ mpack_node_bool()

◆ mpack_node_check_utf8()

◆ mpack_node_check_utf8_cstr()

◆ mpack_node_copy_cstr()

◆ mpack_node_copy_data()

◆ mpack_node_copy_utf8()

◆ mpack_node_copy_utf8_cstr()

◆ mpack_node_cstr_alloc()

◆ mpack_node_data()

◆ mpack_node_data_alloc()

◆ mpack_node_data_len()

◆ mpack_node_double()

◆ mpack_node_double_strict()

◆ mpack_node_enum()

◆ mpack_node_enum_optional()

◆ mpack_node_error()

◆ mpack_node_false()

◆ mpack_node_flag_error()

◆ mpack_node_float()

◆ mpack_node_float_strict()

◆ mpack_node_i16()

◆ mpack_node_i32()

◆ mpack_node_i64()

◆ mpack_node_i8()

◆ mpack_node_int()

◆ mpack_node_is_missing()

◆ mpack_node_is_nil()

◆ mpack_node_map_contains_cstr()

◆ mpack_node_map_contains_int()

◆ mpack_node_map_contains_str()

◆ mpack_node_map_contains_uint()

◆ mpack_node_map_count()

◆ mpack_node_map_cstr()

◆ mpack_node_map_cstr_optional()

◆ mpack_node_map_int()

◆ mpack_node_map_int_optional()

◆ mpack_node_map_key_at()

◆ mpack_node_map_str()

◆ mpack_node_map_str_optional()

◆ mpack_node_map_uint()

◆ mpack_node_map_uint_optional()

◆ mpack_node_map_value_at()

◆ mpack_node_missing()

◆ mpack_node_nil()

◆ mpack_node_str()

◆ mpack_node_strlen()

◆ mpack_node_tag()

◆ mpack_node_true()

◆ mpack_node_type()

◆ mpack_node_u16()

◆ mpack_node_u32()

◆ mpack_node_u64()

◆ mpack_node_u8()

◆ mpack_node_uint()

◆ mpack_node_utf8_cstr_alloc()

◆ mpack_tree_context()

◆ mpack_tree_destroy()

◆ mpack_tree_error()

◆ mpack_tree_flag_error()

◆ mpack_tree_init()