The Dynamic CCL enCODer/DECoder. This is the main class you will use to load, encode and decode DCCL messages. Many users will not need any other DCCL classes than this one. More...

#include <dccl/codec.h>

Public Member Functions
	Codec (std::string dccl_id_codec_name=default_id_codec_name(), const std::string &library_path="")
	Instantiate a Codec, optionally with a non-default identifier field codec (loaded via a shared library). More...

template<class IDFieldCodec , typename std::enable_if< std::is_base_of< FieldCodecBase, IDFieldCodec >::value, int >::type = 0>
	Codec (const std::string &dccl_id_codec_name, const IDFieldCodec &dccl_id_codec)
	Instantiate a Codec with a non-default identifier field codec (loaded directly). More...

virtual	~Codec ()
	Destructor.

	Codec (const Codec &)=delete

Codec &	operator= (const Codec &)=delete

void	load_library (void *dl_handle)
	Add codecs and/or load messages present in the given shared library handle. More...

void	unload_library (void *dl_handle)
	Remove codecs and/or unload messages present in the given shared library handle. More...

void	load_library (const std::string &library_path)
	Load any codecs present in the given shared library name. More...

template<typename ProtobufMessage >
std::size_t	load ()
	All messages must be explicited loaded and validated (size checks, option extensions checks, etc.) before they can be encoded/decoded. Use this version of load() when the messages used are static (known at compile time). More...

template<typename ProtobufMessage >
void	unload ()
	Unload a given message. More...

void	unload_all ()

std::size_t	load (const google::protobuf::Descriptor *desc, int user_id=-1)
	An alterative form for loading and validating messages for message types not known at compile-time ("dynamic"). More...

void	unload (const google::protobuf::Descriptor *desc)
	An alterative form for unloading messages for message types not known at compile-time ("dynamic"). More...

void	unload (size_t dccl_id)
	An alterative form for unloading messages for message types not known at compile-time ("dynamic"). More...

void	set_id_codec (const std::string &id_codec_name)
	Set a different ID codec name (note that is calls unload_all() so all messages must be reloaded)

std::string	get_id_codec ()

void	set_crypto_passphrase (const std::string &passphrase, const std::set< int32 > &do_not_encrypt_ids=std::set< int32 >())
	Set a passphrase to be used when encoded messages to encrypt them and to decrypt messages after decoding them. More...

void	set_crypto_passphrase (const std::string &passphrase, const std::set< unsigned > &do_not_encrypt_ids)

void	set_strict (bool mode)
	Set "strict" mode where a dccl::OutOfRangeException will be thrown for encode if the value(s) provided are out of range. More...

void	set_console_width (unsigned num_chars)
	Set the number of characters used in programmatic generation of console outputs. More...

template<typename CharIterator >
dccl::int32	id (CharIterator begin, CharIterator end) const

Informational Methods.
Provides various forms of information about the Codec
template<typename ProtobufMessage >
void	info (std::ostream *os=nullptr, int user_id=-1) const
	Writes a human readable summary (including field sizes) of the provided DCCL type to the stream provided. More...

void	info (const google::protobuf::Descriptor desc, std::ostream os=nullptr, int user_id=-1) const
	An alterative form for getting information for messages for message types not known at compile-time ("dynamic"). More...

void	info_all (std::ostream *os=nullptr) const
	Writes a human readable summary (including field sizes) of all the loaded (validated) DCCL types. More...

template<typename ProtobufMessage >
int32	id () const
	Gives the DCCL id (defined by the custom message option extension "(dccl.msg).id" in the .proto file). This ID is used on the wire to unique identify incoming message types. More...

int32	id (const std::string &bytes) const
	Get the DCCL ID of an unknown encoded DCCL message. More...

template<typename CharIterator >
int32	id (CharIterator begin, CharIterator end) const
	Get the DCCL ID of an unknown encoded DCCL message (Iterator overload).

int32	id (const google::protobuf::Descriptor *desc) const
	Provides the DCCL ID given a DCCL type.

const std::map< int32, const google::protobuf::Descriptor * > &	loaded () const
	Provides a map of all loaded DCCL IDs to the equivalent Protobuf descriptor.

Codec functions.
This is where the real work happens.
void	encode (std::string *bytes, const google::protobuf::Message &msg, bool header_only=false, int user_id=-1)
	Encodes a DCCL message. More...

size_t	encode (char *bytes, size_t max_len, const google::protobuf::Message &msg, bool header_only=false, int user_id=-1)
	Encodes a DCCL message. More...

template<typename CharIterator , typename ProtobufMessage >
CharIterator	decode (CharIterator begin, CharIterator end, ProtobufMessage *msg, bool header_only=false)
	Decode a DCCL message when the type is known at compile time. More...

template<typename ProtobufMessage >
void	decode (const std::string &bytes, ProtobufMessage *msg, bool header_only=false)
	Decode a DCCL message when the type is known at compile time. More...

template<typename ProtobufMessage >
void	decode (std::string bytes, ProtobufMessage msg)
	Decode a DCCL message when the type is known at compile time. More...

template<typename GoogleProtobufMessagePointer >
GoogleProtobufMessagePointer	decode (const std::string &bytes, bool header_only=false)
	An alterative form for decoding messages for message types not known at compile-time ("dynamic"). More...

template<typename GoogleProtobufMessagePointer >
GoogleProtobufMessagePointer	decode (std::string *bytes)
	An alterative form for decoding messages for message types not known at compile-time ("dynamic"), where the bytes used are stripped from the front of the encoded message. More...

unsigned	size (const google::protobuf::Message &msg, int user_id=-1)
	Provides the encoded size (in bytes) of msg. This is useful if you need to know the size of a message before encoding it (encoding it is generally much more expensive than calling this method) More...

template<typename ProtobufMessage >
unsigned	max_size ()
	Provides the encoded maximum size (in bytes) of msg. More...

unsigned	max_size (const google::protobuf::Descriptor *desc) const
	Provides the encoded maximum size (in bytes) of msg.

template<typename ProtobufMessage >
unsigned	min_size ()
	Provides the encoded minimum size (in bytes) of msg. More...

unsigned	min_size (const google::protobuf::Descriptor *desc) const
	Provides the encoded minimum size (in bytes) of msg.

FieldCodecManagerLocal &	manager ()

static std::string	default_id_codec_name ()

static std::string	default_codec_name (int version=2)

Detailed Description

The Dynamic CCL enCODer/DECoder. This is the main class you will use to load, encode and decode DCCL messages. Many users will not need any other DCCL classes than this one.

Definition at line 62 of file codec.h.

Constructor & Destructor Documentation

◆ Codec() [1/2]

dccl::Codec::Codec	(	std::string	dccl_id_codec_name = `default_id_codec_name()`,
		const std::string &	library_path = `""`
	)

Instantiate a Codec, optionally with a non-default identifier field codec (loaded via a shared library).

Normally you will use the default identifier field codec by calling Codec() with no parameters. This will use the DefaultIdentifierCodec to distinguish DCCL message types. However, if you are writing special purpose messages that need to use a different (e.g. more compact) identifier codec, you can load it with FieldCodecManagerLocal::add and then instantiate Codec with that name.

Parameters

dccl_id_codec_name	Name passed to FieldCodecManagerLocal::add of a non-standard TypedFieldCodec<uint32> to be used by this Codec to identify message types.
library_path	Library to load using load_library (this library would typically load the identifier codec referenced in dccl_id_codec).

Definition at line 75 of file codec.cpp.

◆ Codec() [2/2]

template<class IDFieldCodec , typename std::enable_if< std::is_base_of< FieldCodecBase, IDFieldCodec >::value, int >::type = 0>

dccl::Codec::Codec	(	const std::string &	dccl_id_codec_name,
		const IDFieldCodec &	dccl_id_codec
	)

inline

Instantiate a Codec with a non-default identifier field codec (loaded directly).

If you are writing special purpose messages that need to use a different (e.g. more compact) identifier codec, you can instantiate a DCCL Codec that identifier codec using this constructor

Parameters

dccl_id_codec_name	Name passed to FieldCodecManagerLocal::add of a non-standard TypedFieldCodec<uint32> to be used by this Codec to identify message types.
dccl_id_codec	Default instantiation of the IDFieldCodec to use

Template Parameters

IDFieldCodec The type of the TypedFieldCodec<uint32> to be used as the ID codec

Definition at line 82 of file codec.h.

Member Function Documentation

◆ decode() [1/5]

template<typename CharIterator , typename ProtobufMessage >

CharIterator dccl::Codec::decode	(	CharIterator	begin,
		CharIterator	end,
		ProtobufMessage *	msg,
		bool	header_only = `false`
	)

Decode a DCCL message when the type is known at compile time.

Parameters

begin	Iterator to the first byte of encoded message to decode (must already have been validated)
end	Iterator pointing to the past-the-end character of the message.
msg	Pointer to any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message). The decoded message will be written here.
header_only	If true, only decode the header (do not try to decrypt (if applicable) and decode the message body)

Exceptions

Exception if message cannot be decoded.

Returns: Actual end of decoding, allowing the next message to be decoded starting at this location

Definition at line 532 of file codec.h.

◆ decode() [2/5]

template<typename GoogleProtobufMessagePointer >

GoogleProtobufMessagePointer dccl::Codec::decode	(	const std::string &	bytes,
		bool	header_only = `false`
	)

An alterative form for decoding messages for message types not known at compile-time ("dynamic").

Template Parameters

GoogleProtobufMessagePointer anything that acts like a pointer (has operator*) to a google::protobuf::Message (smart pointers like std::shared_ptr included)

Parameters

bytes	the byte string returned by encode
header_only	If true, only decode the header (do not try to decrypt (if applicable) and decode the message body)

Exceptions

Exception if message cannot be decoded

Returns: pointer to decoded message (a google::protobuf::Message). You are responsible for deleting the memory used by this pointer, so we recommend using a smart pointer here (e.g. std::shared_ptr or the C++11 equivalent). This message can be examined using the Google Reflection/Descriptor API.

Definition at line 474 of file codec.h.

◆ decode() [3/5]

template<typename ProtobufMessage >

void dccl::Codec::decode	(	const std::string &	bytes,
		ProtobufMessage *	msg,
		bool	header_only = `false`
	)

inline

Decode a DCCL message when the type is known at compile time.

Parameters

bytes	encoded message to decode (must already have been validated)
msg	Pointer to any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message). The decoded message will be written here.
header_only	If true, only decode the header (do not try to decrypt (if applicable) and decode the message body)

Exceptions

Exception if message cannot be decoded.

Definition at line 315 of file codec.h.

◆ decode() [4/5]

template<typename GoogleProtobufMessagePointer >

GoogleProtobufMessagePointer dccl::Codec::decode ( std::string * bytes )

An alterative form for decoding messages for message types not known at compile-time ("dynamic"), where the bytes used are stripped from the front of the encoded message.

Template Parameters

GoogleProtobufMessagePointer anything that acts like a pointer (has operator*) to a google::protobuf::Message (smart pointers like std::shared_ptr included)

Parameters

bytes encoded message to decode (must already have been validated) which will have the used bytes stripped from the front of the encoded message

Exceptions

Exception if message cannot be decoded

Returns: pointer to decoded message (a google::protobuf::Message). You are responsible for deleting the memory used by this pointer, so we recommend using a smart pointer here (e.g. std::shared_ptr or the C++11 equivalent). This message can be examined using the Google Reflection/Descriptor API.

Definition at line 491 of file codec.h.

◆ decode() [5/5]

template<typename ProtobufMessage >

void dccl::Codec::decode	(	std::string *	bytes,
		ProtobufMessage *	msg
	)

inline

Decode a DCCL message when the type is known at compile time.

Parameters

bytes	encoded message to decode (must already have been validated) which will have the used bytes stripped from the front of the encoded message
msg	Pointer to any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message). The decoded message will be written here.

Exceptions

Exception if message cannot be decoded.

Definition at line 325 of file codec.h.

◆ encode() [1/2]

size_t dccl::Codec::encode	(	char *	bytes,
		size_t	max_len,
		const google::protobuf::Message &	msg,
		bool	header_only = `false`,
		int	user_id = `-1`
	)

Encodes a DCCL message.

Parameters

bytes	Output buffer to store encoded msg
max_len	Maximum size of output buffer
msg	Message to encode (must already have been validated)
header_only	If true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
user_id	Custom user_speicified dccl id to identify a message, if user_id is not specified or <0, then the first dccl id with the message descriptor corresponding to that of msg will be used

Exceptions

Exception if message cannot be encoded.

Returns: size of encoded message

Definition at line 214 of file codec.cpp.

◆ encode() [2/2]

void dccl::Codec::encode	(	std::string *	bytes,
		const google::protobuf::Message &	msg,
		bool	header_only = `false`,
		int	user_id = `-1`
	)

Encodes a DCCL message.

Parameters

bytes	Pointer to byte string to store encoded msg
msg	Message to encode (must already have been validated)
header_only	If true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
user_id	Custom user_speicified dccl id to identify a message, if user_id is not specified or <0, then the first dccl id with the message descriptor corresponding to that of msg will be used

Exceptions

Exception if message cannot be encoded.

Definition at line 274 of file codec.cpp.

◆ id() [1/2]

template<typename ProtobufMessage >

int32 dccl::Codec::id ( ) const

inline

Gives the DCCL id (defined by the custom message option extension "(dccl.msg).id" in the .proto file). This ID is used on the wire to unique identify incoming message types.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Definition at line 218 of file codec.h.

◆ id() [2/2]

int32 dccl::Codec::id ( const std::string & bytes ) const

Get the DCCL ID of an unknown encoded DCCL message.

You can use this method along with id() to handle multiple types of known (static) incoming DCCL messages. For example:

int32 dccl_id = codec.id(bytes);
if(dccl_id == codec.id<MyProtobufType1>())
{
    MyProtobufType1 msg_out1;
    codec.decode(bytes, &msg_out1);
}
else if(dccl_id == codec.id<MyProtobufType2>())
{
    MyProtobufType2 msg_out2;
    codec.decode(bytes, &msg_out2);
}

Parameters

bytes encoded message to get the DCCL ID of

Returns: DCCL ID

See also: test/acomms/dccl8/test.cpp and test/acomms/dccl8/test.proto

Definition at line 314 of file codec.cpp.

◆ info() [1/2]

void dccl::Codec::info	(	const google::protobuf::Descriptor *	desc,
		std::ostream *	os = `nullptr`,
		int	user_id = `-1`
	)		const

An alterative form for getting information for messages for message types not known at compile-time ("dynamic").

Parameters

os	Pointer to a stream to write this information (if 0, writes to dccl::dlog)
user_id	Custom user_speicified dccl id to identify a message, if user_id is not specified or <0, then the first dccl id with the message descriptor corresponding to that of msg will be used

Definition at line 512 of file codec.cpp.

◆ info() [2/2]

template<typename ProtobufMessage >

void dccl::Codec::info	(	std::ostream *	os = `nullptr`,
		int	user_id = `-1`
	)		const

inline

Writes a human readable summary (including field sizes) of the provided DCCL type to the stream provided.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Parameters

os	Pointer to a stream to write this information (if 0, written to dccl::dlog)
user_id	Custom user_speicified dccl id to identify a message, if user_id is not specified or <0, then the first dccl_id with the message descriptor corresponding to that of msg will be used

Definition at line 197 of file codec.h.

◆ info_all()

void dccl::Codec::info_all ( std::ostream * os = nullptr ) const

Writes a human readable summary (including field sizes) of all the loaded (validated) DCCL types.

Parameters

os	Pointer to a stream to write this information (if 0, writes to dccl::dlog)

Definition at line 709 of file codec.cpp.

◆ load() [1/2]

template<typename ProtobufMessage >

std::size_t dccl::Codec::load ( )

inline

All messages must be explicited loaded and validated (size checks, option extensions checks, etc.) before they can be encoded/decoded. Use this version of load() when the messages used are static (known at compile time).

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Exceptions

dccl::Exception if message is invalid. Warnings and errors are written to dccl::dlog.

Returns: Hash of loaded message definition

Definition at line 121 of file codec.h.

◆ load() [2/2]

std::size_t dccl::Codec::load	(	const google::protobuf::Descriptor *	desc,
		int	user_id = `-1`
	)

An alterative form for loading and validating messages for message types not known at compile-time ("dynamic").

Parameters

desc	The Google Protobuf "Descriptor" (meta-data) of the message to validate.
user_id	Custom user_specified dccl id to identify a message, if user_id is not specified or <0, then the first dccl_id with the message descriptor corresponding to that of msg will be used

Exceptions

dccl::Exception if message is invalid.

Returns: Hash of loaded message definition

Definition at line 318 of file codec.cpp.

◆ load_library() [1/2]

void dccl::Codec::load_library ( const std::string & library_path )

Load any codecs present in the given shared library name.

The library is opened and then load_library(void* dl_handle) is called. Any libraries loaded this way will be unloaded when Codec is destructed.

Definition at line 653 of file codec.cpp.

◆ load_library() [2/2]

void dccl::Codec::load_library ( void * dl_handle )

Add codecs and/or load messages present in the given shared library handle.

Codecs and messages must be loaded within the shared library using a C function (declared extern "C") called "dccl3_load" with the signature void dccl3_load(dccl::Codec* codec)

Definition at line 661 of file codec.cpp.

◆ max_size()

template<typename ProtobufMessage >

unsigned dccl::Codec::max_size ( )

