msgpuck.h - Man Page

MsgPuck is a simple and efficient MsgPack encoder/decoder library in a single self-contained file.

Synopsis

#include <stdlib.h>
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <string.h>
#include <assert.h>
#include <stdarg.h>
#include <stdio.h>

Data Structures

struct mp_frame
struct mp_stack

Macros

#define MP_PRINT_MAX_DEPTH   32

Typedefs

typedef int(* mp_fprint_ext_f) (FILE *file, const char **data, int depth)
typedef int(* mp_snprint_ext_f) (char *buf, int size, const char **data, int depth)

Enumerations

enum mp_type { MP_NIL = 0, MP_UINT, MP_INT, MP_STR, MP_BIN, MP_ARRAY, MP_MAP, MP_BOOL, MP_FLOAT, MP_DOUBLE, MP_EXT }
MsgPack data types.

Functions

MP_PROTO MP_PURE enum mp_type mp_typeof (const char c)
Determine MsgPack type by a first byte c of encoded data.
MP_PROTO MP_CONST uint32_t mp_sizeof_array (uint32_t size)
Calculate exact buffer size needed to store an array header of size elements. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.
MP_PROTO char * mp_encode_array (char *data, uint32_t size)
Encode an array header of size elements.
MP_PROTO MP_PURE ptrdiff_t mp_check_array (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode an array header.
MP_PROTO uint32_t mp_decode_array (const char **data)
Decode an array header from MsgPack data.
MP_PROTO MP_CONST uint32_t mp_sizeof_map (uint32_t size)
Calculate exact buffer size needed to store a map header of size elements. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.
MP_PROTO char * mp_encode_map (char *data, uint32_t size)
Encode a map header of size elements.
MP_PROTO MP_PURE ptrdiff_t mp_check_map (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode a map header.
MP_PROTO uint32_t mp_decode_map (const char **data)
Decode a map header from MsgPack data.
MP_PROTO uint32_t mp_sizeof_extl (uint32_t len)
calculate exact buffer size needed to store ext header for a value of length len.
MP_PROTO uint32_t mp_sizeof_ext (uint32_t len)
Equivalent to mp_sizeof_extl(len) + len.
MP_PROTO char * mp_encode_extl (char *data, int8_t type, uint32_t len)
Encode extension header with type and value length len. The value must be encoded after the header.
MP_PROTO char * mp_encode_ext (char *data, int8_t type, const char *str, uint32_t len)
Encode extension data of length len. The function is equivalent to mp_encode_extl() + memcpy.
MP_PROTO MP_PURE ptrdiff_t mp_check_extl (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode an ext header.
MP_PROTO uint32_t mp_decode_extl (const char **data, int8_t *type)
Decode an extension header from MsgPack data.
MP_PROTO const char * mp_decode_ext (const char **data, int8_t *type, uint32_t *len)
Decode an extension from MsgPack data.
MP_PROTO MP_CONST uint32_t mp_sizeof_uint (uint64_t num)
Calculate exact buffer size needed to store an integer num. Maximum return value is 9. For performance reasons you can preallocate buffer for maximum size without calling the function. Example usage:
MP_PROTO MP_CONST uint32_t mp_sizeof_int (int64_t num)
Calculate exact buffer size needed to store an integer num. Maximum return value is 9. For performance reasons you can preallocate buffer for maximum size without calling the function.
MP_PROTO char * mp_encode_uint (char *data, uint64_t num)
Encode an unsigned integer num. It is your responsibility to ensure that data has enough space.
MP_PROTO char * mp_encode_int (char *data, int64_t num)
Encode a signed integer num. It is your responsibility to ensure that data has enough space.
MP_PROTO MP_PURE ptrdiff_t mp_check_uint (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode an uint.
MP_PROTO MP_PURE ptrdiff_t mp_check_int (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode an int.
MP_PROTO uint64_t mp_decode_uint (const char **data)
Decode an unsigned integer from MsgPack data.
MP_PROTO int64_t mp_decode_int (const char **data)
Decode a signed integer from MsgPack data.
MP_PROTO MP_PURE int mp_compare_uint (const char *data_a, const char *data_b)
Compare two packed unsigned integers.
MP_PROTO MP_CONST uint32_t mp_sizeof_float (float num)
Calculate exact buffer size needed to store a float num. The return value is always 5. The function was added to provide integrity of the library.
MP_PROTO MP_CONST uint32_t mp_sizeof_double (double num)
Calculate exact buffer size needed to store a double num. The return value is either 5 or 9. The function was added to provide integrity of the library. For performance reasons you can preallocate buffer for maximum size without calling the function.
MP_PROTO char * mp_encode_float (char *data, float num)
Encode a float num. It is your responsibility to ensure that data has enough space.
MP_PROTO char * mp_encode_double (char *data, double num)
Encode a double num. It is your responsibility to ensure that data has enough space.
MP_PROTO MP_PURE ptrdiff_t mp_check_float (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode a float.
MP_PROTO MP_PURE ptrdiff_t mp_check_double (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode a double.
MP_PROTO float mp_decode_float (const char **data)
Decode a float from MsgPack data.
MP_PROTO double mp_decode_double (const char **data)
Decode a double from MsgPack data.
MP_PROTO MP_CONST uint32_t mp_sizeof_strl (uint32_t len)
Calculate exact buffer size needed to store a string header of length num. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.
MP_PROTO MP_CONST uint32_t mp_sizeof_str (uint32_t len)
Equivalent to mp_sizeof_strl(len) + len.
MP_PROTO MP_CONST uint32_t mp_sizeof_binl (uint32_t len)
Calculate exact buffer size needed to store a binstring header of length num. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.
MP_PROTO MP_CONST uint32_t mp_sizeof_bin (uint32_t len)
Equivalent to mp_sizeof_binl(len) + len.
MP_PROTO char * mp_encode_strl (char *data, uint32_t len)
Encode a string header of length len.
MP_PROTO char * mp_encode_str (char *data, const char *str, uint32_t len)
Encode a string of length len. The function is equivalent to mp_encode_strl() + memcpy.
MP_PROTO char * mp_encode_binl (char *data, uint32_t len)
Encode a binstring header of length len. See mp_encode_strl() for more details.
MP_PROTO char * mp_encode_bin (char *data, const char *str, uint32_t len)
Encode a binstring of length len. The function is equivalent to mp_encode_binl() + memcpy.
size_t mp_format (char *data, size_t data_size, const char *format,...)
Encode a sequence of values according to format string. Example: mp_format(buf, sz, '[%d {%d%s%d%s}]', 42, 0, 'false', 1, 'true'); to get a msgpack array of two items: number 42 and map (0->'false, 2->'true)Doesnotwriteitemsthatdon'tfittodata_sizeargument.
size_t mp_vformat (char *data, size_t data_size, const char *format, va_list args)
mp_format variation, taking variable argument list Example: va_list args; va_start(args, fmt); mp_vformat(data, data_size, fmt, args); va_end(args);
int mp_fprint (FILE *file, const char *data)
print MsgPack data file using JSON-like format. MP_EXT is printed as a non-standard JSON 'list':
int mp_fprint_recursion (FILE *file, const char **data, int depth)
Print MsgPack data to file using JSON-like format. Works exactly like.
int mp_fprint_ext_default (FILE *file, const char **data, int depth)
Default MP_EXT serializer into a file. Skips the object, ignores all the other arguments, and writes.
int mp_snprint (char *buf, int size, const char *data)
format MsgPack data to buf using JSON-like format. Behaves the same as
int mp_snprint_recursion (char *buf, int size, const char **data, int depth)
Format MsgPack data to buf using JSON-like format. Works exactly like.
int mp_snprint_ext_default (char *buf, int size, const char **data, int depth)
Default MP_EXT serializer into a string. Skips the object, ignores all the other arguments, and prints.
MP_PROTO MP_PURE ptrdiff_t mp_check_strl (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode a string header.
MP_PROTO MP_PURE ptrdiff_t mp_check_binl (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode a binstring header.
MP_PROTO uint32_t mp_decode_strl (const char **data)
Decode a length of a string from MsgPack data.
MP_PROTO const char * mp_decode_str (const char **data, uint32_t *len)
Decode a string from MsgPack data.
MP_PROTO uint32_t mp_decode_binl (const char **data)
Decode a length of a binstring from MsgPack data.
MP_PROTO const char * mp_decode_bin (const char **data, uint32_t *len)
Decode a binstring from MsgPack data.
MP_PROTO uint32_t mp_decode_strbinl (const char **data)
Decode a length of a string or binstring from MsgPack data.
MP_PROTO const char * mp_decode_strbin (const char **data, uint32_t *len)
Decode a string or binstring from MsgPack data.
MP_PROTO MP_CONST uint32_t mp_sizeof_nil (void)
Calculate exact buffer size needed to store the nil value. The return value is always 1. The function was added to provide integrity of the library.
MP_PROTO char * mp_encode_nil (char *data)
Encode the nil value. It is your responsibility to ensure that data has enough space.
MP_PROTO MP_PURE ptrdiff_t mp_check_nil (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode nil.
MP_PROTO void mp_decode_nil (const char **data)
Decode the nil value from MsgPack data.
MP_PROTO MP_CONST uint32_t mp_sizeof_bool (bool val)
Calculate exact buffer size needed to store a boolean value. The return value is always 1. The function was added to provide integrity of the library.
MP_PROTO char * mp_encode_bool (char *data, bool val)
Encode a bool value val. It is your responsibility to ensure that data has enough space.
MP_PROTO MP_PURE ptrdiff_t mp_check_bool (const char *cur, const char *end)
Check that cur buffer has enough bytes to decode a bool value.
MP_PROTO bool mp_decode_bool (const char **data)
Decode a bool value from MsgPack data.
MP_PROTO int mp_read_int32 (const char **data, int32_t *ret)
Decode an integer value as int32_t from MsgPack data.
MP_PROTO int mp_read_int64 (const char **data, int64_t *ret)
Decode an integer value as int64_t from MsgPack data.
MP_PROTO int mp_read_double (const char **data, double *ret)
Decode a floating point value as double from MsgPack data.
MP_PROTO void mp_next (const char **data)
Skip one element in a packed data.
MP_PROTO int mp_check (const char **data, const char *end)
Equivalent to mp_next() but also validates MsgPack in data.
MP_PROTO void mp_stack_create (struct mp_stack *stack, int size, struct mp_frame *frames)
Initialize mp_stack stack with specified size size and user-allocated array frames. The frames allocation must have at least size mp_frame items.
MP_PROTO bool mp_stack_is_empty (struct mp_stack *stack)
Test if mp_stack stack is empty.
MP_PROTO bool mp_stack_is_full (struct mp_stack *stack)
Test if mp_stack stack is full.
MP_PROTO struct mp_frame * mp_stack_top (struct mp_stack *stack)
Return the top mp_stack stack frame.
MP_PROTO void mp_stack_pop (struct mp_stack *stack)
Pop the top mp_stack stack frame.
MP_PROTO void mp_stack_push (struct mp_stack *stack, enum mp_type type, int count)
Construct a new mp_frame and push it on to mp_stack stack.
MP_PROTO bool mp_frame_advance (struct mp_frame *frame)
Advance idx attribute of the frame.

Variables

mp_fprint_ext_f mp_fprint_ext
Function called when need to serialize MP_EXT into a file.
mp_snprint_ext_f mp_snprint_ext
Function called when need to serialize MP_EXT into a string.

Detailed Description

MsgPuck is a simple and efficient MsgPack encoder/decoder library in a single self-contained file.

MsgPuck

Usage example:

// Encode
char buf[1024];
char *w = buf;
w = mp_encode_array(w, 4);
w = mp_encode_uint(w, 10);
w = mp_encode_str(w, "hello world", strlen("hello world"));
w = mp_encode_bool(w, true);
w = mp_encode_double(w, 3.1415);

// Validate
const char *b = buf;
int r = mp_check(&b, w);
assert(!r);
assert(b == w);

// Decode
uint32_t size;
uint64_t ival;
const char *sval;
uint32_t sval_len;
bool bval;
double dval;

const char *r = buf;

size = mp_decode_array(&r);
// size is 4

ival = mp_decode_uint(&r);
// ival is 10;

sval = mp_decode_str(&r, &sval_len);
// sval is "hello world", sval_len is strlen("hello world")

bval = mp_decode_bool(&r);
// bval is true

dval = mp_decode_double(&r);
// dval is 3.1415

assert(r == w);
Note

Supported compilers. The implementation requires a C99+ or C++03+ compatible compiler.

Inline functions. The implementation is compatible with both C99 and GNU inline functions. Please link libmsgpuck.a static library for non-inlined versions of functions and global tables.

Macro Definition Documentation

#define MP_PRINT_MAX_DEPTH   32

The maximum msgpack nesting depth supported by mp_snprint(). Everything beyond that will be omitted (replaced with '...').

Function Documentation

MP_PROTO int mp_check (const char ** data, const char * end)

Equivalent to mp_next() but also validates MsgPack in data.

Parameters

data - the pointer to a buffer
end - the end of a buffer

Return values

0 when MsgPack in data is valid.
!= 0 when MsgPack in data is not valid.

Postcondition

*data = *data + mp_sizeof_TYPE() where TYPE is mp_typeof(**data)

*data is not defined if MsgPack is not valid

See also

mp_next()

MP_PROTO MP_PURE ptrdiff_t mp_check_array (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode an array header.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_ARRAY

MP_PROTO MP_PURE ptrdiff_t mp_check_binl (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode a binstring header.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_BIN

MP_PROTO MP_PURE ptrdiff_t mp_check_bool (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode a bool value.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_BOOL

MP_PROTO MP_PURE ptrdiff_t mp_check_double (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode a double.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_DOUBLE

MP_PROTO MP_PURE ptrdiff_t mp_check_extl (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode an ext header.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the numbeer of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_EXT

MP_PROTO MP_PURE ptrdiff_t mp_check_float (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode a float.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_FLOAT

MP_PROTO MP_PURE ptrdiff_t mp_check_int (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode an int.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_INT

MP_PROTO MP_PURE ptrdiff_t mp_check_map (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode a map header.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_MAP

MP_PROTO MP_PURE ptrdiff_t mp_check_nil (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode nil.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_NIL

MP_PROTO MP_PURE ptrdiff_t mp_check_strl (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode a string header.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_STR

MP_PROTO MP_PURE ptrdiff_t mp_check_uint (const char * cur, const char * end)

Check that cur buffer has enough bytes to decode an uint.

Parameters

cur buffer
end end of the buffer

Return values

0 - buffer has enough bytes
> 0 - the number of remaining bytes to read

Precondition

cur < end

mp_typeof(*cur) == MP_UINT

MP_PROTO MP_PURE int mp_compare_uint (const char * data_a, const char * data_b)

Compare two packed unsigned integers. The function is faster than two mp_decode_uint() calls.

Parameters

data_a unsigned int a
data_b unsigned int b

Return values

< 0 when a < b
0 when a == b
> 0 when a > b

MP_PROTO uint32_t mp_decode_array (const char ** data)

Decode an array header from MsgPack data. All array members must be decoded after the header.

Parameters

data - the pointer to a buffer

Returns

the number of elements in an array

Postcondition

*data = *data + mp_sizeof_array(retval)

See also

An usage example

MP_PROTO const char* mp_decode_bin (const char ** data, uint32_t * len)

Decode a binstring from MsgPack data.

Parameters

data - the pointer to a buffer
len - the pointer to save a binstring length

Returns

a pointer to a decoded binstring

Postcondition

*data = *data + mp_sizeof_str(*len)

See also

mp_encode_binl

MP_PROTO uint32_t mp_decode_binl (const char ** data)

Decode a length of a binstring from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

a length of a binstring

Postcondition

*data = *data + mp_sizeof_binl(retval)

See also

mp_encode_binl

MP_PROTO bool mp_decode_bool (const char ** data)

Decode a bool value from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

a decoded bool value

Postcondition

*data = *data + mp_sizeof_bool(retval)

MP_PROTO double mp_decode_double (const char ** data)

Decode a double from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

a double

Postcondition

*data = *data + mp_sizeof_double(retval)

MP_PROTO const char* mp_decode_ext (const char ** data, int8_t * type, uint32_t * len)

Decode an extension from MsgPack data.

Parameters

data - the pointer to a buffer
type - the pointer to save extension type
len - the pointer to save extension data length

Returns

a pointer to decoded extension data

Postcondition

*data = *data + mp_sizeof_ext(*len)

MP_PROTO uint32_t mp_decode_extl (const char ** data, int8_t * type)

Decode an extension header from MsgPack data. The extension type value must be decoded after the header.

Parameters

data - the pointer to a buffer.
type - decoded type of the following value.

Return values

- the length of the following ext value.

Postcondition

*data = *data + mp_sizeof_extl(length)

MP_PROTO float mp_decode_float (const char ** data)

Decode a float from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

a float

Postcondition

*data = *data + mp_sizeof_float(retval)

MP_PROTO int64_t mp_decode_int (const char ** data)

Decode a signed integer from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

an unsigned number

Postcondition

*data = *data + mp_sizeof_int(retval)

MP_PROTO uint32_t mp_decode_map (const char ** data)

Decode a map header from MsgPack data. All map key-value pairs must be decoded after the header.

Parameters

data - the pointer to a buffer

Returns

the number of key/value pairs in a map

Postcondition

*data = *data + mp_sizeof_array(retval)

See also

An usage example

MP_PROTO void mp_decode_nil (const char ** data)

Decode the nil value from MsgPack data.

Parameters

data - the pointer to a buffer

Postcondition

*data = *data + mp_sizeof_nil()

MP_PROTO const char* mp_decode_str (const char ** data, uint32_t * len)

Decode a string from MsgPack data.

Parameters

data - the pointer to a buffer
len - the pointer to save a string length

Returns

a pointer to a decoded string

Postcondition

*data = *data + mp_sizeof_str(*len)

See also

mp_encode_binl

MP_PROTO const char* mp_decode_strbin (const char ** data, uint32_t * len)

Decode a string or binstring from MsgPack data.

Parameters

data - the pointer to a buffer
len - the pointer to save a binstring length

Returns

a pointer to a decoded binstring

Postcondition

*data = *data + mp_sizeof_strbinl(*len)

See also

mp_encode_binl

MP_PROTO uint32_t mp_decode_strbinl (const char ** data)

Decode a length of a string or binstring from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

a length of a string

Postcondition

*data = *data + mp_sizeof_strbinl(retval)

See also

mp_encode_binl

MP_PROTO uint32_t mp_decode_strl (const char ** data)

Decode a length of a string from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

a length of astring

Postcondition

*data = *data + mp_sizeof_strl(retval)

See also

mp_encode_strl

MP_PROTO uint64_t mp_decode_uint (const char ** data)

Decode an unsigned integer from MsgPack data.

Parameters

data - the pointer to a buffer

Returns

an unsigned number

Postcondition

*data = *data + mp_sizeof_uint(retval)

MP_PROTO char* mp_encode_array (char * data, uint32_t size)

Encode an array header of size elements. All array members must be encoded after the header.

Example usage:

// Encode
char buf[1024];
char *w = buf;
w = mp_encode_array(w, 2);
w = mp_encode_uint(w, 10);
w = mp_encode_uint(w, 15);

// Decode
const char *r = buf;
uint32_t size = mp_decode_array(&r);
for (uint32_t i = 0; i < size; i++) {
    uint64_t val = mp_decode_uint(&r);
}
assert (r == w);

It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
size - a number of elements

Returns

data + mp_sizeof_array(size)

See also

mp_sizeof_array

MP_PROTO char* mp_encode_bin (char * data, const char * str, uint32_t len)

Encode a binstring of length len. The function is equivalent to mp_encode_binl() + memcpy.

Parameters

data - a buffer
str - a pointer to binstring data
len - a binstring length

Returns

data + mp_sizeof_bin(len) == data + mp_sizeof_binl(len) + len

See also

mp_encode_strl

MP_PROTO char* mp_encode_binl (char * data, uint32_t len)

Encode a binstring header of length len. See mp_encode_strl() for more details.

Parameters

data - a bufer
len - a string length

Returns

data + mp_sizeof_binl(len)

See also

mp_encode_strl

MP_PROTO char* mp_encode_bool (char * data, bool val)

Encode a bool value val. It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
val - a bool

Returns

data + mp_sizeof_bool(val)

See also

An usage example

mp_sizeof_bool()

MP_PROTO char* mp_encode_double (char * data, double num)

Encode a double num. It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
num - a float

Returns

data + mp_sizeof_double(num)

See also

An usage example

mp_sizeof_double()

MP_PROTO char* mp_encode_ext (char * data, int8_t type, const char * str, uint32_t len)

Encode extension data of length len. The function is equivalent to mp_encode_extl() + memcpy.

Parameters

data - a buffer
type - extension type to encode
str - a pointer to extension data
len - a extension data length

Returns

data + mp_sizeof_ext(len) == data + mp_sizeof_extl(len) + len

See also

mp_encode_strl

MP_PROTO char* mp_encode_extl (char * data, int8_t type, uint32_t len)

Encode extension header with type and value length len. The value must be encoded after the header.

Returns

data + mp_sizeof_extl(size)

MP_PROTO char* mp_encode_float (char * data, float num)

Encode a float num. It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
num - a float

Returns

data + mp_sizeof_float(num)

See also

mp_sizeof_float()

An usage example

MP_PROTO char* mp_encode_int (char * data, int64_t num)

Encode a signed integer num. It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
num - a number

Returns

data + mp_sizeof_int(num)

See also

An usage example

mp_sizeof_int()

Precondition

num < 0

MP_PROTO char* mp_encode_map (char * data, uint32_t size)

Encode a map header of size elements. All map key-value pairs must be encoded after the header.

Example usage:

char buf[1024];

// Encode
char *w = buf;
w = mp_encode_map(b, 2);
w = mp_encode_str(b, "key1", 4);
w = mp_encode_str(b, "value1", 6);
w = mp_encode_str(b, "key2", 4);
w = mp_encode_str(b, "value2", 6);

// Decode
const char *r = buf;
uint32_t size = mp_decode_map(&r);
for (uint32_t i = 0; i < size; i++) {
     // Use switch(mp_typeof(**r)) to support more types
    uint32_t key_len, val_len;
    const char *key = mp_decode_str(&r, key_len);
    const char *val = mp_decode_str(&r, val_len);
}
assert (r == w);

It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
size - a number of key/value pairs

Returns

data + mp_sizeof_map(size)

See also

mp_sizeof_map

MP_PROTO char* mp_encode_nil (char * data)

Encode the nil value. It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer

Returns

data + mp_sizeof_nil()

See also

An usage example

mp_sizeof_nil()

MP_PROTO char* mp_encode_str (char * data, const char * str, uint32_t len)

Encode a string of length len. The function is equivalent to mp_encode_strl() + memcpy.

Parameters

data - a buffer
str - a pointer to string data
len - a string length

Returns

data + mp_sizeof_str(len) == data + mp_sizeof_strl(len) + len

See also

mp_encode_strl

MP_PROTO char* mp_encode_strl (char * data, uint32_t len)

Encode a string header of length len. The function encodes MsgPack header (only header) for a string of length len. You should append actual string data to the buffer manually after encoding the header (exactly len bytes without trailing '\0').

This approach is very useful for cases when the total length of the string is known in advance, but the string data is not stored in a single continuous buffer (e.g. network packets).

It is your responsibility to ensure that data has enough space. Usage example:

char buffer[1024];
char *b = buffer;
b = mp_encode_strl(b, hdr.total_len);
char *s = b;
memcpy(b, pkt1.data, pkt1.len);
b += pkt1.len;
// get next packet
memcpy(b, pkt2.data, pkt2.len);
b += pkt2.len;
// get next packet
memcpy(b, pkt1.data, pkt3.len);
b += pkt3.len;

// Check that all data was received
assert(hdr.total_len == (uint32_t) (b - s))

Hint: you can dynamically reallocate the buffer during the process.

Parameters

data - a buffer
len - a string length

Returns

data + mp_sizeof_strl(len)

See also

mp_sizeof_strl()

MP_PROTO char* mp_encode_uint (char * data, uint64_t num)

Encode an unsigned integer num. It is your responsibility to ensure that data has enough space.

Parameters

data - a buffer
num - a number

Returns

data + mp_sizeof_uint(num)

See also

An usage example

mp_sizeof_uint()

size_t mp_format (char * data, size_t data_size, const char * format,  ...)

Encode a sequence of values according to format string. Example: mp_format(buf, sz, '[%d {%d%s%d%s}]', 42, 0, 'false', 1, 'true'); to get a msgpack array of two items: number 42 and map (0->'false, 2->'true") Does not write items that don't fit to data_size argument.

Parameters

data - a buffer
data_size - a buffer size
format - zero-end string, containing structure of resulting msgpack and types of next arguments. Format can contain '[' and ']' pairs, defining arrays, '{' and '}' pairs, defining maps, and format specifiers, described below: d, i - int u - unsigned int ld, li - long lu - unsigned long lld, lli - long long llu - unsigned long long hd, hi - short hu - unsigned short hhd, hhi - char (as number) hhu - unsigned char (as number) f - float lf - double b - bool s - zero-end string %.*s - string with specified length p - MsgPack data %.*p - MsgPack data with specified length %% is ignored smthelse assert and undefined behaviour NIL - a nil value all other symbols are ignored.

Returns

the number of requred bytes.

Return values

> data_size means that is not enough space and whole msgpack was not encoded.

int mp_fprint (FILE * file, const char * data)

print MsgPack data file using JSON-like format. MP_EXT is printed as a non-standard JSON 'list':

(extension: type <type>, len <len>)

For example:

(extension: type 10, len 35)

Type is the MP_EXT type. Length is of the MP_EXT body, not counting its header. Since the 'list' and what is in it is not a standard JSON, printing a MessagePack buffer, having MP_EXT in it, may lead to an invalid JSON.

However MP_EXT may be printed differently in case a proper virtual serializer was installed.

See also

mp_fprint_ext_f.

Parameters

file - pointer to file (or NULL for stdout)
data - pointer to buffer containing msgpack object

Return values

>=0 - the number of bytes printed
-1 - error

See also

fprintf()

int mp_fprint_ext_default (FILE * file, const char ** data, int depth)

Default MP_EXT serializer into a file. Skips the object, ignores all the other arguments, and writes.

(extension: type <type>, len <len>)
See also

mp_fprint().

int mp_fprint_recursion (FILE * file, const char ** data, int depth)

Print MsgPack data to file using JSON-like format. Works exactly like.

See also

mp_fprint(), but allows to specify max depth, and changes data parameter. Intended to be used for MsgPack serialization recursion.

MP_PROTO bool mp_frame_advance (struct mp_frame * frame)

Advance idx attribute of the frame.

Parameters

frame - the frame pointer to operate with.

Return values

true when mp_frame::idx is less than mp_frame::count. false otherwise.

MP_PROTO void mp_next (const char ** data)

Skip one element in a packed data. The function is faster than mp_typeof + mp_decode_XXX() combination. For arrays and maps the function also skips all members. For strings and binstrings the function also skips the string data.

Usage example:

char buf[1024];

char *w = buf;
// First MsgPack object
w = mp_encode_uint(w, 10);

// Second MsgPack object
w = mp_encode_array(w, 4);
   w = mp_encode_array(w, 2);
        // Begin of an inner array
        w = mp_encode_str(w, "second inner 1", 14);
        w = mp_encode_str(w, "second inner 2", 14);
        // End of an inner array
   w = mp_encode_str(w, "second", 6);
   w = mp_encode_uint(w, 20);
   w = mp_encode_bool(w, true);

// Third MsgPack object
w = mp_encode_str(w, "third", 5);
// EOF

const char *r = buf;

// First MsgPack object
assert(mp_typeof(**r) == MP_UINT);
mp_next(&r); // skip the first object

// Second MsgPack object
assert(mp_typeof(**r) == MP_ARRAY);
mp_decode_array(&r);
    assert(mp_typeof(**r) == MP_ARRAY); // inner array
    mp_next(&r); // -->> skip the entire inner array (with all members)
    assert(mp_typeof(**r) == MP_STR); // second
    mp_next(&r);
    assert(mp_typeof(**r) == MP_UINT); // 20
    mp_next(&r);
    assert(mp_typeof(**r) == MP_BOOL); // true
    mp_next(&r);

// Third MsgPack object
assert(mp_typeof(**r) == MP_STR); // third
mp_next(&r);

assert(r == w); // EOF
Parameters

data - the pointer to a buffer

Postcondition

*data = *data + mp_sizeof_TYPE() where TYPE is mp_typeof(**data)

MP_PROTO int mp_read_double (const char ** data, double * ret)

Decode a floating point value as double from MsgPack data.

Parameters

data - the pointer to a buffer
ret - the pointer to save a result

Return values

0 on success
-1 if underlying mp type is not MP_INT, MP_UINT, MP_FLOAT, or MP_DOUBLE
-1 if the result can't be stored in double

MP_PROTO int mp_read_int32 (const char ** data, int32_t * ret)

Decode an integer value as int32_t from MsgPack data.

Parameters

data - the pointer to a buffer
ret - the pointer to save a result

Return values

0 on success
-1 if underlying mp type is not MP_INT or MP_UINT
-1 if the result can't be stored in int32_t

MP_PROTO int mp_read_int64 (const char ** data, int64_t * ret)

Decode an integer value as int64_t from MsgPack data.

Parameters

data - the pointer to a buffer
ret - the pointer to save a result

Return values

0 on success
-1 if underlying mp type is not MP_INT or MP_UINT
-1 if the result can't be stored in int64_t

MP_PROTO MP_CONST uint32_t mp_sizeof_array (uint32_t size)

Calculate exact buffer size needed to store an array header of size elements. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.

Parameters

size - a number of elements

Returns

buffer size in bytes (max is 5)

MP_PROTO MP_CONST uint32_t mp_sizeof_bin (uint32_t len)

Equivalent to mp_sizeof_binl(len) + len.

Parameters

len - a string length

Returns

size in chars (max is 5 + len)

MP_PROTO MP_CONST uint32_t mp_sizeof_binl (uint32_t len)

Calculate exact buffer size needed to store a binstring header of length num. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.

Parameters

len - a string length

Returns

size in chars (max is 5)

MP_PROTO MP_CONST uint32_t mp_sizeof_bool (bool val)

Calculate exact buffer size needed to store a boolean value. The return value is always 1. The function was added to provide integrity of the library.

Returns

buffer size in bytes (always 1)

MP_PROTO MP_CONST uint32_t mp_sizeof_double (double num)

Calculate exact buffer size needed to store a double num. The return value is either 5 or 9. The function was added to provide integrity of the library. For performance reasons you can preallocate buffer for maximum size without calling the function.

Parameters

num - a double

Returns

buffer size in bytes (5 or 9)

MP_PROTO uint32_t mp_sizeof_ext (uint32_t len)

Equivalent to mp_sizeof_extl(len) + len.

Parameters

len - a extension data length

Returns

size in chars (max is 6 + len)

MP_PROTO uint32_t mp_sizeof_extl (uint32_t len)

calculate exact buffer size needed to store ext header for a value of length len.

Parameters

len value length in bytes.

Return values

buffer size in bytes

MP_PROTO MP_CONST uint32_t mp_sizeof_float (float num)

Calculate exact buffer size needed to store a float num. The return value is always 5. The function was added to provide integrity of the library.

Parameters

num - a float

Returns

buffer size in bytes (always 5)

MP_PROTO MP_CONST uint32_t mp_sizeof_int (int64_t num)

Calculate exact buffer size needed to store an integer num. Maximum return value is 9. For performance reasons you can preallocate buffer for maximum size without calling the function.

Parameters

num - a number

Returns

buffer size in bytes (max is 9)

Precondition

num < 0

MP_PROTO MP_CONST uint32_t mp_sizeof_map (uint32_t size)

Calculate exact buffer size needed to store a map header of size elements. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.

Parameters

size - a number of elements

Returns

buffer size in bytes (max is 5)

MP_PROTO MP_CONST uint32_t mp_sizeof_nil (void)

Calculate exact buffer size needed to store the nil value. The return value is always 1. The function was added to provide integrity of the library.

Returns

buffer size in bytes (always 1)

MP_PROTO MP_CONST uint32_t mp_sizeof_str (uint32_t len)

Equivalent to mp_sizeof_strl(len) + len.

Parameters

len - a string length

Returns

size in chars (max is 5 + len)

MP_PROTO MP_CONST uint32_t mp_sizeof_strl (uint32_t len)

Calculate exact buffer size needed to store a string header of length num. Maximum return value is 5. For performance reasons you can preallocate buffer for maximum size without calling the function.

Parameters

len - a string length

Returns

size in chars (max is 5)

MP_PROTO MP_CONST uint32_t mp_sizeof_uint (uint64_t num)

Calculate exact buffer size needed to store an integer num. Maximum return value is 9. For performance reasons you can preallocate buffer for maximum size without calling the function. Example usage:

char **data = ...;
char *end = *data;
my_buffer_ensure(mp_sizeof_uint(x), &end);
// my_buffer_ensure(9, &end);
mp_encode_uint(buffer, x);
Parameters

num - a number

Returns

buffer size in bytes (max is 9)

int mp_snprint (char * buf, int size, const char * data)

format MsgPack data to buf using JSON-like format. Behaves the same as

See also

mp_fprint(), but with snprintf() semantics.

mp_fprint()

Parameters

buf - buffer to use
size - buffer size. This function write at most size bytes (including the terminating null byte ('\0').
data - pointer to buffer containing msgpack object

Return values

<size - the number of characters printed (excluding the null byte)
>=size - the number of characters (excluding the null byte), which would have been written to the final string if enough space had been available.
-1 - error

See also

snprintf()

int mp_snprint_ext_default (char * buf, int size, const char ** data, int depth)

Default MP_EXT serializer into a string. Skips the object, ignores all the other arguments, and prints.

(extension: type <type>, len <len>)
See also

mp_snprint().

int mp_snprint_recursion (char * buf, int size, const char ** data, int depth)

Format MsgPack data to buf using JSON-like format. Works exactly like.

See also

mp_snprint(), but allows to specify max depth, and changes data parameter. Intended to be used for MsgPack serialization recursion.

MP_PROTO void mp_stack_create (struct mp_stack * stack, int size, struct mp_frame * frames)

Initialize mp_stack stack with specified size size and user-allocated array frames. The frames allocation must have at least size mp_frame items.

Parameters

stack - the pointer to a mp_stack to initialize.
size - stack size, count of stack::frames to use.
frames - mp_frame preallocated array of size size of struct mp_frame items

MP_PROTO bool mp_stack_is_empty (struct mp_stack * stack)

Test if mp_stack stack is empty.

Parameters

stack - the pointer to a mp_stack to a stack to test.

Return values

true if mp_stack is empty, false otherwise.

MP_PROTO bool mp_stack_is_full (struct mp_stack * stack)

Test if mp_stack stack is full.

Parameters

stack - the pointer to a mp_stack to a stack to test.

Return values

true if mp_stack is full, false otherwise.

MP_PROTO void mp_stack_pop (struct mp_stack * stack)

Pop the top mp_stack stack frame.

Parameters

stack - the pointer to a mp_stack to operate with.

Precondition

mp_stack_is_empty(stack) == false

MP_PROTO void mp_stack_push (struct mp_stack * stack, enum mp_type type, int count)

Construct a new mp_frame and push it on to mp_stack stack.

Parameters

stack - the pointer to a stack to operate with.
type - the type of mp_frame to create.
count - the count of itemes of mp_frame to create.

Precondition

mp_stack_is_full(stack) == false

MP_PROTO struct mp_frame* mp_stack_top (struct mp_stack * stack)

Return the top mp_stack stack frame.

Parameters

stack - the pointer to a mp_stack to operate with.

Precondition

mp_stack_is_empty(stack) == false

MP_PROTO MP_PURE enum mp_type mp_typeof (const char c)

Determine MsgPack type by a first byte c of encoded data. Example usage:

assert(MP_ARRAY == mp_typeof(0x90));
Parameters

c - a first byte of encoded data

Returns

MsgPack type

size_t mp_vformat (char * data, size_t data_size, const char * format, va_list args)

mp_format variation, taking variable argument list Example: va_list args; va_start(args, fmt); mp_vformat(data, data_size, fmt, args); va_end(args);

See also

mp_format()

Author

Generated automatically by Doxygen for MsgPuck from the source code.

Info

Tue Jan 26 2021 MsgPuck