Note: Goby version 1 (shown here) is now considered obsolete. Please use version 2 for new projects, and consider upgrading old projects.

Goby Underwater Autonomy Project  Series: 1.1, revision: 163, released on 2013-02-06 14:23:27 -0500
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends
Public Member Functions
goby::acomms::DCCLCodec Class Reference

provides an API to the Dynamic CCL Codec. More...

#include <goby/acomms/dccl.h>

List of all members.

Public Member Functions

std::vector< DCCLMessage > & messages ()
const ManipulatorManager & manip_manager () const
Constructors/Destructor
 DCCLCodec (std::ostream *log=0)
 Instantiate optionally with a ostream logger (for human readable output)
 ~DCCLCodec ()
 destructor
Codec functions.

This is where the real work happens.

template<typename Key >
void encode (const Key &k, std::string &bytes, const std::map< std::string, DCCLMessageVal > &m)
 Encode a message.
template<typename Key >
void encode (const Key &k, std::string &bytes, const std::map< std::string, std::vector< DCCLMessageVal > > &m)
 Encode a message.
void decode (const std::string &bytes, std::map< std::string, DCCLMessageVal > &m)
 Decode a message.
void decode (const std::string &bytes, std::map< std::string, std::vector< DCCLMessageVal > > &m)
 Decode a message.
Informational Methods
template<typename Key >
std::string summary (const Key &k) const
std::string summary () const
 long summary of a message for all loaded messages
template<typename Key >
std::string brief_summary (const Key &k) const
 brief summary of a message for a given Key (std::string name or unsigned id)
std::string brief_summary () const
 brief summary of a message for all loaded messages
unsigned message_count ()
template<typename Key >
unsigned get_repeat (const Key &k)
std::set< unsigned > all_message_ids ()
std::set< std::string > all_message_names ()
template<typename Key >
std::map< std::string,
std::string > 
message_var_names (const Key &k) const
std::string id2name (unsigned id)
unsigned name2id (const std::string &name)
Publish/subscribe architecture related methods

