Zakero_MessagePack.h File Reference

Zakero MessagePack. More...

Include dependency graph for Zakero_MessagePack.h:

Go to the source code of this file.

Classes
struct	zakero::messagepack::Array
	An array of Objects. More...
class	zakero::messagepack::ErrorCategory_
	MessagePack Error Categories. More...
struct	zakero::messagepack::Ext
	Extension Data. More...
struct	zakero::messagepack::Map
	A Key/Value collection of Objects. More...
struct	zakero::messagepack::Object
	A Data Object. More...

Macros
#define	ZAKERO_MESSAGEPACK_IMPLEMENTATION
	Activate the implementation code. More...

Functions
Object	zakero::messagepack::deserialize (const std::vector< uint8_t > &data) noexcept
	Deserialize MessagePack data. More...
Object	zakero::messagepack::deserialize (const std::vector< uint8_t > &data, size_t &index) noexcept
	Deserialize MessagePack data. More...
Object	zakero::messagepack::deserialize (const std::vector< uint8_t > &data, size_t &index, std::error_code &error) noexcept
	Deserialize MessagePack data. More...
Object	zakero::messagepack::deserialize (const std::vector< uint8_t > &data, std::error_code &error) noexcept
	Deserialize MessagePack data. More...
bool	zakero::messagepack::extensionTimestampCheck (const Object &object) noexcept
	Timestamp Extension Check. More...
struct timespec	zakero::messagepack::extensionTimestampConvert (const Object &object) noexcept
	Convert MessagePack Timestamp extension into a struct timespec. More...
Object	zakero::messagepack::extensionTimestampConvert (const struct timespec &ts) noexcept
	Convert a struct timespec into a MessagePack Timestamp extension. More...
bool	operator!= (const zakero::messagepack::Object &lhs, const zakero::messagepack::Object &rhs) noexcept
	Compare two Objects for inequality. More...
std::ostream &	operator<< (std::ostream &stream, const zakero::messagepack::Array &array) noexcept
	OStream operator. More...
std::ostream &	operator<< (std::ostream &stream, const zakero::messagepack::Ext &ext) noexcept
	OStream operator. More...
std::ostream &	operator<< (std::ostream &stream, const zakero::messagepack::Map &map) noexcept
	OStream operator. More...
std::ostream &	operator<< (std::ostream &stream, const zakero::messagepack::Object &object) noexcept
	OStream operator. More...
bool	operator== (const zakero::messagepack::Object &lhs, const zakero::messagepack::Object &rhs) noexcept
	Compare two Objects for equality. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Array &array) noexcept
	Serialize Array data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Array &array, std::error_code &error) noexcept
	Serialize Array data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Ext &ext) noexcept
	Serialize Ext data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Ext &ext, std::error_code &error) noexcept
	Serialize Ext data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Map &map) noexcept
	Serialize Map data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Map &map, std::error_code &error) noexcept
	Serialize Map data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Object &object) noexcept
	Serialize Object data. More...
std::vector< uint8_t >	zakero::messagepack::serialize (const Object &object, std::error_code &error) noexcept
	Serialize Object data. More...
std::string	zakero::messagepack::to_string (const messagepack::Array &array) noexcept
	Convert to a JSON formatted string. More...
std::string	zakero::messagepack::to_string (const messagepack::Ext &ext) noexcept
	Convert to a JSON formatted string. More...
std::string	zakero::messagepack::to_string (const messagepack::Map &map) noexcept
	Convert to a JSON formatted string. More...
std::string	zakero::messagepack::to_string (const messagepack::Object &object) noexcept
	Convert to a JSON formatted string. More...

Variables
ErrorCategory_	zakero::messagepack::ErrorCategory
	A single instance. More...

Format Value Masks
#define	X(name_, val_, mesg_)
	Generate Code.
#define	X(name_, val_, mesg_)
	Generate Code.
#define	X(type_, id_, mask_, size_, text_)
	Generate Code.
#define	X(type_, id_, mask_, size_, text_)
	Generate Code.
#define	X(type_, id_, mask_, size_, text_)
	Generate Code.
#define	X(type_, id_, mask_, size_, text_)
	Generate Code.

Detailed Description

API	Dependencies	TL;DR	What Is It?	Why Use It?	How To Use It?	Version

The Zakero_MessagePack will serialize and deserialize data using the MessagePack specification.

Dependencies

• None

TL;DR:

This library makes it very easy to use the MessagePack data format.

To use:

1. Add the implementation to a source code file:

   #define ZAKERO_MESSAGEPACK_IMPLEMENTATION
   #include "Zakero_MessagePack.h"

2. Add the library to where it is used:

   #include "Zakero_MessagePack.h"

What Is It?

The Zakero_MessagePack library provides a way to serialize data for storage or transport over a network. Deserialization is also available so that the data may be accessed. The MessagePack specification provides a format that allows many different types of data to be packed with very little overhead.

Why Use It?

There are many libraries available to do the same thing, however the Zakero_MessagePack library offers the following:

Benefits

• Single Header Library
• Small compile size
• Easy to add data
• Access to existing data
• Modify existing data
• Uses native C++ types

Draw Backs

• Memory Usage: Serialization makes a copy of the contents

Instead of attempting to interface with other libraries or provide a dynamic interface, basic C++ types are used. It is expected that this approach will make using the library with other code bases easier and less volatile.

How To Use It?

Step 0

Your compiler must support at least the C++20 standard. The location of the Zakero_MessagePack.h header files must be in your compiler's include path.

Step 1

The first step is to select which C++ source code file will contain the Zakero MessagePack implementation. Once the location has been determined, add the following to that file:

#define ZAKERO_MESSAGEPACK_IMPLEMENTATION
#include "Zakero_MessagePack.h"

The macro ZAKERO_MESSAGEPACK_IMPLEMENTATION tells the header file to include the implementation of the MessagePack.

In all other files that will use the MessagePack, they need to include the header.

#include "Zakero_MessagePack.h"

Step 2

Create MessagePack Objects to store data. Use containers to store more objects. Then serialize the data.
MessagePack Objects can also be created by deserializing data.

Add data manually

zakero::messagepack::Array array;
 
zakero::messagepack::Object the_answer = Object{uint64_t(42)};
array.append(the_answer);
array.append(Object{true});
array.append({std::string("Hello, World!")});

Deserialize data

std::vector<uint8_t> data = load_data();
 
zakero::messagepack::Object object = zakero::messagepack::deserialize(data);

The data in the MessagePack can be modified:

if(object.isArray())
{
     zakero::messagepack::Array& array = object.asArray();
     array.object(2) = {std::string("Good Bye!")};
}

Then the MessagePack can be (re)serialized:

data = zakero::messagepack::serialize(object);

Version

v0.9.1

• Beta Release 2
• Restricted Map key types to improve performance.

v0.9.0

• Beta Release
• Added error checks to the deserializer

v0.3.1

• Fixed issues found by CLang++

v0.3.0

• Alpha Release
• Added support for Ext
• Added support for Maps
• Added support for the Timestamp extension
• Complete rewrite

v0.2.0

• Added support for Arrays

v0.1.0

• The initial implementation

Copyright

Mozilla Public License v2

Author

Andrew "Zakero" Moore

• Original Author

Macro Definition Documentation

ZAKERO_MESSAGEPACK_IMPLEMENTATION

#define ZAKERO_MESSAGEPACK_IMPLEMENTATION

Defining this macro will cause the zakero::MessagePack implementation to be included. This should only be done once, since compiler and/or linker errors will typically be generated if more than a single implementation is found.

Note

It does not matter if the macro is given a value or not, only its existence is checked.

Function Documentation

deserialize() [1/4]

Object zakero::messagepack::deserialize ( const std::vector< uint8_t > &  data )

noexcept

The packed vector of data will be converted into an object that can be queried and used.

Example

std::vector<uint8_t> command_result = get_reply(command_id);
 
zakero::messagepack::Object object;
object = zakero::messagepack::deserialize(command_result);
if(object.isArray() == false)
{
        writeError(ERROR_INVALID_COMMAND_RESULT);
 
        return;
}
 
zakero::messagepack::Array& array = object.asArray();
 
constexpr size_t success_index = 1;
constexpr size_t result_code_index = 2;
if(array(success_index).boolean == true)
{
        writeError(array(error_code_index).as<int64_t>());
}

Returns

The MessagePack Object.

Parameters

data	The packed data

deserialize() [2/4]

Object zakero::messagepack::deserialize ( const std::vector< uint8_t > &  data, size_t &  index  )

noexcept

The packed vector of data will be converted into an object that can be queried and used.

Example

std::vector<uint8_t> command_result = get_reply(command_id);
 
zakero::messagepack::Object object;
size_t                      index;
object = zakero::messagepack::deserialize(command_result, index);
if(object.isArray() == false)
{
     writeError(ERROR_INVALID_COMMAND_RESULT);
 
        return;
}
 
zakero::messagepack::Array& array = object.asArray();
 
constexpr size_t error_index = 1;
constexpr size_t error_code_index = 2;
if(array(error_index).as<bool>() == true)
{
        writeError(array(error_code_index).as<int64_t>());
}

Returns

The MessagePack Object.

Parameters

data	The packed data
index	The starting index

deserialize() [3/4]

Object zakero::messagepack::deserialize ( const std::vector< uint8_t > &  data, size_t &  index, std::error_code &  error  )

noexcept

