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 (const std::string &dccl_id_codec=default_id_codec_name(), const std::string &library_path="")
	Instantiate a Codec, optionally with a non-default identifier field codec. More...

virtual	~Codec ()
	Destructor.

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

void	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< unsigned > &do_not_encrypt_ids_=std::set< unsigned >())
	Set a passphrase to be used when encoded messages to encrypt them and to decrypt messages after decoding them. More...

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...

Informational Methods.
Provides various forms of information about the Codec
template<typename ProtobufMessage >
void	info (std::ostream *os=0, 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=0, 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=0) const
	Writes a human readable summary (including field sizes) of all the loaded (validated) DCCL types. More...

template<typename ProtobufMessage >
unsigned	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...

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

template<typename CharIterator >
unsigned	id (CharIterator begin, CharIterator end) const
	Provides the DCCL ID given a DCCL type.

unsigned	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.
class	v2::DefaultMessageCodec

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 >
CharIterator	decode (CharIterator begin, CharIterator end, google::protobuf::Message *msg, bool header_only=false)
	Decode a DCCL message when the type is known at compile time. More...

void	decode (const std::string &bytes, google::protobuf::Message *msg, bool header_only=false)
	Decode a DCCL message when the type is known at compile time. More...

void	decode (std::string bytes, google::protobuf::Message 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.

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 56 of file codec.h.

Constructor & Destructor Documentation

◆ Codec()

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

Instantiate a Codec, optionally with a non-default identifier field codec.

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 FieldCodecManager::add and then instantiate Codec with that name.

Parameters

dccl_id_codec	Name passed to FieldCodecManager::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 68 of file codec.cpp.

Member Function Documentation

◆ decode() [1/5]

template<typename CharIterator >

CharIterator dccl::Codec::decode	(	CharIterator	begin,
		CharIterator	end,
		google::protobuf::Message *	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 447 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 boost::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. boost::shared_ptr or the C++11 equivalent). This message can be examined using the Google Reflection/Descriptor API.

Definition at line 395 of file codec.h.

◆ decode() [3/5]

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

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 329 of file codec.cpp.

◆ 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 boost::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. boost::shared_ptr or the C++11 equivalent). This message can be examined using the Google Reflection/Descriptor API.

Definition at line 410 of file codec.h.

◆ decode() [5/5]

void dccl::Codec::decode	(	std::string *	bytes,
		google::protobuf::Message *	msg
	)

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 322 of file codec.cpp.

◆ 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 234 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 283 of file codec.cpp.

◆ id() [1/2]

template<typename ProtobufMessage >

unsigned 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 182 of file codec.h.

◆ id() [2/2]

unsigned 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:

unsigned 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 316 of file codec.cpp.

◆ info() [1/2]

void dccl::Codec::info	(	const google::protobuf::Descriptor *	desc,
		std::ostream *	os = `0`,
		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 492 of file codec.cpp.

◆ info() [2/2]

template<typename ProtobufMessage >

void dccl::Codec::info	(	std::ostream *	os = `0`,
		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 163 of file codec.h.

◆ info_all()

void dccl::Codec::info_all ( std::ostream * os = 0 ) 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 661 of file codec.cpp.

◆ load() [1/2]

template<typename ProtobufMessage >

void 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.

Definition at line 96 of file codec.h.

◆ load() [2/2]

void 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_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

dccl::Exception if message is invalid.

Definition at line 336 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 608 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 616 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 313 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 324 of file codec.h.

◆ set_crypto_passphrase()

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

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 641 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 147 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 429 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 103 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 393 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 415 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 628 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()

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

◆ set_strict()

◆ size()

◆ unload() [1/3]

◆ unload() [2/3]

◆ unload() [3/3]

◆ unload_library()