Methods written largely to support DCCL in the context of a publish/subscribe architecture (e.g., see MOOS (http://www.robots.ox.ac.uk/~mobile/MOOS/wiki/pmwiki.php)). The other methods provide a complete interface for encoding and decoding DCCL messages. However, the methods listed here extend the functionality to allow for

  • message creation triggering (a message is encoded on a certain event, either time based or publish based)
  • encoding that will parse strings of the form: "key1=value,key2=value,key3=value"
  • decoding to an arbitrarily formatted string (similar concept to printf)

These methods will be useful if you are interested in any of the features mentioned above.

template<typename Key >
void pubsub_encode (const Key &k, protobuf::ModemDataTransmission *msg, const std::map< std::string, std::vector< DCCLMessageVal > > &pubsub_vals)
 Encode a message using <src_var> tags instead of <name> tags.
template<typename Key >
void pubsub_encode (const Key &k, protobuf::ModemDataTransmission *msg, const std::map< std::string, DCCLMessageVal > &pubsub_vals)
 Encode a message using <src_var> tags instead of <name> tags.
void pubsub_decode (const protobuf::ModemDataTransmission &msg, std::multimap< std::string, DCCLMessageVal > *pubsub_vals)
 Decode a message using formatting specified in <publish> tags.
template<typename Key >
std::set< std::string > get_pubsub_src_vars (const Key &k)
 what moos variables do i need to provide to create a message with a call to encode_using_src_vars
template<typename Key >
std::set< std::string > get_pubsub_all_vars (const Key &k)
 for a given message name, all architecture variables (sources, input, destination, trigger)
template<typename Key >
std::set< std::string > get_pubsub_encode_vars (const Key &k)
 all architecture variables needed for encoding (includes trigger)
template<typename Key >
std::set< std::string > get_pubsub_decode_vars (const Key &k)
 for a given message, all architecture variables for decoding (input)
template<typename Key >
std::string get_outgoing_hex_var (const Key &k)
 returns outgoing architecture hexadecimal variable
template<typename Key >
std::string get_incoming_hex_var (const Key &k)
 returns incoming architecture hexadecimal variable
bool is_publish_trigger (std::set< unsigned > &id, const std::string &key, const std::string &value)
 look if key / value are trigger for any loaded messages if so, store to id and return true
bool is_time_trigger (std::set< unsigned > &id)
 look if the time is right for trigger for any loaded messages if so, store to id and return true
bool is_incoming (unsigned &id, const std::string &key)
 see if this key is for an incoming message if so, return id for decoding

Initialization Methods.

These methods are intended to be called before doing any work with the class. However, they may be called at any time as desired.

void set_cfg (const protobuf::DCCLConfig &cfg)
 Set (and overwrite completely if present) the current configuration. (protobuf::DCCLConfig defined in dccl.proto)
void merge_cfg (const protobuf::DCCLConfig &cfg)
 Set (and merge "repeat" fields) the current configuration. (protobuf::DCCLConfig defined in dccl.proto)
void add_algorithm (const std::string &name, AlgFunction1 func)
 Add an algorithm callback for a MessageVal. The return value is stored back into the input parameter (MessageVal). See test.cpp for an example.
void add_adv_algorithm (const std::string &name, AlgFunction2 func)
 Add an advanced algorithm callback for any DCCL C++ type that may also require knowledge of all the other message variables and can optionally have additional parameters.
static void add_flex_groups (util::FlexOstream *tout)
 Registers the group names used for the FlexOstream logger.

Detailed Description

provides an API to the Dynamic CCL Codec.

See also:
dccl.proto and modem_message.proto for definition of Google Protocol Buffers messages (namespace goby::acomms::protobuf).
Examples:
acomms/chat/chat.cpp, libdccl/dccl_simple/dccl_simple.cpp, libdccl/plusnet/plusnet.cpp, libdccl/test/test.cpp, and libdccl/two_message/two_message.cpp.

Definition at line 87 of file dccl.h.


Constructor & Destructor Documentation

goby::acomms::DCCLCodec::DCCLCodec ( std::ostream *  log = 0)

Instantiate optionally with a ostream logger (for human readable output)

Parameters:
logstd::ostream object or FlexOstream to capture all humanly readable runtime and debug information (optional).

Definition at line 47 of file dccl.cpp.


Member Function Documentation

void goby::acomms::DCCLCodec::add_adv_algorithm ( const std::string &  name,
AlgFunction2  func 
)

Add an advanced algorithm callback for any DCCL C++ type that may also require knowledge of all the other message variables and can optionally have additional parameters.

Parameters:
namename of the algorithm (<... algorithm="name:param1:param2">)
funchas the form void name(MessageVal& val_to_edit, const std::vector<std::string> params, const std::map<std::string,MessageVal>& vals) (see AdvAlgFunction3). func can be a function pointer (&name) or any function object supported by boost::function (http://www.boost.org/doc/libs/1_34_0/doc/html/function.html).
params(passed to func) a list of colon separated parameters passed by the user in the XML file. param[0] is the name.
vals(passed to func) a map of <name> to current values for all message variables.

Definition at line 122 of file dccl.cpp.

void goby::acomms::DCCLCodec::add_algorithm ( const std::string &  name,
AlgFunction1  func 
)

Add an algorithm callback for a MessageVal. The return value is stored back into the input parameter (MessageVal). See test.cpp for an example.

Parameters:
namename of the algorithm (<... algorithm="name">)
funchas the form void name(MessageVal& val_to_edit) (see AdvAlgFunction1). can be a function pointer (&name) or any function object supported by boost::function (http://www.boost.org/doc/libs/1_34_0/doc/html/function.html)

Definition at line 116 of file dccl.cpp.

std::set< unsigned > goby::acomms::DCCLCodec::all_message_ids ( )
Returns:
set of all message ids loaded

Definition at line 84 of file dccl.cpp.

std::set< std::string > goby::acomms::DCCLCodec::all_message_names ( )
Returns:
set of all message names loaded

Definition at line 91 of file dccl.cpp.

void goby::acomms::DCCLCodec::decode ( const std::string &  bytes,
std::map< std::string, DCCLMessageVal > &  m 
) [inline]

Decode a message.

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message
bytesthe bytes to be decoded.
mmap of std::string (<name>) to MessageVal to store the values to be decoded. No fields can be arrays using this call. If fields are arrays, only the first value is returned.
Examples:
libdccl/dccl_simple/dccl_simple.cpp.

Definition at line 175 of file dccl.h.

void goby::acomms::DCCLCodec::decode ( const std::string &  bytes,
std::map< std::string, std::vector< DCCLMessageVal > > &  m 
) [inline]

Decode a message.

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message
bytesthe bytes to be decoded.
mmap of std::string (<name>) to MessageVal to store the values to be decoded

Definition at line 192 of file dccl.h.

template<typename Key >
void goby::acomms::DCCLCodec::encode ( const Key &  k,
std::string &  bytes,
const std::map< std::string, DCCLMessageVal > &  m 
) [inline]

Encode a message.

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message)
byteslocation for the encoded bytes to be stored. this is suitable for sending to the Micro-Modem
mmap of std::string (<name>) to a vector of MessageVal representing the values to encode. No fields can be arrays using this call. If fields are arrays, all values but the first in the array will be set to NaN or blank.
Examples:
libdccl/dccl_simple/dccl_simple.cpp.

Definition at line 147 of file dccl.h.

template<typename Key >
void goby::acomms::DCCLCodec::encode ( const Key &  k,
std::string &  bytes,
const std::map< std::string, std::vector< DCCLMessageVal > > &  m 
) [inline]

Encode a message.

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message)
byteslocation for the encoded bytes to be stored. this is suitable for sending to the Micro-Modem
mmap of std::string (<name>) to a vector of MessageVal representing the values to encode. Fields can be arrays.

Definition at line 165 of file dccl.h.

template<typename Key >
unsigned goby::acomms::DCCLCodec::get_repeat ( const Key &  k) [inline]
Returns:
repeat value (number of copies of the message per encode)

Definition at line 223 of file dccl.h.

std::string goby::acomms::DCCLCodec::id2name ( unsigned  id) [inline]
Parameters:
idmessage id
Returns:
name of message

Definition at line 237 of file dccl.h.

how many message are loaded?

Returns:
number of messages loaded
Examples:
libdccl/two_message/two_message.cpp.

Definition at line 219 of file dccl.h.

template<typename Key >
std::map<std::string, std::string> goby::acomms::DCCLCodec::message_var_names ( const Key &  k) const [inline]
Returns:
map of names to DCCL types needed to encode a given message

Definition at line 232 of file dccl.h.

unsigned goby::acomms::DCCLCodec::name2id ( const std::string &  name) [inline]
Parameters:
namemessage name
Returns:
id of message

Definition at line 240 of file dccl.h.

void goby::acomms::DCCLCodec::pubsub_decode ( const protobuf::ModemDataTransmission &  msg,
std::multimap< std::string, DCCLMessageVal > *  pubsub_vals 
) [inline]

Decode a message using formatting specified in <publish> tags.

Values will be received in two maps, one of strings and the other of doubles. The <publish> value will be placed either based on the "type" parameter of the <publish_var> tag (e.g. <publish_var type="long">SOMEVAR</publish_var> will be placed as a long). If no type parameter is given and the variable is numeric (e.g. "23242.23") it will be considered a double. If not numeric, it will be considered a string.

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message)
msgmessage to be decoded. (protobuf::ModemDataTransmission defined in modem_message.proto)
valspointer to std::multimap of publish variable name to std::string values.

Definition at line 341 of file dccl.h.

template<typename Key >
void goby::acomms::DCCLCodec::pubsub_encode ( const Key &  k,
protobuf::ModemDataTransmission *  msg,
const std::map< std::string, std::vector< DCCLMessageVal > > &  pubsub_vals 
) [inline]

Encode a message using <src_var> tags instead of <name> tags.

Values can be passed in on one or more maps of names to values, similar to DCCLCodec::encode. Casts are made and string parsing of key=value comma delimited fields is performed. This differs substantially from the behavior of encode above. For example, take this message variable:

              <int>
              <name>myint</name>
              <src_var>somevar</src_var>
              </int> 

Using this method you can pass vals["somevar"] = "mystring=foo,blah=dog,myint=32" or vals["somevar"] = 32.0 and both cases will properly parse out 32 as the value for this field. In comparison, using the normal encode you would pass vals["myint"] = 32

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message)
msglocation for the encoded message to be stored (protobuf::ModemDataTransmission defined in modem_message.proto)
valsmap of source variable name to MessageVal values.

Definition at line 278 of file dccl.h.

template<typename Key >
void goby::acomms::DCCLCodec::pubsub_encode ( const Key &  k,
protobuf::ModemDataTransmission *  msg,
const std::map< std::string, DCCLMessageVal > &  pubsub_vals 
) [inline]

Encode a message using <src_var> tags instead of <name> tags.

Use this version if you do not have vectors of src_var values

Definition at line 319 of file dccl.h.

template<typename Key >
std::string goby::acomms::DCCLCodec::summary ( const Key &  k) const [inline]

long summary of a message for a given Key (std::string name or unsigned id)

Parameters:
kcan either be std::string (the name of the message) or unsigned (the id of the message)

Definition at line 205 of file dccl.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends