DCCL v3
Public Member Functions | Static Public Member Functions | Friends | List of all members
dccl::Codec Class Reference

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

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 Public Member Functions

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

Friends

class v2::DefaultMessageCodec
 

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

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_codecName passed to FieldCodecManager::add of a non-standard TypedFieldCodec<uint32> to be used by this Codec to identify message types.
library_pathLibrary 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

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
beginIterator to the first byte of encoded message to decode (must already have been validated)
endIterator pointing to the past-the-end character of the message.
msgPointer to any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message). The decoded message will be written here.
header_onlyIf true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
Exceptions
Exceptionif message cannot be decoded.
Returns
Actual end of decoding, allowing the next message to be decoded starting at this location

Definition at line 439 of file codec.h.

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
bytesencoded message to decode (must already have been validated)
msgPointer to any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message). The decoded message will be written here.
header_onlyIf true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
Exceptions
Exceptionif message cannot be decoded.

Definition at line 329 of file codec.cpp.

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

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

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

Definition at line 322 of file codec.cpp.

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
GoogleProtobufMessagePointeranything that acts like a pointer (has operator*) to a google::protobuf::Message (smart pointers like boost::shared_ptr included)
Parameters
bytesthe byte string returned by encode
header_onlyIf true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
Exceptions
Exceptionif 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 387 of file codec.h.

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
GoogleProtobufMessagePointeranything that acts like a pointer (has operator*) to a google::protobuf::Message (smart pointers like boost::shared_ptr included)
Parameters
bytesencoded message to decode (must already have been validated) which will have the used bytes stripped from the front of the encoded message
Exceptions
Exceptionif 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 402 of file codec.h.

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
bytesPointer to byte string to store encoded msg
msgMessage to encode (must already have been validated)
header_onlyIf true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
user_idCustom 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
Exceptionif message cannot be encoded.

Definition at line 283 of file codec.cpp.

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
bytesOutput buffer to store encoded msg
max_lenMaximum size of output buffer
msgMessage to encode (must already have been validated)
header_onlyIf true, only decode the header (do not try to decrypt (if applicable) and decode the message body)
user_idCustom 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
Exceptionif message cannot be encoded.
Returns
size of encoded message

Definition at line 234 of file codec.cpp.

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
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Definition at line 174 of file codec.h.

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

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
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)
Parameters
osPointer to a stream to write this information (if 0, written to dccl::dlog)
user_idCustom 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 155 of file codec.h.

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
osPointer to a stream to write this information (if 0, writes to dccl::dlog)
user_idCustom 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.

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
osPointer to a stream to write this information (if 0, writes to dccl::dlog)

Definition at line 661 of file codec.cpp.

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
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)
Exceptions
dccl::Exceptionif message is invalid. Warnings and errors are written to dccl::dlog.

Definition at line 96 of file codec.h.

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
descThe Google Protobuf "Descriptor" (meta-data) of the message to validate.
user_idCustom 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::Exceptionif message is invalid.

Definition at line 336 of file codec.cpp.

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.

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.

template<typename ProtobufMessage >
unsigned dccl::Codec::max_size ( )
inline

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

Template Parameters
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)
Returns
Encoded (using DCCL) maximum size in bytes

Definition at line 305 of file codec.h.

template<typename ProtobufMessage >
unsigned dccl::Codec::min_size ( )
inline

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

Template Parameters
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)
Returns
Encoded (using DCCL) minimum size in bytes

Definition at line 316 of file codec.h.

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

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

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
msgGoogle Protobuf message with DCCL extensions for which the encoded size is requested
user_idCustom 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.

template<typename ProtobufMessage >
void dccl::Codec::unload ( )
inline

Unload a given message.

Template Parameters
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Definition at line 103 of file codec.h.

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
descThe Google Protobuf "Descriptor" (meta-data) of the message to validate.
Exceptions
dccl::Exceptionif message is invalid.

Definition at line 393 of file codec.cpp.

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_idMessage dccl id
Exceptions
dccl::Exceptionif message is invalid.

Definition at line 415 of file codec.cpp.

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: