Loading...
Searching...
No Matches
Write API

## Description

The MPack Write API encodes structured data of a fixed (hardcoded) schema to MessagePack.

## Macros

#define | MPACK_WRITER_MINIMUM_BUFFER_SIZE 32
| The minimum buffer size for a writer with a flush function. More...

## Typedefs

typedef void(* | mpack_writer_error_t) (mpack_writer_t *writer, mpack_error_t error)
| An error handler function to be called when an error is flagged on the writer. More...
typedef void(* | mpack_writer_flush_t) (mpack_writer_t *writer, const char *buffer, size_t count)
| The MPack writer's flush function to flush the buffer to the output stream. More...
typedef struct mpack_writer_t | mpack_writer_t
| A buffered MessagePack encoder. More...
typedef void(* | mpack_writer_teardown_t) (mpack_writer_t *writer)
| A teardown function to be called when the writer is destroyed. More...

## Lifecycle Functions

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

## Configuration

void | mpack_writer_set_version (mpack_writer_t *writer, mpack_version_t version)
| Sets the version of the MessagePack spec that will be generated. More...
void | mpack_writer_set_context (mpack_writer_t *writer, void *context)
| Sets the custom pointer to pass to the writer callbacks, such as flush or teardown. More...
void * | mpack_writer_context (mpack_writer_t *writer)
| Returns the custom context for writer callbacks. More...
void | mpack_writer_set_flush (mpack_writer_t *writer, mpack_writer_flush_t flush)
| Sets the flush function to write out the data when the buffer is full. More...
void | mpack_writer_set_error_handler (mpack_writer_t *writer, mpack_writer_error_t error_fn)
| Sets the error function to call when an error is flagged on the writer. More...
void | mpack_writer_set_teardown (mpack_writer_t *writer, mpack_writer_teardown_t teardown)
| Sets the teardown function to call when the writer is destroyed. More...

## Core Writer Functions

void | mpack_writer_flush_message (mpack_writer_t *writer)
| Flushes any buffered data to the underlying stream. More...
size_t | mpack_writer_buffer_used (mpack_writer_t *writer)
| Returns the number of bytes currently stored in the buffer. More...
size_t | mpack_writer_buffer_left (mpack_writer_t *writer)
| Returns the amount of space left in the buffer. More...
size_t | mpack_writer_buffer_size (mpack_writer_t *writer)
| Returns the (current) size of the buffer. More...
void | mpack_writer_flag_error (mpack_writer_t *writer, mpack_error_t error)
| Places the writer in the given error state, calling the error callback if one is set. More...
mpack_error_t | mpack_writer_error (mpack_writer_t *writer)
| Queries the error state of the MPack writer. More...
void | mpack_write_tag (mpack_writer_t *writer, mpack_tag_t tag)
| Writes a MessagePack object header (an MPack Tag.) More...

## Integers

void | mpack_write_i8 (mpack_writer_t *writer, int8_t value)
| Writes an 8-bit integer in the most efficient packing available. More...
void | mpack_write_i16 (mpack_writer_t *writer, int16_t value)
| Writes a 16-bit integer in the most efficient packing available. More...
void | mpack_write_i32 (mpack_writer_t *writer, int32_t value)
| Writes a 32-bit integer in the most efficient packing available. More...
void | mpack_write_i64 (mpack_writer_t *writer, int64_t value)
| Writes a 64-bit integer in the most efficient packing available. More...
void | mpack_write_int (mpack_writer_t *writer, int64_t value)
| Writes an integer in the most efficient packing available. More...
void | mpack_write_u8 (mpack_writer_t *writer, uint8_t value)
| Writes an 8-bit unsigned integer in the most efficient packing available. More...
void | mpack_write_u16 (mpack_writer_t *writer, uint16_t value)
| Writes an 16-bit unsigned integer in the most efficient packing available. More...
void | mpack_write_u32 (mpack_writer_t *writer, uint32_t value)
| Writes an 32-bit unsigned integer in the most efficient packing available. More...
void | mpack_write_u64 (mpack_writer_t *writer, uint64_t value)
| Writes an 64-bit unsigned integer in the most efficient packing available. More...
void | mpack_write_uint (mpack_writer_t *writer, uint64_t value)
| Writes an unsigned integer in the most efficient packing available. More...

## Other Basic Types

void | mpack_write_float (mpack_writer_t *writer, float value)
| Writes a float. More...
void | mpack_write_double (mpack_writer_t *writer, double value)
| Writes a double. More...
void | mpack_write_bool (mpack_writer_t *writer, bool value)
| Writes a boolean. More...
void | mpack_write_true (mpack_writer_t *writer)
| Writes a boolean with value true. More...
void | mpack_write_false (mpack_writer_t *writer)
| Writes a boolean with value false. More...
void | mpack_write_nil (mpack_writer_t *writer)
| Writes a nil. More...
void | mpack_write_object_bytes (mpack_writer_t *writer, const char *data, size_t bytes)
| Write a pre-encoded messagepack object. More...
void | mpack_write_timestamp (mpack_writer_t *writer, int64_t seconds, uint32_t nanoseconds)
| Writes a timestamp. More...
void | mpack_write_timestamp_seconds (mpack_writer_t *writer, int64_t seconds)
| Writes a timestamp with the given number of seconds (and zero nanoseconds). More...
void | mpack_write_timestamp_struct (mpack_writer_t *writer, mpack_timestamp_t timestamp)
| Writes a timestamp. More...

## Map and Array Functions

void | mpack_start_array (mpack_writer_t *writer, uint32_t count)
| Opens an array. More...
void | mpack_start_map (mpack_writer_t *writer, uint32_t count)
| Opens a map. More...
void | mpack_builder_compound_push (mpack_writer_t *writer)
void | mpack_builder_compound_pop (mpack_writer_t *writer)
void | mpack_finish_array (mpack_writer_t *writer)
| Finishes writing an array. More...
void | mpack_finish_map (mpack_writer_t *writer)
| Finishes writing a map. More...
void | mpack_build_array (struct mpack_writer_t *writer)
| Starts building an array. More...
void | mpack_build_map (struct mpack_writer_t *writer)
| Starts building a map. More...
void | mpack_complete_array (struct mpack_writer_t *writer)
| Completes an array being built. More...
void | mpack_complete_map (struct mpack_writer_t *writer)
| Completes a map being built. More...

## Data Helpers

void | mpack_write_str (mpack_writer_t *writer, const char *str, uint32_t length)
| Writes a string. More...
void | mpack_write_utf8 (mpack_writer_t *writer, const char *str, uint32_t length)
| Writes a string, ensuring that it is valid UTF-8. More...
void | mpack_write_cstr (mpack_writer_t *writer, const char *cstr)
| Writes a null-terminated string. More...
void | mpack_write_cstr_or_nil (mpack_writer_t *writer, const char *cstr)
| Writes a null-terminated string, or a nil node if the given cstr pointer is NULL. More...
void | mpack_write_utf8_cstr (mpack_writer_t *writer, const char *cstr)
| Writes a null-terminated string, ensuring that it is valid UTF-8. More...
void | mpack_write_utf8_cstr_or_nil (mpack_writer_t *writer, const char *cstr)
| Writes a null-terminated string ensuring that it is valid UTF-8, or writes nil if the given cstr pointer is NULL. More...
void | mpack_write_bin (mpack_writer_t *writer, const char *data, uint32_t count)
| Writes a binary blob. More...
void | mpack_write_ext (mpack_writer_t *writer, int8_t exttype, const char *data, uint32_t count)
| Writes an extension type. More...

## Chunked Data Functions

void | mpack_start_str (mpack_writer_t *writer, uint32_t count)
| Opens a string. More...
void | mpack_start_bin (mpack_writer_t *writer, uint32_t count)
| Opens a binary blob. More...
void | mpack_start_ext (mpack_writer_t *writer, int8_t exttype, uint32_t count)
| Opens an extension type. More...
void | mpack_write_bytes (mpack_writer_t *writer, const char *data, size_t count)
| Writes a portion of bytes for a string, binary blob or extension type which was opened by mpack_write_tag() or one of the mpack_start_*() functions. More...
void | mpack_finish_str (mpack_writer_t *writer)
| Finishes writing a string. More...
void | mpack_finish_bin (mpack_writer_t *writer)
| Finishes writing a binary blob. More...
void | mpack_finish_ext (mpack_writer_t *writer)
| Finishes writing an extended type binary data blob. More...
void | mpack_finish_type (mpack_writer_t *writer, mpack_type_t type)
| Finishes writing the given compound type. More...

## C++ write overloads

void | mpack_write (mpack_writer_t *writer, int8_t value)
void | mpack_write (mpack_writer_t *writer, int16_t value)
void | mpack_write (mpack_writer_t *writer, int32_t value)
void | mpack_write (mpack_writer_t *writer, int64_t value)
void | mpack_write (mpack_writer_t *writer, uint8_t value)
void | mpack_write (mpack_writer_t *writer, uint16_t value)
void | mpack_write (mpack_writer_t *writer, uint32_t value)
void | mpack_write (mpack_writer_t *writer, uint64_t value)
void | mpack_write (mpack_writer_t *writer, bool value)
void | mpack_write (mpack_writer_t *writer, float value)
void | mpack_write (mpack_writer_t *writer, double value)
void | mpack_write (mpack_writer_t *writer, char *value)
void | mpack_write (mpack_writer_t *writer, const char *value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, int8_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, int16_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, int32_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, int64_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, uint8_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, uint16_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, uint32_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, uint64_t value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, bool value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, float value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, double value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, char *value)
void | mpack_write_kv (mpack_writer_t *writer, const char *key, const char *value)

## Type-Generic Writers

#define | mpack_write(writer, value)
| Type-generic writer for primitive types. More...
#define | MPACK_WRITE_GENERIC_FLOAT float: mpack_write_float,
#define | MPACK_WRITE_GENERIC_DOUBLE double: mpack_write_double,
#define | mpack_write_kv(writer, key, value)
| Type-generic writer for key-value pairs of null-terminated string keys and primitive values. More...

## Macro Definition Documentation

## mpack_write

#define mpack_write | ( |  | writer,
|  |  | value
| ) |  |

Value:
_Generic(((void)0, value), \
int8_t: mpack_write_i8, \
int16_t: mpack_write_i16, \
int32_t: mpack_write_i32, \
int64_t: mpack_write_i64, \
uint8_t: mpack_write_u8, \
uint16_t: mpack_write_u16, \
uint32_t: mpack_write_u32, \
uint64_t: mpack_write_u64, \
bool: mpack_write_bool, \
MPACK_WRITE_GENERIC_FLOAT \
MPACK_WRITE_GENERIC_DOUBLE \
char *: mpack_write_cstr_or_nil, \
const char *: mpack_write_cstr_or_nil \
)(writer, value)
mpack_write_i32
void mpack_write_i32(mpack_writer_t *writer, int32_t value)
Writes a 32-bit integer in the most efficient packing available.
mpack_write_u64
void mpack_write_u64(mpack_writer_t *writer, uint64_t value)
Writes an 64-bit unsigned integer in the most efficient packing available.
mpack_write_i8
void mpack_write_i8(mpack_writer_t *writer, int8_t value)
Writes an 8-bit integer in the most efficient packing available.
mpack_write_u8
void mpack_write_u8(mpack_writer_t *writer, uint8_t value)
Writes an 8-bit unsigned integer in the most efficient packing available.
mpack_write_bool
void mpack_write_bool(mpack_writer_t *writer, bool value)
Writes a boolean.
mpack_write_cstr_or_nil
void mpack_write_cstr_or_nil(mpack_writer_t *writer, const char *cstr)
Writes a null-terminated string, or a nil node if the given cstr pointer is NULL.
mpack_write_u32
void mpack_write_u32(mpack_writer_t *writer, uint32_t value)
Writes an 32-bit unsigned integer in the most efficient packing available.
mpack_write_i64
void mpack_write_i64(mpack_writer_t *writer, int64_t value)
Writes a 64-bit integer in the most efficient packing available.
mpack_write_i16
void mpack_write_i16(mpack_writer_t *writer, int16_t value)
Writes a 16-bit integer in the most efficient packing available.
mpack_write_u16
void mpack_write_u16(mpack_writer_t *writer, uint16_t value)
Writes an 16-bit unsigned integer in the most efficient packing available.

Type-generic writer for primitive types.

The compiler will dispatch to an appropriate write function based on the type of the value parameter.

Note
  This requires C11 `_Generic` support. (A set of inline overloads are used in C++ to provide the same functionality.)

Warning
  In C11, the indentifiers `true`, `false` and `NULL` are all of type `int`, not `bool` or `void*`! They will emit unexpected types when passed uncast, so be careful when using them.

## mpack_write_kv

#define mpack_write_kv | ( |  | writer,
|  |  | key,
|  |  | value
| ) |  |

Value:
do { \
mpack_write_cstr(writer, key); \
mpack_write(writer, value); \
} while (0)

Type-generic writer for key-value pairs of null-terminated string keys and primitive values.

Warning
  writer may be evaluated multiple times.
  In C11, the indentifiers `true`, `false` and `NULL` are all of type `int`, not `bool` or `void*`! They will emit unexpected types when passed uncast, so be careful when using them.

Parameters

  writer | The writer.
  key | A null-terminated C string.
  value | A primitive type supported by mpack_write().

## MPACK_WRITER_MINIMUM_BUFFER_SIZE

#define MPACK_WRITER_MINIMUM_BUFFER_SIZE 32

The minimum buffer size for a writer with a flush function.

## Typedef Documentation

## mpack_writer_error_t

typedef void(* mpack_writer_error_t) (mpack_writer_t *writer, mpack_error_t error)

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

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

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

## mpack_writer_flush_t

typedef void(* mpack_writer_flush_t) (mpack_writer_t *writer, const char *buffer, size_t count)

The MPack writer's flush function to flush the buffer to the output stream.

It should flag an appropriate error on the writer if flushing fails (usually mpack_error_io or mpack_error_memory.)

The specified context for callbacks is at writer->context.

## mpack_writer_t

typedef struct mpack_writer_t mpack_writer_t

A buffered MessagePack encoder.

The encoder wraps an existing buffer and, optionally, a flush function. This allows efficiently encoding to an in-memory buffer or to a stream.

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

## mpack_writer_teardown_t

typedef void(* mpack_writer_teardown_t) (mpack_writer_t *writer)

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

## Function Documentation

## mpack_build_array()

void mpack_build_array | ( | struct mpack_writer_t * | writer | ) |

Starts building an array.

Elements must follow, and mpack_complete_array() must be called when done. The number of elements is determined automatically.

If you know ahead of time the number of elements in the array, it is more efficient to call mpack_start_array() instead, even if you are already within another open build.

Builder containers can be nested within normal (known size) containers and vice versa. You can call mpack_build_array(), then mpack_start_array() inside it, then mpack_build_array() inside that, and so forth.

See also
  mpack_complete_array() to complete this array
  mpack_start_array() if you already know the size of the array
  mpack_build_map() for implementation details

## mpack_build_map()

void mpack_build_map | ( | struct mpack_writer_t * | writer | ) |

Starts building a map.

An even number of elements must follow, and mpack_complete_map() must be called when done. The number of elements is determined automatically.

If you know ahead of time the number of elements in the map, it is more efficient to call mpack_start_map() instead, even if you are already within another open build.

Builder containers can be nested within normal (known size) containers and vice versa. You can call mpack_build_map(), then mpack_start_map() inside it, then mpack_build_map() inside that, and so forth.

A writer in build mode diverts writes to a builder buffer that allocates as needed. Once the last map or array being built is completed, the deferred message is composed with computed array and map sizes into the writer. Builder maps and arrays are encoded exactly the same as ordinary maps and arrays in the final message.

This indirect encoding is costly, as it incurs at least an extra copy of all data written within a builder (but not additional copies for nested builders.) Expect a speed penalty of half or more.

A good strategy is to use this during early development when your messages are constantly changing, and then closer to release when your message formats have stabilized, replace all your build calls with start calls with pre-computed sizes. Or don't, if you find the builder has little impact on performance, because even with builders MPack is extremely fast.

Note
  When an array or map starts being built, nothing will be flushed until it is completed. If you are building a large message that does not fit in the output stream, you won't get an error about it until everything is written.

See also
  mpack_complete_map() to complete this map
  mpack_start_map() if you already know the size of the map

## mpack_complete_array()

void mpack_complete_array | ( | struct mpack_writer_t * | writer | ) |

Completes an array being built.

See also
  mpack_build_array()

## mpack_complete_map()

void mpack_complete_map | ( | struct mpack_writer_t * | writer | ) |

Completes a map being built.

See also
  mpack_build_map()

## mpack_finish_array()

void mpack_finish_array | ( | mpack_writer_t * | writer | ) |

Finishes writing an array.

This should be called only after a corresponding call to mpack_start_array() and after the array contents are written.

In debug mode (or if MPACK_WRITE_TRACKING is not 0), this will track writes to ensure that the correct number of elements are written.

See also
  mpack_start_array()

## mpack_finish_bin()

void mpack_finish_bin | ( | mpack_writer_t * | writer | ) |

Finishes writing a binary blob.

This should be called only after a corresponding call to mpack_start_bin() and after the binary bytes are written with mpack_write_bytes().

This will track writes to ensure that the correct number of bytes are written.

See also
  mpack_start_bin()
  mpack_write_bytes()

## mpack_finish_ext()

void mpack_finish_ext | ( | mpack_writer_t * | writer | ) |

Finishes writing an extended type binary data blob.

This should be called only after a corresponding call to mpack_start_bin() and after the binary bytes are written with mpack_write_bytes().

This will track writes to ensure that the correct number of bytes are written.

Note
  This requires MPACK_EXTENSIONS.

See also
  mpack_start_ext()
  mpack_write_bytes()

## mpack_finish_map()

void mpack_finish_map | ( | mpack_writer_t * | writer | ) |

Finishes writing a map.

This should be called only after a corresponding call to mpack_start_map() and after the map contents are written.

In debug mode (or if MPACK_WRITE_TRACKING is not 0), this will track writes to ensure that the correct number of elements are written.

See also
  mpack_start_map()

## mpack_finish_str()

void mpack_finish_str | ( | mpack_writer_t * | writer | ) |

Finishes writing a string.

This should be called only after a corresponding call to mpack_start_str() and after the string bytes are written with mpack_write_bytes().

This will track writes to ensure that the correct number of elements are written.

See also
  mpack_start_str()
  mpack_write_bytes()

## mpack_finish_type()

void mpack_finish_type | ( | mpack_writer_t * | writer,
|  | mpack_type_t | type
| ) |  |

Finishes writing the given compound type.

This will track writes to ensure that the correct number of elements or bytes are written.

This can be called with the appropriate type instead the corresponding mpack_finish_*() function if you want to finish a dynamic type.

## mpack_start_array()

void mpack_start_array | ( | mpack_writer_t * | writer,
|  | uint32_t | count
| ) |  |

Opens an array.

`count` elements must follow, and mpack_finish_array() must be called when done.

If you do not know the number of elements to be written ahead of time, call mpack_build_array() instead.

See also
  mpack_finish_array()
  mpack_build_array() to count the number of elements automatically

## mpack_start_bin()

void mpack_start_bin | ( | mpack_writer_t * | writer,
|  | uint32_t | count
| ) |  |

Opens a binary blob.

`count` bytes should be written with calls to mpack_write_bytes(), and mpack_finish_bin() should be called when done.

## mpack_start_ext()

void mpack_start_ext | ( | mpack_writer_t * | writer,
|  | int8_t | exttype,
|  | uint32_t | count
| ) |  |

Opens an extension type.

`count` bytes should be written with calls to mpack_write_bytes(), and mpack_finish_ext() should be called when done.

Extension types [0, 127] are available for application-specific types. Extension types [-128, -1] are reserved for future extensions of MessagePack.

Note
  This requires MPACK_EXTENSIONS.

## mpack_start_map()

void mpack_start_map | ( | mpack_writer_t * | writer,
|  | uint32_t | count
| ) |  |

Opens a map.

`count * 2` elements must follow, and mpack_finish_map() must be called when done.

If you do not know the number of elements to be written ahead of time, call mpack_build_map() instead.

Remember that while map elements in MessagePack are implicitly ordered, they are not ordered in JSON. If you need elements to be read back in the order they are written, consider use an array instead.

See also
  mpack_finish_map()
  mpack_build_map() to count the number of key/value pairs automatically

## mpack_start_str()

void mpack_start_str | ( | mpack_writer_t * | writer,
|  | uint32_t | count
| ) |  |

Opens a string.

`count` bytes should be written with calls to mpack_write_bytes(), and mpack_finish_str() should be called when done.

To write an entire string at once, use mpack_write_str() or mpack_write_cstr() instead.

MPack does not care about the underlying encoding, but UTF-8 is highly recommended, especially for compatibility with JSON.

## mpack_write_bin()

void mpack_write_bin | ( | mpack_writer_t * | writer,
|  | const char * | data,
|  | uint32_t | count
| ) |  |

Writes a binary blob.

To stream a binary blob in chunks, use mpack_start_bin() instead.

You should not call mpack_finish_bin() after calling this; this performs both start and finish.

## mpack_write_bool()

void mpack_write_bool | ( | mpack_writer_t * | writer,
|  | bool | value
| ) |  |

Writes a boolean.

## mpack_write_bytes()

void mpack_write_bytes | ( | mpack_writer_t * | writer,
|  | const char * | data,
|  | size_t | count
| ) |  |

Writes a portion of bytes for a string, binary blob or extension type which was opened by mpack_write_tag() or one of the mpack_start_*() functions.

This can be called multiple times to write the data in chunks, as long as the total amount of bytes written matches the count given when the compound type was started.

The corresponding mpack_finish_*() function must be called when done.

To write an entire string, binary blob or extension type at once, use one of the mpack_write_*() functions instead.

See also
  mpack_write_tag()
  mpack_start_str()
  mpack_start_bin()
  mpack_start_ext()
  mpack_finish_str()
  mpack_finish_bin()
  mpack_finish_ext()
  mpack_finish_type()

## mpack_write_cstr()

void mpack_write_cstr | ( | mpack_writer_t * | writer,
|  | const char * | cstr
| ) |  |

Writes a null-terminated string.

(The null-terminator is not written.)

MPack does not care about the underlying encoding, but UTF-8 is highly recommended, especially for compatibility with JSON. You should consider calling mpack_write_utf8_cstr() instead, especially if you will be reading it back as UTF-8.

You should not call mpack_finish_str() after calling this; this performs both start and finish.

## mpack_write_cstr_or_nil()

void mpack_write_cstr_or_nil | ( | mpack_writer_t * | writer,
|  | const char * | cstr
| ) |  |

Writes a null-terminated string, or a nil node if the given cstr pointer is NULL.

(The null-terminator is not written.)

MPack does not care about the underlying encoding, but UTF-8 is highly recommended, especially for compatibility with JSON. You should consider calling mpack_write_utf8_cstr_or_nil() instead, especially if you will be reading it back as UTF-8.

You should not call mpack_finish_str() after calling this; this performs both start and finish.

## mpack_write_double()

void mpack_write_double | ( | mpack_writer_t * | writer,
|  | double | value
| ) |  |

Writes a double.

## mpack_write_ext()

void mpack_write_ext | ( | mpack_writer_t * | writer,
|  | int8_t | exttype,
|  | const char * | data,
|  | uint32_t | count
| ) |  |

Writes an extension type.

To stream an extension blob in chunks, use mpack_start_ext() instead.

Extension types [0, 127] are available for application-specific types. Extension types [-128, -1] are reserved for future extensions of MessagePack.

You should not call mpack_finish_ext() after calling this; this performs both start and finish.

Note
  This requires MPACK_EXTENSIONS.

## mpack_write_false()

void mpack_write_false | ( | mpack_writer_t * | writer | ) |

Writes a boolean with value false.

## mpack_write_float()

void mpack_write_float | ( | mpack_writer_t * | writer,
|  | float | value
| ) |  |

Writes a float.

## mpack_write_i16()

void mpack_write_i16 | ( | mpack_writer_t * | writer,
|  | int16_t | value
| ) |  |

Writes a 16-bit integer in the most efficient packing available.

## mpack_write_i32()

void mpack_write_i32 | ( | mpack_writer_t * | writer,
|  | int32_t | value
| ) |  |

Writes a 32-bit integer in the most efficient packing available.

## mpack_write_i64()

void mpack_write_i64 | ( | mpack_writer_t * | writer,
|  | int64_t | value
| ) |  |

Writes a 64-bit integer in the most efficient packing available.

## mpack_write_i8()

void mpack_write_i8 | ( | mpack_writer_t * | writer,
|  | int8_t | value
| ) |  |

Writes an 8-bit integer in the most efficient packing available.

## mpack_write_int()

void mpack_write_int | ( | mpack_writer_t * | writer,
|  | int64_t | value
| ) |  |

Writes an integer in the most efficient packing available.

## mpack_write_nil()

void mpack_write_nil | ( | mpack_writer_t * | writer | ) |

Writes a nil.

