--- name: "msgpuck.h" section: "3" platform: "linux" package: "libmsgpuck-dev" version: "1.0.3-1.2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/msgpuck.h" --- # msgpuck.h(3) MsgPuck is a simple and efficient MsgPack encoder/decoder library in a single self-contained file. ## NAME msgpuck.h - MsgPuck is a simple and efficient MsgPack encoder/decoder library in a single self-contained file. ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### 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 enum **mp\_type** **mp\_typeof** (const char c)\ Determine MsgPack type by a first byte *c* of encoded data. MP\_PROTO 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 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 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 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\_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 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 ptrdiff\_t **mp\_check\_uint** (const char \*cur, const char \*end)\ Check that *cur* buffer has enough bytes to decode an uint. MP\_PROTO 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 int **mp\_compare\_uint** (const char \*data\_a, const char \*data\_b)\ Compare two packed unsigned integers. MP\_PROTO 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 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 ptrdiff\_t **mp\_check\_float** (const char \*cur, const char \*end)\ Check that *cur* buffer has enough bytes to decode a float. MP\_PROTO 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 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 uint32\_t **mp\_sizeof\_str** (uint32\_t len)\ Equivalent to mp\_sizeof\_strl(*len*) + *len*. MP\_PROTO 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 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. MP\_PROTO 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.* MP\_PROTO 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); MP\_PROTO int **mp\_fprint** (FILE \*file, const char \*data)\ print to *file* msgpacked data in JSON format. MP\_EXT is printed as 'EXT' only MP\_PROTO 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 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 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 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 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 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 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*. ## 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 ### 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 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 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 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 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 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 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 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 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 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 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 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 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\_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()** ### MP\_PROTO 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 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. ### MP\_PROTO int mp\_fprint (FILE \* file, const char \* data) print to *file* msgpacked data in JSON format. MP\_EXT is printed as 'EXT' only **Parameters** *file* - pointer to file (or NULL for stdout) \ *data* - pointer to buffer containing msgpack object **Return values** *0* - success \ *-1* - wrong msgpack ### 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 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 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 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 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 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\_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 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 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 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 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 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 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) ### MP\_PROTO 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 ### MP\_PROTO 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.