The packed vector of data will be converted into an object that can be queried and used.

Example

std::vector<uint8_t> command_result = get_reply(command_id);
 
zakero::messagepack::Object object;
size_t index;
std::error_code error;
object = zakero::messagepack::deserialize(command_result, index, error);
if(object.isArray() == false)
{
     writeError(ERROR_INVALID_COMMAND_RESULT, error);
 
        // index points to the end of the "object"
        crashAnalysis(&command_result[index]);
 
        return;
}
 
zakero::messagepack::Array& array = object.asArray();
 
constexpr size_t error_index = 1;
constexpr size_t error_code_index = 2;
if(array(error_index).as<bool>() == true)
{
        writeError(array(error_code_index).as<int64_t>());
}

Returns

The MessagePack Object.

Parameters

data	The packed data
index	The starting index
error	The error code

deserialize() [4/4]

Object zakero::messagepack::deserialize ( const std::vector< uint8_t > &  data, std::error_code &  error  )

noexcept

The packed vector of data will be converted into an object that can be queried and used.

Example

std::vector<uint8_t> command_result = get_reply(command_id);
 
zakero::messagepack::Object object;
std::error_code             error;
object = zakero::messagepack::deserialize(command_result, error);
if(error)
{
     writeError(ERROR_INVALID_COMMAND_RESULT);
 
        return;
}
 
zakero::messagepack::Array& array = object.asArray();
 
constexpr size_t error_index = 1;
constexpr size_t error_code_index = 2;
if(array(error_index).as<bool>() == true)
{
        writeError(array(error_code_index).as<int64_t>());
}

Returns

The MessagePack Object.

Parameters

data	The packed data
error	The error code

extensionTimestampCheck()

bool zakero::messagepack::extensionTimestampCheck ( const Object &  object )

noexcept

Use this method to determine if the object is a MessagePack Timestamp Extension.

Example

std::vector<uint8_t> data = getSerializedData();
zakero::messagepack::Object obj = zakero::messagepack::deserialize(data);
 
if(zakero::messagepack::extensionTimestampCheck(obj) == false)
{
        return ERROR_INVALID_TIMESTAMP;
}

Return values

true	The object is a Timestamp extension.
false	The object is not a Timestamp extension.

Parameters

object

The Ext to check.

extensionTimestampConvert() [1/2]

struct timespec zakero::messagepack::extensionTimestampConvert ( const Object &  object )

noexcept

Conversion from Object to struct timespec is performed by this method. If the provided object is not a valid Timestamp extension then an empty struct timespec will be returned.

Example

std::vector<uint8_t> data = getSerializedData();
zakero::messagepack::Object obj = zakero::messagepack::deserialize(data);
struct timespec ts = zakero::messagepack::extensionTimestampConvert(obj);
 
char buf[128];
std::strftime(buf, sizeof(buf), "%D %T", std::gmtime(&ts.tv_sec));
std::printf("Time: %s.%09ld UTC\n", buf, ts.tv_nsec);

Returns

A struct timespec.

Parameters

object

The Ext data.

extensionTimestampConvert() [2/2]

Object zakero::messagepack::extensionTimestampConvert ( const struct timespec &  ts )

noexcept

Conversion from a struct timespec into the MessagePack Timestamp extension is handled by this method.

Example

std::timespec ts;
std::timespec_get(&ts, TIME_UTC);
 
zakero::messagepack::Object object =
        zakero::messagepack::extensionTimestampConvert(ts);
 
std::vector<uint8_t> data = zakero::messagepack::serialize(object);

Returns

A MessagePack Object.

Parameters

ts	The time data

operator!=()

bool operator!= ( const zakero::messagepack::Object &  lhs, const zakero::messagepack::Object &  rhs  )

noexcept

For two Objects to differ, their variant types must be different or the contents of the Objects must be different.

Return values

true	The Objects are different.
false	The Objects are not different (they are the same).

Parameters

lhs	The Object
rhs	The Object

operator<<() [1/4]

std::ostream & operator<< ( std::ostream &  stream, const zakero::messagepack::Array &  array  )

noexcept

The array will be converted into a JSON formatted string and written to the stream.

Returns

The stream object.

Parameters

stream	The stream to use.
array	The data to write.

operator<<() [2/4]

std::ostream & operator<< ( std::ostream &  stream, const zakero::messagepack::Ext &  ext  )

noexcept

The ext will be converted into a JSON formatted string and written to the stream.

Returns

The stream object.

Parameters

stream	The stream to use.
ext	The data to write.

operator<<() [3/4]

std::ostream & operator<< ( std::ostream &  stream, const zakero::messagepack::Map &  map  )

noexcept

The map will be converted into a JSON formatted string and written to the stream.

Returns

The stream object.

Parameters

stream	The stream to use.
map	The data to write.

operator<<() [4/4]

std::ostream & operator<< ( std::ostream &  stream, const zakero::messagepack::Object &  object  )

noexcept

The object will be converted into a JSON formatted string and written to the stream.

Returns

The stream object.

Parameters

stream	The stream to use.
object	The data to write.

operator==()

bool operator== ( const zakero::messagepack::Object &  lhs, const zakero::messagepack::Object &  rhs  )

noexcept

For two Objects to be the same, their variant types must be the same and the contents of the Objects must match.

Return values

true	The Objects are the same.
false	The Objects are not the same.

Parameters

lhs	The Object
rhs	The Object

serialize() [1/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Array &  array )

noexcept

The contents of the Array will be packed into the returned std::vector.

Example

zakero::messagepack::Array array;
array.append(command_id);
array.append(true);
array.append(error_code);
 
std::vector<uint8_t> result = zakero::messagepack::serialize(array);
 
reply(host_ip, result);

Returns

The packed data.

Parameters

array

The Array

serialize() [2/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Array &  array, std::error_code &  error  )

noexcept

The contents of the Array will be packed into the returned std::vector.

Example

zakero::messagepack::Array array;
array.append(command_id);
array.append(true);
array.append(error_code);
 
std::error_code error;
 
std::vector<uint8_t> result = zakero::messagepack::serialize(array, error);
 
if(error)
{
        logError(command_id, error);
}
else
{
        reply(host_ip, result);
}

Returns

The packed data.

Parameters

array	The Array
error	The Error

serialize() [3/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Ext &  ext )

noexcept

The contents of the Ext will be packed into the returned std::vector.

Example

zakero::messagepack::Ext ext;
ext.type = 42;
ext.data = std::vector<uint8_t>(16, '_');
 
std::vector<uint8_t> result = zakero::messagepack::serialize(ext);

Returns

The packed data.

Parameters

ext	The Extension

serialize() [4/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Ext &  ext, std::error_code &  error  )

noexcept

The contents of the Ext will be packed into the returned std::vector.

Example

zakero::messagepack::Ext ext;
ext.type = 42;
ext.data = std::vector<uint8_t>(16, '_');
 
std::error_code error;
std::vector<uint8_t> result = zakero::messagepack::serialize(ext, error);

Returns

The packed data.

Parameters

ext	The Extension
error	The Error

serialize() [5/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Map &  map )

noexcept

The contents of the Map will be packed into the returned std::vector.

Example

zakero::messagepack::Map map;
map.set(Object{uint64_t(42)}, Object{true});
 
std::vector<uint8_t> result = zakero::messagepack::serialize(map);
 
reply(host_ip, result);

Returns

The packed data.

Parameters

map

The Map

serialize() [6/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Map &  map, std::error_code &  error  )

noexcept

The contents of the Map will be packed into the returned std::vector.

Example

zakero::messagepack::Map map;
map.set(Object{uint64_t(42)}, Object{true});
 
std::error_code error;
std::vector<uint8_t> result = zakero::messagepack::serialize(map, error);
 
reply(host_ip, result);

Returns

The packed data.

Parameters

map	The Map
error	The Error

serialize() [7/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Object &  object )

noexcept

The contents of the Object will be packed into the returned std::vector.

Example

zakero::messagepack::Object object = { true };
 
std::vector<uint8_t> result = zakero::messagepack::serialize(object);
 
reply(host_ip, result);

Returns

The packed data.

Parameters

object

The Object

serialize() [8/8]

std::vector< uint8_t > zakero::messagepack::serialize ( const Object &  object, std::error_code &  error  )

noexcept

The contents of the Object will be packed into the returned std::vector.

Example

zakero::messagepack::Object object = { true };
 
std::error_code error;
std::vector<uint8_t> result = zakero::messagepack::serialize(object, error);
 
reply(host_ip, result);

Returns

The packed data.

Parameters

object	The Object
error	The Error

to_string() [1/4]

std::string zakero::messagepack::to_string ( const messagepack::Array &  array )

noexcept

Returns

A string.

Parameters

array

The Array to convert.

to_string() [2/4]

std::string zakero::messagepack::to_string ( const messagepack::Ext &  ext )

noexcept

Returns

A string.

Parameters

ext	The Ext to convert.

to_string() [3/4]

std::string zakero::messagepack::to_string ( const messagepack::Map &  map )

noexcept

Returns

A string.

Parameters

map	The Map to convert.

to_string() [4/4]

std::string zakero::messagepack::to_string ( const messagepack::Object &  object )

noexcept

Returns

A string.

Parameters

object

The Object to convert.

Variable Documentation

ErrorCategory

ErrorCategory_ zakero::messagepack::ErrorCategory

This one instance will be used by all error codes.