Description

The MPack Node API allows you to parse a chunk of MessagePack data in-place into a dynamically typed data structure.

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 struct mpack_tree_t	mpack_tree_t
	An MPack tree parsed from a blob 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 Functions
void	mpack_tree_init (mpack_tree_t tree, const char data, size_t length)
	Initializes a tree by parsing the given data buffer. 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 by parsing the given data buffer, 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_file (mpack_tree_t tree, const char filename, size_t max_bytes)
	Initializes a tree by reading and parsing the given file. 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 number of bytes used in the buffer when the tree was parsed. 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_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...

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

Node Core Functions
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...

void	mpack_node_print_file (mpack_node_t node, FILE *file)
	Converts a node to pseudo-JSON for debugging purposes and pretty-prints it to the given file. More...

void	mpack_node_print (mpack_node_t node)
	Converts a node to pseudo-JSON for debugging purposes and pretty-prints it to stdout. More...

Node Primitive Value Functions
mpack_type_t	mpack_node_type (mpack_node_t node)
	Returns the type of the node. More...

void	mpack_node_nil (mpack_node_t node)
	Checks if the given node is of nil type, 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...

int8_t	mpack_node_exttype (mpack_node_t node)
	Returns the extension type of the given ext 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 it is a string. More...

const char *	mpack_node_data (mpack_node_t node)
	Returns a pointer to the data contained by this 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_at (mpack_node_t node, size_t index, size_t offset)

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

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.

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 a handle, not the node data itself. It is passed by value in the Node API.

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.

typedef struct mpack_tree_t mpack_tree_t

An MPack tree parsed from a blob of MessagePack.

The tree contains a single root node which contains all parsed data. The tree and its nodes are immutable.

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

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.

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.

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

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

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

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.

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.

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

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.

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

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.

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.

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.

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.

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

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

Returns the error state of the node's tree.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

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

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_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_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 nil 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 nil node in case of error

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_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 nil 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 nil node in case of error

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_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_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 nil 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 nil node in case of error

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_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 nil 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 nil node in case of error

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

void mpack_node_nil ( mpack_node_t node )

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

void mpack_node_print ( mpack_node_t node )

Converts a node to pseudo-JSON for debugging purposes and pretty-prints it to stdout.

void mpack_node_print_file	(	mpack_node_t	node,
		FILE *	file
	)

Converts a node to pseudo-JSON for debugging purposes and pretty-prints it to the given file.

const char* mpack_node_str ( mpack_node_t node )

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

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

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.

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.

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_type_t mpack_node_type ( mpack_node_t node )

Returns the type of the node.

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.

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.

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.

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.

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

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_error_t mpack_tree_destroy ( mpack_tree_t * tree )

Destroys the tree.

mpack_error_t mpack_tree_error ( mpack_tree_t * tree )

Returns the error state of the tree.

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.

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

Initializes a tree by parsing the given data buffer.

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

The tree will allocate pages of nodes as needed, and free them when destroyed.

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

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 mpack_tree_init() which can fail its setup.

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

Initializes a tree by reading and parsing 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.

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 by parsing the given data buffer, using the given node data pool to store the results.

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

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.

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.

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.

size_t mpack_tree_size ( mpack_tree_t * tree )

Returns the number of bytes used in the buffer when the tree was parsed.

If there is something in the buffer after the MessagePack object (such as another 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.)

Description

Typedefs

Tree Functions

Node Core Functions

Node Primitive Value Functions

Node String and Data Functions

Compound Node Functions

Typedef Documentation

Function Documentation