inline

Provides the encoded maximum size (in bytes) of msg.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Returns: Encoded (using DCCL) maximum size in bytes

Definition at line 363 of file codec.h.

◆ min_size()

template<typename ProtobufMessage >

unsigned dccl::Codec::min_size ( )

inline

Provides the encoded minimum size (in bytes) of msg.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Returns: Encoded (using DCCL) minimum size in bytes

Definition at line 375 of file codec.h.

◆ set_console_width()

void dccl::Codec::set_console_width ( unsigned num_chars )

inline

Set the number of characters used in programmatic generation of console outputs.

Parameters

num_chars Character limit for line widths on console outputs

Definition at line 181 of file codec.h.

◆ set_crypto_passphrase()

void dccl::Codec::set_crypto_passphrase	(	const std::string &	passphrase,
		const std::set< int32 > &	do_not_encrypt_ids = `std::set<int32>()`
	)

Set a passphrase to be used when encoded messages to encrypt them and to decrypt messages after decoding them.

Encryption is performed using AES via the opertional Crypto++ library. If this library is not compiled in, no encryption will be performed.

Parameters

passphrase	Plain-text passphrase
do_not_encrypt_ids_	Optional set of DCCL ids for which to skip encrypting or decrypting

Definition at line 685 of file codec.cpp.

◆ set_strict()

void dccl::Codec::set_strict ( bool mode )

inline

Set "strict" mode where a dccl::OutOfRangeException will be thrown for encode if the value(s) provided are out of range.

Parameters

mode	"true" sets strict mode, "false" disables strict mode

Definition at line 176 of file codec.h.

◆ size()

unsigned dccl::Codec::size	(	const google::protobuf::Message &	msg,
		int	user_id = `-1`
	)

Provides the encoded size (in bytes) of msg. This is useful if you need to know the size of a message before encoding it (encoding it is generally much more expensive than calling this method)

Parameters

msg	Google Protobuf message with DCCL extensions for which the encoded size is requested
user_id	Custom user-specified dccl id to identify a message, if user_id is not specified or <0, then first found dccl id with the message descriptor corresponding to that of msg will be used

Returns: Encoded (using DCCL) size in bytes

Definition at line 449 of file codec.cpp.

◆ unload() [1/3]

template<typename ProtobufMessage >

void dccl::Codec::unload ( )

inline

Unload a given message.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Definition at line 129 of file codec.h.

◆ unload() [2/3]

void dccl::Codec::unload ( const google::protobuf::Descriptor * desc )

An alterative form for unloading messages for message types not known at compile-time ("dynamic").

Parameters

desc	The Google Protobuf "Descriptor" (meta-data) of the message to validate.

Exceptions

dccl::Exception if message is invalid.

Definition at line 413 of file codec.cpp.

◆ unload() [3/3]

void dccl::Codec::unload ( size_t dccl_id )

An alterative form for unloading messages for message types not known at compile-time ("dynamic").

Parameters

dccl_id Message dccl id

Exceptions

dccl::Exception if message is invalid.

Definition at line 435 of file codec.cpp.

◆ unload_library()

void dccl::Codec::unload_library ( void * dl_handle )

Remove codecs and/or unload messages present in the given shared library handle.

Codecs and messages must be unloaded within the shared library using a C function (declared extern "C") called "dccl3_unload" with the signature void dccl3_unload(dccl::Codec* codec) Note that codecs must be added before messages that use them are loaded.

Definition at line 673 of file codec.cpp.

The documentation for this class was generated from the following files:

dccl/codec.h
src/codec.cpp

Public Member Functions

Codec functions.

Detailed Description

Constructor & Destructor Documentation

◆ Codec() [1/2]

◆ Codec() [2/2]

Member Function Documentation

◆ decode() [1/5]

◆ decode() [2/5]

◆ decode() [3/5]

◆ decode() [4/5]

◆ decode() [5/5]

◆ encode() [1/2]

◆ encode() [2/2]

◆ id() [1/2]

◆ id() [2/2]

◆ info() [1/2]

◆ info() [2/2]

◆ info_all()

◆ load() [1/2]

◆ load() [2/2]

◆ load_library() [1/2]

◆ load_library() [2/2]

◆ max_size()

◆ min_size()

◆ set_console_width()

◆ set_crypto_passphrase()

◆ set_strict()

◆ size()

◆ unload() [1/3]

◆ unload() [2/3]

◆ unload() [3/3]

◆ unload_library()