The MPack Reader API contains functions for imperatively reading dynamically typed data from a MessagePack stream. More...

Macros
#define	MPACK_READER_MINIMUM_BUFFER_SIZE 32
	The minimum buffer size for a reader with a fill function. More...

Typedefs
typedef struct mpack_reader_t	mpack_reader_t
	A buffered MessagePack decoder. More...

typedef size_t(*	mpack_reader_fill_t) (mpack_reader_t reader, char buffer, size_t count)
	The MPack reader's fill function. More...

typedef void(*	mpack_reader_skip_t) (mpack_reader_t *reader, size_t count)
	The MPack reader's skip function. More...

typedef void(*	mpack_reader_error_t) (mpack_reader_t *reader, mpack_error_t error)
	An error handler function to be called when an error is flagged on the reader. More...

typedef void(*	mpack_reader_teardown_t) (mpack_reader_t *reader)
	A teardown function to be called when the reader is destroyed. More...

Lifecycle Functions
void	mpack_reader_init (mpack_reader_t reader, char buffer, size_t size, size_t count)
	Initializes an MPack reader with the given buffer. More...

void	mpack_reader_init_error (mpack_reader_t *reader, mpack_error_t error)
	Initializes an MPack reader directly into an error state. More...

void	mpack_reader_init_data (mpack_reader_t reader, const char data, size_t count)
	Initializes an MPack reader to parse a pre-loaded contiguous chunk of data. More...

void	mpack_reader_init_filename (mpack_reader_t reader, const char filename)
	Initializes an MPack reader that reads from a file. More...

MPACK_INLINE void	mpack_reader_init_file (mpack_reader_t reader, const char filename)
	Deprecated. More...

void	mpack_reader_init_stdfile (mpack_reader_t reader, FILE stdfile, bool close_when_done)
	Initializes an MPack reader that reads from a libc FILE. More...

mpack_error_t	mpack_reader_destroy (mpack_reader_t *reader)
	Cleans up the MPack reader, ensuring that all compound elements have been completely read. More...

void	mpack_writer_init (mpack_writer_t writer, char buffer, size_t size)
	Initializes an MPack writer with the given buffer. More...

void	mpack_writer_init_growable (mpack_writer_t writer, char data, size_t size)
	Initializes an MPack writer using a growable buffer. More...

void	mpack_writer_init_error (mpack_writer_t *writer, mpack_error_t error)
	Initializes an MPack writer directly into an error state. More...

void	mpack_writer_init_filename (mpack_writer_t writer, const char filename)
	Initializes an MPack writer that writes to a file. More...

MPACK_INLINE void	mpack_writer_init_file (mpack_writer_t writer, const char filename)
	Deprecated. More...

void	mpack_writer_init_stdfile (mpack_writer_t writer, FILE stdfile, bool close_when_done)
	Initializes an MPack writer that writes to a libc FILE. More...

mpack_error_t	mpack_writer_destroy (mpack_writer_t *writer)
	Cleans up the MPack writer, flushing and closing the underlying stream, if any. More...

#define	mpack_reader_init_stack(reader)
	Initializes an MPack reader using stack space as a buffer. More...

Callbacks
MPACK_INLINE void	mpack_reader_set_context (mpack_reader_t reader, void context)
	Sets the custom pointer to pass to the reader callbacks, such as fill or teardown. More...

MPACK_INLINE void *	mpack_reader_context (mpack_reader_t *reader)
	Returns the custom context for reader callbacks. More...

void	mpack_reader_set_fill (mpack_reader_t *reader, mpack_reader_fill_t fill)
	Sets the fill function to refill the data buffer when it runs out of data. More...

void	mpack_reader_set_skip (mpack_reader_t *reader, mpack_reader_skip_t skip)
	Sets the skip function to discard bytes from the source stream. More...

MPACK_INLINE void	mpack_reader_set_error_handler (mpack_reader_t *reader, mpack_reader_error_t error_fn)
	Sets the error function to call when an error is flagged on the reader. More...

MPACK_INLINE void	mpack_reader_set_teardown (mpack_reader_t *reader, mpack_reader_teardown_t teardown)
	Sets the teardown function to call when the reader is destroyed. More...

Core Reader Functions
MPACK_INLINE mpack_error_t	mpack_reader_error (mpack_reader_t *reader)
	Queries the error state of the MPack reader. More...

void	mpack_reader_flag_error (mpack_reader_t *reader, mpack_error_t error)
	Places the reader in the given error state, calling the error callback if one is set. More...

MPACK_INLINE mpack_error_t	mpack_reader_flag_if_error (mpack_reader_t *reader, mpack_error_t error)
	Places the reader in the given error state if the given error is not mpack_ok, returning the resulting error state of the reader. More...

size_t	mpack_reader_remaining (mpack_reader_t reader, const char *data)
	Returns bytes left in the reader's buffer. More...

mpack_tag_t	mpack_read_tag (mpack_reader_t *reader)
	Reads a MessagePack object header (an MPack tag.) More...

mpack_tag_t	mpack_peek_tag (mpack_reader_t *reader)
	Parses the next MessagePack object header (an MPack tag) without advancing the reader. More...

MPACK_INLINE void	mpack_done_type (mpack_reader_t *reader, mpack_type_t type)

MPACK_INLINE void	mpack_done_array (mpack_reader_t *reader)
	Finishes reading an array. More...

MPACK_INLINE void	mpack_done_map (mpack_reader_t *reader)
	Finishes reading a map. More...

MPACK_INLINE void	mpack_done_str (mpack_reader_t *reader)
	Finishes reading a string. More...

MPACK_INLINE void	mpack_done_bin (mpack_reader_t *reader)
	Finishes reading a binary data blob. More...

void	mpack_discard (mpack_reader_t *reader)
	Reads and discards the next object. More...

String and Data Functions
void	mpack_skip_bytes (mpack_reader_t *reader, size_t count)
	Skips bytes from the underlying stream. More...

void	mpack_read_bytes (mpack_reader_t reader, char p, size_t count)
	Reads bytes from a string, binary blob or extension object, copying them into the given buffer. More...

void	mpack_read_utf8 (mpack_reader_t reader, char p, size_t byte_count)
	Reads bytes from a string, ensures that the string is valid UTF-8, and copies the bytes into the given buffer. More...

void	mpack_read_cstr (mpack_reader_t reader, char buf, size_t buffer_size, size_t byte_count)
	Reads bytes from a string, ensures that the string contains no NUL bytes, copies the bytes into the given buffer and adds a null-terminator. More...

void	mpack_read_utf8_cstr (mpack_reader_t reader, char buf, size_t buffer_size, size_t byte_count)
	Reads bytes from a string, ensures that the string is valid UTF-8 with no NUL bytes, copies the bytes into the given buffer and adds a null-terminator. More...

MPACK_INLINE char *	mpack_read_bytes_alloc (mpack_reader_t *reader, size_t count)
	Reads bytes from a string, binary blob or extension object, allocating storage for them and returning the allocated pointer. More...

const char *	mpack_read_bytes_inplace (mpack_reader_t *reader, size_t count)
	Reads bytes from a string, binary blob or extension object in-place in the buffer. More...

const char *	mpack_read_utf8_inplace (mpack_reader_t *reader, size_t count)
	Reads bytes from a string in-place in the buffer and ensures they are valid UTF-8. More...

MPACK_INLINE bool	mpack_should_read_bytes_inplace (mpack_reader_t *reader, size_t count)
	Returns true if it's a good idea to read the given number of bytes in-place. More...

Detailed Description

The MPack Reader API contains functions for imperatively reading dynamically typed data from a MessagePack stream.

See docs/reader.md for examples.

Note: If you are not writing code for an embedded device (or otherwise do not need maximum performance with minimal memory usage), you should not use this. You probably want to use the Node API instead.

