MsgPuck
Enumerations | Functions | Variables
msgpuck.h File Reference

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

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

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

 __attribute__ ((pure)) enum mp_type mp_typeof(const char c)
 Determine MsgPack type by a first byte c of encoded data. More...
 
 __attribute__ ((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. More...
 
char * mp_encode_array (char *data, uint32_t size)
 Encode an array header of size elements. More...
 
uint32_t mp_decode_array (const char **data)
 Decode an array header from MsgPack data. More...
 
char * mp_encode_map (char *data, uint32_t size)
 Encode a map header of size elements. More...
 
uint32_t mp_decode_map (const char **data)
 Decode a map header from MsgPack data. More...
 
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. More...
 
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. More...
 
uint64_t mp_decode_uint (const char **data)
 Decode an unsigned integer from MsgPack data. More...
 
int64_t mp_decode_int (const char **data)
 Decode a signed integer from MsgPack data. More...
 
char * mp_encode_float (char *data, float num)
 Encode a float num. It is your responsibility to ensure that data has enough space. More...
 
char * mp_encode_double (char *data, double num)
 Encode a double num. It is your responsibility to ensure that data has enough space. More...
 
float mp_decode_float (const char **data)
 Decode a float from MsgPack data. More...
 
double mp_decode_double (const char **data)
 Decode a double from MsgPack data. More...
 
char * mp_encode_strl (char *data, uint32_t len)
 Encode a string header of length len. More...
 
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. More...
 
char * mp_encode_binl (char *data, uint32_t len)
 Encode a binstring header of length len. See mp_encode_strl() for more details. More...
 
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. More...
 
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. More...
 
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); More...
 
uint32_t mp_decode_strl (const char **data)
 Decode a length of a string from MsgPack data. More...
 
const char * mp_decode_str (const char **data, uint32_t *len)
 Decode a string from MsgPack data. More...
 
uint32_t mp_decode_binl (const char **data)
 Decode a length of a binstring from MsgPack data. More...
 
const char * mp_decode_bin (const char **data, uint32_t *len)
 Decode a binstring from MsgPack data. More...
 
char * mp_encode_nil (char *data)
 Encode the nil value. It is your responsibility to ensure that data has enough space. More...
 
void mp_decode_nil (const char **data)
 Decode the nil value from MsgPack data. More...
 
char * mp_encode_bool (char *data, bool val)
 Encode a bool value val. It is your responsibility to ensure that data has enough space. More...
 
bool mp_decode_bool (const char **data)
 Decode a bool value from MsgPack data. More...
 
void mp_next (const char **data)
 Skip one element in a packed data. More...
 
int mp_check (const char **data, const char *end)
 Equivalent to mp_next() but also validates MsgPack in data. More...
 

Variables

const char * end
 
const char * data_b
 

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 define MP_SOURCE 1 before #include <msgpuck.h> in a single compilation unit. This module will be used to store non-inlined versions of functions and global tables.

Function Documentation

__attribute__ ( (pure)  ) const

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

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

Check that cur buffer has enough bytes to decode nil.

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

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

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

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

Compare two packed unsigned integers.

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

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

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

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

Example usage:

1 assert(MP_ARRAY == mp_typeof(0x90));
Parameters
c- a first byte of encoded data
Returns
MsgPack type
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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

The function is faster than two mp_decode_uint() calls.

Parameters
data_aunsigned int a
data_bunsigned int b
Return values
<0 when a < b
0when a == b
>0 when a > b
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
Parameters
curbuffer
endend 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
__attribute__ ( (const)  )

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.

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.

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.

Equivalent to mp_sizeof_binl(len) + 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.

Equivalent to mp_sizeof_strl(len) + 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.

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.

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.

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.

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:

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)
1 char **data = ...;
2 char *end = *data;
3 my_buffer_ensure(mp_sizeof_uint(x), &end);
4 // my_buffer_ensure(9, &end);
5 mp_encode_uint(buffer, x);
Parameters
num- a number
Returns
buffer size in bytes (max is 9)
Parameters
num- a number
Returns
buffer size in bytes (max is 9)
Precondition
num < 0
Parameters
num- a float
Returns
buffer size in bytes (always 5)
Parameters
num- a double
Returns
buffer size in bytes (5 or 9)
Parameters
len- a string length
Returns
size in chars (max is 5)
Parameters
len- a string length
Returns
size in chars (max is 5 + len)
buffer size in bytes (always 1)
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
0when 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()
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
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
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
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)
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)
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)
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)
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
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()
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
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
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)
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:

1 // Encode
2 char buf[1024];
3 char *w = buf;
4 w = mp_encode_array(w, 2)
5 w = mp_encode_uint(w, 10);
6 w = mp_encode_uint(w, 15);
7 
8 // Decode
9 const char *r = buf;
10 uint32_t size = mp_decode_array(&r);
11 for (uint32_t i = 0; i < size; i++) {
12  uint64_t val = mp_decode_uint(&r);
13 }
14 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
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
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
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()
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()
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
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
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:

1 char buf[1024];
2 
3 // Encode
4 char *w = buf;
5 w = mp_encode_map(b, 2);
6 w = mp_encode_str(b, "key1", 4);
7 w = mp_encode_str(b, "value1", 6);
8 w = mp_encode_str(b, "key2", 4);
9 w = mp_encode_str(b, "value2", 6);
10 
11 // Decode
12 const char *r = buf;
13 uint32_t size = mp_decode_map(&r);
14 for (uint32_t i = 0; i < size; i++) {
15  // Use switch(mp_typeof(**r)) to support more types
16  uint32_t key_len, val_len;
17  const char *key = mp_decode_str(&r, key_len);
18  const char *val = mp_decode_str(&r, val_len);
19 }
20 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
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()
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
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:

1 char buffer[1024];
2 char *b = buffer;
3 b = mp_encode_strl(b, hdr.total_len);
4 char *s = b;
5 memcpy(b, pkt1.data, pkt1.len)
6 b += pkt1.len;
7 // get next packet
8 memcpy(b, pkt2.data, pkt2.len)
9 b += pkt2.len;
10 // get next packet
11 memcpy(b, pkt1.data, pkt3.len)
12 b += pkt3.len;
13 
14 // Check that all data was received
15 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()
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 %% is ignored %<smth else>=""> 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.
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:

1 char buf[1024];
2 
3 char *w = buf;
4 // First MsgPack object
5 w = mp_encode_uint(w, 10);
6 
7 // Second MsgPack object
8 w = mp_encode_array(w, 4);
9  w = mp_encode_array(w, 2);
10  // Begin of an inner array
11  w = mp_encode_str(w, "second inner 1", 14);
12  w = mp_encode_str(w, "second inner 2", 14);
13  // End of an inner array
14  w = mp_encode_str(w, "second", 6);
15  w = mp_encode_uint(w, 20);
16  w = mp_encode_bool(w, true);
17 
18 // Third MsgPack object
19 w = mp_encode_str(w, "third", 5);
20 // EOF
21 
22 const char *r = buf;
23 
24 // First MsgPack object
25 assert(mp_typeof(**r) == MP_UINT);
26 mp_next(&r); // skip the first object
27 
28 // Second MsgPack object
29 assert(mp_typeof(**r) == MP_ARRAY);
30 mp_decode_array(&r);
31  assert(mp_typeof(**r) == MP_ARRAY); // inner array
32  mp_next(&r); // -->> skip the entire inner array (with all members)
33  assert(mp_typeof(**r) == MP_STR); // second
34  mp_next(&r);
35  assert(mp_typeof(**r) == MP_UINT); // 20
36  mp_next(&r);
37  assert(mp_typeof(**r) == MP_BOOL); // true
38  mp_next(&r);
39 
40 // Third MsgPack object
41 assert(mp_typeof(**r) == MP_STR); // third
42 mp_next(&r);
43 
44 assert(r == w); // EOF
Parameters
data- the pointer to a buffer
Postcondition
*data = *data + mp_sizeof_TYPE() where TYPE is mp_typeof(**data)
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()