msgpuck.h File Reference

MsgPack data types.

Definition at line 312 of file msgpuck.h.

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:

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

Parameters:

c	- a first byte of encoded data

Returns:

MsgPack type

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

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

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

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

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

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

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

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

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

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

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

Calculate exact buffer size needed to store an array header of size elements.

Calculate exact buffer size needed to store a boolean value.

Calculate exact buffer size needed to store the nil value.

Equivalent to mp_sizeof_binl(len) + len.

Calculate exact buffer size needed to store a binstring header of length num.

Equivalent to mp_sizeof_strl(len) + len.

Calculate exact buffer size needed to store a string header of length num.

Calculate exact buffer size needed to store a double num.

Calculate exact buffer size needed to store a float num.

Calculate exact buffer size needed to store an integer num.

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)

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)

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

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)

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)

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)

Parameters:

len	- a string length

Returns:

size in chars (max is 5 + len)

The return value is always 1. The function was added to provide integrity of the library.

Returns:

buffer size in bytes (always 1)

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

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

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

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

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)

Decode a double from MsgPack data.

Parameters:

data	- the pointer to a buffer

Returns:

a double

Postcondition:

*data = *data + mp_sizeof_double(retval)

Decode a float from MsgPack data.

Parameters:

data	- the pointer to a buffer

Returns:

a float

Postcondition:

*data = *data + mp_sizeof_float(retval)

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)

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

Decode the nil value from MsgPack data.

Parameters:

data	- the pointer to a buffer

Postcondition:

*data = *data + mp_sizeof_nil()

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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.

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