This forms the basis of the Expect API, which can be used to interpret the stream of elements in expected types and value ranges.

Macro Definition Documentation

◆ mpack_reader_init_stack

#define mpack_reader_init_stack ( reader )

Initializes an MPack reader using stack space as a buffer.

A fill function should be added to the reader to fill the buffer.

See also: mpack_reader_set_fill

◆ MPACK_READER_MINIMUM_BUFFER_SIZE

#define MPACK_READER_MINIMUM_BUFFER_SIZE 32

The minimum buffer size for a reader with a fill function.

Typedef Documentation

◆ mpack_reader_error_t

typedef void(* mpack_reader_error_t) (mpack_reader_t *reader, mpack_error_t error)

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

The error handler will only be called once on the first error flagged; any subsequent reads and errors are ignored, and the reader 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 reader on the stack in the same activation frame as the setjmp without declaring it volatile.

You must still eventually destroy the reader. It is not destroyed automatically when an error is flagged. It is safe to destroy the reader 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 reader is destroyed since any future accesses to it cause undefined behavior.

◆ mpack_reader_fill_t

typedef size_t(* mpack_reader_fill_t) (mpack_reader_t *reader, char *buffer, size_t count)

The MPack reader's fill function.

It should fill the buffer with at least one byte and at most 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), or simply return zero. If zero is returned, mpack_error_io is raised.

Note: When reading from a stream, you should only copy and return the bytes that are immediately available. It is always safe to return less than the requested count as long as some non-zero number of bytes are read; if more bytes are needed, the read function will simply be called again.

See also: mpack_reader_context()

◆ mpack_reader_skip_t

typedef void(* mpack_reader_skip_t) (mpack_reader_t *reader, size_t count)

The MPack reader's skip function.

It should discard the given number of bytes from the source (for example by seeking forward.)

In case of error, it should flag an appropriate error on the reader.

See also: mpack_reader_context()

◆ mpack_reader_t

typedef struct mpack_reader_t mpack_reader_t

A buffered MessagePack decoder.

The decoder wraps an existing buffer and, optionally, a fill function. This allows efficiently decoding data from existing memory buffers, files, streams, etc.

All read operations are synchronous; they will block until the requested data is fully read, or an error occurs.

This structure is opaque; its fields should not be accessed outside of MPack.

◆ mpack_reader_teardown_t

typedef void(* mpack_reader_teardown_t) (mpack_reader_t *reader)

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

Function Documentation

◆ mpack_discard()

void mpack_discard ( mpack_reader_t * reader )

Reads and discards the next object.

This will read and discard all contained data as well if it is a compound type.

◆ mpack_done_array()

MPACK_INLINE void mpack_done_array ( mpack_reader_t * reader )

Finishes reading an array.

This will track reads to ensure that the correct number of elements are read.

◆ mpack_done_bin()

mpack_done_bin ( mpack_reader_t * reader )

Finishes reading a binary data blob.

This will track reads to ensure that the correct number of bytes are read.

◆ mpack_done_map()

mpack_done_map ( mpack_reader_t * reader )

Finishes reading a map.

This will track reads to ensure that the correct number of elements are read.

◆ mpack_done_str()

mpack_done_str ( mpack_reader_t * reader )

Finishes reading a string.

This will track reads to ensure that the correct number of bytes are read.

◆ mpack_done_type()

MPACK_INLINE void mpack_done_type	(	mpack_reader_t *	reader,
		mpack_type_t	type
	)

◆ mpack_peek_tag()

mpack_tag_t mpack_peek_tag ( mpack_reader_t * reader )

Parses the next MessagePack object header (an MPack tag) without advancing the reader.

If an error occurs, the reader is placed in an error state and a nil tag is returned. If the reader is already in an error state, a nil tag is returned.

Note: Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.

See also: mpack_read_tag(); mpack_discard()

◆ mpack_read_bytes()

void mpack_read_bytes	(	mpack_reader_t *	reader,
		char *	p,
		size_t	count
	)

Reads bytes from a string, binary blob or extension object, copying them into the given buffer.

A str, bin or ext must have been opened by a call to mpack_read_tag() which yielded one of these types, or by a call to an expect function such as mpack_expect_str() or mpack_expect_bin().

If an error occurs, the buffer contents are undefined.

This can be called multiple times for a single str, bin or ext to read the data in chunks. The total data read must add up to the size of the object.

Parameters

reader	The MPack reader
p	The buffer in which to copy the bytes
count	The number of bytes to read

◆ mpack_read_bytes_alloc()

MPACK_INLINE char * mpack_read_bytes_alloc	(	mpack_reader_t *	reader,
		size_t	count
	)

Reads bytes from a string, binary blob or extension object, allocating storage for them and returning the allocated pointer.

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

Returns NULL if any error occurs, or if count is zero.

◆ mpack_read_bytes_inplace()

const char * mpack_read_bytes_inplace	(	mpack_reader_t *	reader,
		size_t	count
	)

Reads bytes from a string, binary blob or extension object in-place in the buffer.

This can be used to avoid copying the data.

A str, bin or ext must have been opened by a call to mpack_read_tag() which yielded one of these types, or by a call to an expect function such as mpack_expect_str() or mpack_expect_bin().

If the bytes are from a string, the string is not null-terminated! Use mpack_read_cstr() to copy the string into a buffer and add a null-terminator.

The returned pointer is invalidated on the next read, or when the buffer is destroyed.

The reader will move data around in the buffer if needed to ensure that the pointer can always be returned, so this should only be used if count is very small compared to the buffer size. If you need to check whether a small size is reasonable (for example you intend to handle small and large sizes differently), you can call mpack_should_read_bytes_inplace().

This can be called multiple times for a single str, bin or ext to read the data in chunks. The total data read must add up to the size of the object.

NULL is returned if the reader is in an error state.

Exceptions

mpack_error_too_big if the requested size is larger than the buffer size

See also: mpack_should_read_bytes_inplace()

◆ mpack_read_cstr()

void mpack_read_cstr	(	mpack_reader_t *	reader,
		char *	buf,
		size_t	buffer_size,
		size_t	byte_count
	)

Reads bytes from a string, ensures that the string contains no NUL bytes, copies the bytes into the given buffer and adds a null-terminator.

A string must have been opened by a call to mpack_read_tag() which yielded a string, or by a call to an expect function such as mpack_expect_str().

The given byte count must match the size of the string as returned by the tag or expect function. The string will only be copied if the buffer is large enough to store it.

If an error occurs, the buffer will contain an empty string.

Note: If you know the object will be a string before reading it, it is highly recommended to use mpack_expect_cstr() instead. Alternatively you could use mpack_peek_tag() and call mpack_expect_cstr() if it's a string.

Exceptions

mpack_error_too_big	if the string plus null-terminator is larger than the given buffer size
mpack_error_type	if the string contains a null byte.

See also: mpack_peek_tag(); mpack_expect_cstr(); mpack_expect_utf8_cstr()

◆ mpack_read_tag()

mpack_tag_t mpack_read_tag ( mpack_reader_t * reader )

Reads a MessagePack object header (an MPack tag.)

If an error occurs, the reader is placed in an error state and a nil tag is returned. If the reader is already in an error state, a nil tag is returned.

If the type is compound (i.e. is a map, array, string, binary or extension type), additional reads are required to get the contained data, and the corresponding done function must be called when done.

Note: Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.

See also: mpack_read_bytes(); mpack_done_array(); mpack_done_map(); mpack_done_str(); mpack_done_bin(); mpack_done_ext()

◆ mpack_read_utf8()

void mpack_read_utf8	(	mpack_reader_t *	reader,
		char *	p,
		size_t	byte_count
	)

Reads bytes from a string, ensures that the string is valid UTF-8, and copies the bytes into the given buffer.

A string must have been opened by a call to mpack_read_tag() which yielded a string, or by a call to an expect function such as mpack_expect_str().

The given byte count must match the complete size of the string as returned by the tag or expect function. You must ensure that the buffer fits the data.

This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or WTF-8. Only pure UTF-8 is allowed.

If an error occurs, the buffer contents are undefined.

Unlike mpack_read_bytes(), this cannot be used to read the data in chunks (since this might split a character's UTF-8 bytes, and the reader does not keep track of the UTF-8 decoding state between reads.)

Exceptions

mpack_error_type if the string contains invalid UTF-8.

◆ mpack_read_utf8_cstr()

void mpack_read_utf8_cstr	(	mpack_reader_t *	reader,
		char *	buf,
		size_t	buffer_size,
		size_t	byte_count
	)

Reads bytes from a string, ensures that the string is valid UTF-8 with no NUL bytes, copies the bytes into the given buffer and adds a null-terminator.

A string must have been opened by a call to mpack_read_tag() which yielded a string, or by a call to an expect function such as mpack_expect_str().

The given byte count must match the size of the string as returned by the tag or expect function. The string will only be copied if the buffer is large enough to store it.

This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or WTF-8. Only pure UTF-8 is allowed, but without the NUL character, since it cannot be represented in a null-terminated string.

If an error occurs, the buffer will contain an empty string.

Note: If you know the object will be a string before reading it, it is highly recommended to use mpack_expect_utf8_cstr() instead. Alternatively you could use mpack_peek_tag() and call mpack_expect_utf8_cstr() if it's a string.

Exceptions

mpack_error_too_big	if the string plus null-terminator is larger than the given buffer size
mpack_error_type	if the string contains invalid UTF-8 or a null byte.

See also: mpack_peek_tag(); mpack_expect_utf8_cstr()

◆ mpack_read_utf8_inplace()

const char * mpack_read_utf8_inplace	(	mpack_reader_t *	reader,
		size_t	count
	)

Reads bytes from a string in-place in the buffer and ensures they are valid UTF-8.

This can be used to avoid copying the data.

A string must have been opened by a call to mpack_read_tag() which yielded a string, or by a call to an expect function such as mpack_expect_str().

The string is not null-terminated! Use mpack_read_utf8_cstr() to copy the string into a buffer and add a null-terminator.

The returned pointer is invalidated on the next read, or when the buffer is destroyed.

The reader will move data around in the buffer if needed to ensure that the pointer can always be returned, so this should only be used if count is very small compared to the buffer size. If you need to check whether a small size is reasonable (for example you intend to handle small and large sizes differently), you can call mpack_should_read_bytes_inplace().

This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or WTF-8. Only pure UTF-8 is allowed.

Unlike mpack_read_bytes_inplace(), this cannot be used to read the data in chunks (since this might split a character's UTF-8 bytes, and the reader does not keep track of the UTF-8 decoding state between reads.)

NULL is returned if the reader is in an error state.

Exceptions

mpack_error_type	if the string contains invalid UTF-8
mpack_error_too_big	if the requested size is larger than the buffer size

See also: mpack_should_read_bytes_inplace()

◆ mpack_reader_context()

MPACK_INLINE void * mpack_reader_context ( mpack_reader_t * reader )

Returns the custom context for reader callbacks.

See also: mpack_reader_set_context; mpack_reader_set_fill; mpack_reader_set_skip

◆ mpack_reader_destroy()

mpack_error_t mpack_reader_destroy ( mpack_reader_t * reader )

Cleans up the MPack reader, ensuring that all compound elements have been completely read.

Returns the final error state of the reader.

This will assert in tracking mode if the reader is not in an error state and has any incomplete reads. If you want to cancel reading in the middle of a document, you need to flag an error on the reader before destroying it (such as mpack_error_data).

See also: mpack_read_tag(); mpack_reader_flag_error(); mpack_error_data

◆ mpack_reader_error()

MPACK_INLINE mpack_error_t mpack_reader_error ( mpack_reader_t * reader )

Queries the error state of the MPack reader.

If a reader is in an error state, you should discard all data since the last time the error flag was checked. The error flag cannot be cleared.

◆ mpack_reader_flag_error()

void mpack_reader_flag_error	(	mpack_reader_t *	reader,
		mpack_error_t	error
	)

Places the reader 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 reader is already in an error state, this call is ignored and no error callback is called.

◆ mpack_reader_flag_if_error()

MPACK_INLINE mpack_error_t mpack_reader_flag_if_error	(	mpack_reader_t *	reader,
		mpack_error_t	error
	)

Places the reader in the given error state if the given error is not mpack_ok, returning the resulting error state of the reader.

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

If the given error is mpack_ok or if the reader is already in an error state, this call is ignored and the actual error state of the reader is returned.

◆ mpack_reader_init()

void mpack_reader_init	(	mpack_reader_t *	reader,
		char *	buffer,
		size_t	size,
		size_t	count
	)

Initializes an MPack reader with the given buffer.

The reader does not assume ownership of the buffer, but the buffer must be writeable if a fill function will be used to refill it.

Parameters

reader	The MPack reader.
buffer	The buffer with which to read MessagePack data.
size	The size of the buffer.
count	The number of bytes already in the buffer.

◆ mpack_reader_init_data()

void mpack_reader_init_data	(	mpack_reader_t *	reader,
		const char *	data,
		size_t	count
	)

Initializes an MPack reader to parse a pre-loaded contiguous chunk of data.

The reader does not assume ownership of the data.

Parameters

reader	The MPack reader.
data	The data to parse.
count	The number of bytes pointed to by data.

◆ mpack_reader_init_error()

void mpack_reader_init_error	(	mpack_reader_t *	reader,
		mpack_error_t	error
	)

Initializes an MPack reader directly into an error state.

Use this if you are writing a wrapper to mpack_reader_init() which can fail its setup.

◆ mpack_reader_init_file()

MPACK_INLINE void mpack_reader_init_file	(	mpack_reader_t *	reader,
		const char *	filename
	)

Deprecated.

Deprecated:: Renamed to mpack_reader_init_filename().

◆ mpack_reader_init_filename()

void mpack_reader_init_filename	(	mpack_reader_t *	reader,
		const char *	filename
	)

Initializes an MPack reader that reads from a file.

The file will be automatically opened and closed by the reader.

◆ mpack_reader_init_stdfile()

void mpack_reader_init_stdfile	(	mpack_reader_t *	reader,
		FILE *	stdfile,
		bool	close_when_done
	)

Initializes an MPack reader that reads from a libc FILE.

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

Parameters

reader	The MPack reader.
stdfile	The FILE.
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 reader is buffered. It will read data in advance of parsing it, and it may read more data than it parsed. See mpack_reader_remaining() to access the extra data.

◆ mpack_reader_remaining()

size_t mpack_reader_remaining	(	mpack_reader_t *	reader,
		const char **	data
	)

Returns bytes left in the reader's buffer.

If you are done reading MessagePack data but there is other interesting data following it, the reader may have buffered too much data. The number of bytes remaining in the buffer and a pointer to the position of those bytes can be queried here.

If you know the length of the MPack chunk beforehand, it's better to instead have your fill function limit the data it reads so that the reader does not have extra data. In this case you can simply check that this returns zero.

Returns 0 if the reader is in an error state.

Parameters

reader	The MPack reader from which to query remaining data.
data	[out] A pointer to the remaining data, or NULL.

Returns: The number of bytes remaining in the buffer.

◆ mpack_reader_set_context()

MPACK_INLINE void mpack_reader_set_context	(	mpack_reader_t *	reader,
		void *	context
	)

Sets the custom pointer to pass to the reader callbacks, such as fill or teardown.

Parameters

reader	The MPack reader.
context	User data to pass to the reader callbacks.

See also: mpack_reader_context()

◆ mpack_reader_set_error_handler()

MPACK_INLINE void mpack_reader_set_error_handler	(	mpack_reader_t *	reader,
		mpack_reader_error_t	error_fn
	)

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

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

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

See also: mpack_reader_error_t

Parameters

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

◆ mpack_reader_set_fill()

void mpack_reader_set_fill	(	mpack_reader_t *	reader,
		mpack_reader_fill_t	fill
	)

Sets the fill function to refill the data buffer when it runs out of data.

If no fill function is used, truncated MessagePack data results in mpack_error_invalid (since the buffer is assumed to contain a complete MessagePack object.)

If a fill function is used, truncated MessagePack data usually results in mpack_error_io (since the fill function fails to get the missing data.)

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

Parameters

reader	The MPack reader.
fill	The function to fetch additional data into the buffer.

◆ mpack_reader_set_skip()

void mpack_reader_set_skip	(	mpack_reader_t *	reader,
		mpack_reader_skip_t	skip
	)

Sets the skip function to discard bytes from the source stream.

It's not necessary to implement this function. If the stream is not seekable, don't set a skip callback. The reader will fall back to using the fill function instead.

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

The skip function is ignored in size-optimized builds to reduce code size. Data will be skipped with the fill function when necessary.

Parameters

reader	The MPack reader.
skip	The function to discard bytes from the source stream.

◆ mpack_reader_set_teardown()

MPACK_INLINE void mpack_reader_set_teardown	(	mpack_reader_t *	reader,
		mpack_reader_teardown_t	teardown
	)

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

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

Parameters

reader	The MPack reader.
teardown	The function to call when the reader is destroyed.

◆ mpack_should_read_bytes_inplace()

MPACK_INLINE bool mpack_should_read_bytes_inplace	(	mpack_reader_t *	reader,
		size_t	count
	)

Returns true if it's a good idea to read the given number of bytes in-place.

If the read will be larger than some small fraction of the buffer size, this will return false to avoid shuffling too much data back and forth in the buffer.

Use this if you're expecting arbitrary size data, and you want to read in-place for the best performance when possible but will fall back to a normal read if the data is too large.

See also: mpack_read_bytes_inplace()

◆ mpack_skip_bytes()

void mpack_skip_bytes	(	mpack_reader_t *	reader,
		size_t	count
	)

Skips bytes from the underlying stream.

This is used only to skip the contents of a string, binary blob or extension object.

◆ mpack_writer_destroy()

mpack_error_t mpack_writer_destroy ( mpack_writer_t * writer )

Cleans up the MPack writer, flushing and closing the underlying stream, if any.

Returns the final error state of the writer.

No flushing is performed if the writer is in an error state. The attached teardown function is called whether or not the writer is in an error state.

This will assert in tracking mode if the writer is not in an error state and has any unclosed compound types. If you want to cancel writing in the middle of a document, you need to flag an error on the writer before destroying it (such as mpack_error_data).

Note that a writer may raise an error and call your error handler during the final flush. It is safe to longjmp or throw out of this error handler, but if you do, the writer will not be destroyed, and the teardown function will not be called. You can still get the writer's error state, and you must call mpack_writer_destroy() again. (The second call is guaranteed not to call your error handler again since the writer is already in an error state.)

See also: mpack_writer_set_error_handler; mpack_writer_set_flush; mpack_writer_set_teardown; mpack_writer_flag_error; mpack_error_data

◆ mpack_writer_init()

void mpack_writer_init	(	mpack_writer_t *	writer,
		char *	buffer,
		size_t	size
	)

Initializes an MPack writer with the given buffer.

The writer does not assume ownership of the buffer.

Trying to write past the end of the buffer will result in mpack_error_too_big unless a flush function is set with mpack_writer_set_flush(). To use the data without flushing, call mpack_writer_buffer_used() to determine the number of bytes written.

Parameters

writer	The MPack writer.
buffer	The buffer into which to write MessagePack data.
size	The size of the buffer.

◆ mpack_writer_init_error()

void mpack_writer_init_error	(	mpack_writer_t *	writer,
		mpack_error_t	error
	)

Initializes an MPack writer directly into an error state.

Use this if you are writing a wrapper to mpack_writer_init() which can fail its setup.

◆ mpack_writer_init_file()

MPACK_INLINE void mpack_writer_init_file	(	mpack_writer_t *	writer,
		const char *	filename
	)

Deprecated.

Deprecated:: Renamed to mpack_writer_init_filename().

◆ mpack_writer_init_filename()

void mpack_writer_init_filename	(	mpack_writer_t *	writer,
		const char *	filename
	)

Initializes an MPack writer that writes to a file.

Exceptions

mpack_error_memory	if allocation fails
mpack_error_io	if the file cannot be opened

◆ mpack_writer_init_growable()

void mpack_writer_init_growable	(	mpack_writer_t *	writer,
		char **	data,
		size_t *	size
	)

Initializes an MPack writer using a growable buffer.

The data is placed in the given data pointer if and when the writer is destroyed without error. The data pointer is NULL during writing, and will remain NULL if an error occurs.

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

Exceptions

mpack_error_memory if the buffer fails to grow when flushing.

Parameters

writer	The MPack writer.
data	Where to place the allocated data.
size	Where to write the size of the data.

◆ mpack_writer_init_stdfile()

void mpack_writer_init_stdfile	(	mpack_writer_t *	writer,
		FILE *	stdfile,
		bool	close_when_done
	)

Initializes an MPack writer that writes to a libc FILE.

This can be used to write to stdout or stderr, or to a file opened separately.

Parameters

writer	The MPack writer.
stdfile	The FILE.
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 flushed or closed when writing is done.

Note: The writer is buffered. If you want to write other data to the FILE in between messages, you must flush it first.

See also: mpack_writer_flush_message

Macros

Typedefs

Lifecycle Functions

Callbacks

Core Reader Functions

String and Data Functions

Detailed Description

Macro Definition Documentation

◆ mpack_reader_init_stack

◆ MPACK_READER_MINIMUM_BUFFER_SIZE

Typedef Documentation

◆ mpack_reader_error_t

◆ mpack_reader_fill_t

◆ mpack_reader_skip_t

◆ mpack_reader_t

◆ mpack_reader_teardown_t

Function Documentation

◆ mpack_discard()

◆ mpack_done_array()

◆ mpack_done_bin()

◆ mpack_done_map()

◆ mpack_done_str()

◆ mpack_done_type()

◆ mpack_peek_tag()

◆ mpack_read_bytes()

◆ mpack_read_bytes_alloc()

◆ mpack_read_bytes_inplace()

◆ mpack_read_cstr()

◆ mpack_read_tag()

◆ mpack_read_utf8()

◆ mpack_read_utf8_cstr()

◆ mpack_read_utf8_inplace()

◆ mpack_reader_context()

◆ mpack_reader_destroy()

◆ mpack_reader_error()

◆ mpack_reader_flag_error()

◆ mpack_reader_flag_if_error()

◆ mpack_reader_init()

◆ mpack_reader_init_data()

◆ mpack_reader_init_error()

◆ mpack_reader_init_file()

◆ mpack_reader_init_filename()

◆ mpack_reader_init_stdfile()

◆ mpack_reader_remaining()

◆ mpack_reader_set_context()

◆ mpack_reader_set_error_handler()

◆ mpack_reader_set_fill()

◆ mpack_reader_set_skip()

◆ mpack_reader_set_teardown()

◆ mpack_should_read_bytes_inplace()

◆ mpack_skip_bytes()

◆ mpack_writer_destroy()

◆ mpack_writer_init()

◆ mpack_writer_init_error()

◆ mpack_writer_init_file()

◆ mpack_writer_init_filename()

◆ mpack_writer_init_growable()

◆ mpack_writer_init_stdfile()