## mpack_write_object_bytes()

void mpack_write_object_bytes | ( | mpack_writer_t * | writer,
|  | const char * | data,
|  | size_t | bytes
| ) |  |

Write a pre-encoded messagepack object.

## mpack_write_str()

void mpack_write_str | ( | mpack_writer_t * | writer,
|  | const char * | str,
|  | uint32_t | length
| ) |  |

Writes a string.

To stream a string in chunks, use mpack_start_str() instead.

MPack does not care about the underlying encoding, but UTF-8 is highly recommended, especially for compatibility with JSON. You should consider calling mpack_write_utf8() instead, especially if you will be reading it back as UTF-8.

You should not call mpack_finish_str() after calling this; this performs both start and finish.

## mpack_write_tag()

void mpack_write_tag | ( | mpack_writer_t * | writer,
|  | mpack_tag_t | tag
| ) |  |

Writes a MessagePack object header (an MPack Tag.)

If the value is a map, array, string, binary or extension type, the containing elements or bytes must be written separately and the appropriate finish function must be called (as though one of the mpack_start_*() functions was called.)

See also
  mpack_write_bytes()
  mpack_finish_map()
  mpack_finish_array()
  mpack_finish_str()
  mpack_finish_bin()
  mpack_finish_ext()
  mpack_finish_type()

## mpack_write_timestamp()

void mpack_write_timestamp | ( | mpack_writer_t * | writer,
|  | int64_t | seconds,
|  | uint32_t | nanoseconds
| ) |  |

Writes a timestamp.

Note
  This requires MPACK_EXTENSIONS.

Parameters

  writer | The writer
  seconds | The (signed) number of seconds since 1970-01-01T00:00:00Z.
  nanoseconds | The additional number of nanoseconds from 0 to 999,999,999 inclusive.

## mpack_write_timestamp_seconds()

void mpack_write_timestamp_seconds | ( | mpack_writer_t * | writer,
|  | int64_t | seconds
| ) |  |

Writes a timestamp with the given number of seconds (and zero nanoseconds).

Note
  This requires MPACK_EXTENSIONS.

Parameters

  writer | The writer
  seconds | The (signed) number of seconds since 1970-01-01T00:00:00Z.

## mpack_write_timestamp_struct()

void mpack_write_timestamp_struct | ( | mpack_writer_t * | writer,
|  | mpack_timestamp_t | timestamp
| ) |  |

Writes a timestamp.

Note
  This requires MPACK_EXTENSIONS.

## mpack_write_true()

void mpack_write_true | ( | mpack_writer_t * | writer | ) |

Writes a boolean with value true.

## mpack_write_u16()

void mpack_write_u16 | ( | mpack_writer_t * | writer,
|  | uint16_t | value
| ) |  |

Writes an 16-bit unsigned integer in the most efficient packing available.

## mpack_write_u32()

void mpack_write_u32 | ( | mpack_writer_t * | writer,
|  | uint32_t | value
| ) |  |

Writes an 32-bit unsigned integer in the most efficient packing available.

## mpack_write_u64()

void mpack_write_u64 | ( | mpack_writer_t * | writer,
|  | uint64_t | value
| ) |  |

Writes an 64-bit unsigned integer in the most efficient packing available.

## mpack_write_u8()

void mpack_write_u8 | ( | mpack_writer_t * | writer,
|  | uint8_t | value
| ) |  |

Writes an 8-bit unsigned integer in the most efficient packing available.

## mpack_write_uint()

void mpack_write_uint | ( | mpack_writer_t * | writer,
|  | uint64_t | value
| ) |  |

Writes an unsigned integer in the most efficient packing available.

## mpack_write_utf8()

void mpack_write_utf8 | ( | mpack_writer_t * | writer,
|  | const char * | str,
|  | uint32_t | length
| ) |  |

Writes a string, ensuring that it is valid UTF-8.

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

You should not call mpack_finish_str() after calling this; this performs both start and finish.

Exceptions

  mpack_error_invalid | if the string is not valid UTF-8

## mpack_write_utf8_cstr()

void mpack_write_utf8_cstr | ( | mpack_writer_t * | writer,
|  | const char * | cstr
| ) |  |

Writes a null-terminated string, ensuring that it is valid UTF-8.

(The null-terminator is not written.)

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

You should not call mpack_finish_str() after calling this; this performs both start and finish.

Exceptions

  mpack_error_invalid | if the string is not valid UTF-8

## mpack_write_utf8_cstr_or_nil()

void mpack_write_utf8_cstr_or_nil | ( | mpack_writer_t * | writer,
|  | const char * | cstr
| ) |  |

Writes a null-terminated string ensuring that it is valid UTF-8, or writes nil if the given cstr pointer is NULL.

(The null-terminator is not written.)

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

You should not call mpack_finish_str() after calling this; this performs both start and finish.

Exceptions

  mpack_error_invalid | if the string is not valid UTF-8

## mpack_writer_buffer_left()

size_t mpack_writer_buffer_left | ( | mpack_writer_t * | writer | ) |

Returns the amount of space left in the buffer.

This may be reset after a write if bytes are flushed to an underlying stream.

## mpack_writer_buffer_size()

size_t mpack_writer_buffer_size | ( | mpack_writer_t * | writer | ) |

Returns the (current) size of the buffer.

This may change after a write if the flush callback changes the buffer.

## mpack_writer_buffer_used()

size_t mpack_writer_buffer_used | ( | mpack_writer_t * | writer | ) |

Returns the number of bytes currently stored in the buffer.

This may be less than the total number of bytes written if bytes have been flushed to an underlying stream.

## mpack_writer_context()

void * mpack_writer_context | ( | mpack_writer_t * | writer | ) |

Returns the custom context for writer callbacks.

See also
  mpack_writer_set_context
  mpack_writer_set_flush

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

mpack_error_t mpack_writer_error | ( | mpack_writer_t * | writer | ) |

Queries the error state of the MPack writer.

If a writer 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_writer_flag_error()

void mpack_writer_flag_error | ( | mpack_writer_t * | writer,
|  | mpack_error_t | error
| ) |  |

Places the writer 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 write it, or if you want to cancel writing in the middle of a document. (The writer will assert if you try to destroy it without error and with unclosed compound types. In this case you should flag mpack_error_data before destroying it.)

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

See also
  mpack_writer_destroy
  mpack_error_data

## mpack_writer_flush_message()

void mpack_writer_flush_message | ( | mpack_writer_t * | writer | ) |

Flushes any buffered data to the underlying stream.

If the writer is connected to a socket and you are keeping it open, you will want to call this after writing a message (or set of messages) so that the data is actually sent.

It is not necessary to call this if you are not keeping the writer open afterwards. You can just call `mpack_writer_destroy()` and it will flush before cleaning up.

This will assert if no flush function is assigned to the writer.

If write tracking is enabled, this will break and flag mpack_error_bug if the writer has any open compound types, ensuring that no compound types are still open. This prevents a "missing finish" bug from causing a never-ending message.

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

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

## mpack_writer_set_context()

void mpack_writer_set_context | ( | mpack_writer_t * | writer,
|  | void * | context
| ) |  |

Sets the custom pointer to pass to the writer callbacks, such as flush or teardown.

Parameters

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

See also
  mpack_writer_context()

## mpack_writer_set_error_handler()

void mpack_writer_set_error_handler | ( | mpack_writer_t * | writer,
|  | mpack_writer_error_t | error_fn
| ) |  |

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

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

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

See also
  mpack_writer_error_t

Parameters

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

## mpack_writer_set_flush()

void mpack_writer_set_flush | ( | mpack_writer_t * | writer,
|  | mpack_writer_flush_t | flush
| ) |  |

Sets the flush function to write out the data when the buffer is full.

If no flush function is used, trying to write past the end of the buffer will result in mpack_error_too_big.

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

Parameters

  writer | The MPack writer.
  flush | The function to write out data from the buffer.

See also
  mpack_writer_context()

## mpack_writer_set_teardown()

void mpack_writer_set_teardown | ( | mpack_writer_t * | writer,
|  | mpack_writer_teardown_t | teardown
| ) |  |

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

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

Parameters

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

## mpack_writer_set_version()

void mpack_writer_set_version | ( | mpack_writer_t * | writer,
|  | mpack_version_t | version
| ) |  |

Sets the version of the MessagePack spec that will be generated.

This can be used to interface with older libraries that do not support the newest MessagePack features (such as the `str8` type.)

Note
  This requires MPACK_COMPATIBILITY.