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

#include <goby/acomms/dccl.h>

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:

log	std::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:

name	name of the algorithm (`<... algorithm="name:param1:param2">`)
func	has 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:

name	name of the algorithm (`<... algorithm="name">`)
func	has 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:

k	can either be std::string (the name of the message) or unsigned (the id of the message
bytes	the bytes to be decoded.
m	map 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:

k	can either be std::string (the name of the message) or unsigned (the id of the message
bytes	the bytes to be decoded.
m	map 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:

k	can either be std::string (the name of the message) or unsigned (the id of the message)
bytes	location for the encoded bytes to be stored. this is suitable for sending to the Micro-Modem
m	map 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:

k	can either be std::string (the name of the message) or unsigned (the id of the message)
bytes	location for the encoded bytes to be stored. this is suitable for sending to the Micro-Modem
m	map 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:

id	message id

Returns:: name of message

Definition at line 237 of file dccl.h.

unsigned goby::acomms::DCCLCodec::message_count ( ) [inline]

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:

name	message 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:

k	can either be std::string (the name of the message) or unsigned (the id of the message)
msg	message to be decoded. (protobuf::ModemDataTransmission defined in modem_message.proto)
vals	pointer 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:

k	can either be std::string (the name of the message) or unsigned (the id of the message)
msg	location for the encoded message to be stored (protobuf::ModemDataTransmission defined in modem_message.proto)
vals	map 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:

k	can 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:

acomms/libdccl/dccl.h
acomms/libdccl/dccl.cpp

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

Public Member Functions

Initialization Methods.

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation