lcm::LCM Class Reference

Core communications class for the C++ API. More...

#include <lcm/lcm-cpp.hpp>

Public Types
template<class MessageType >
using	HandlerFunction = std::function< void(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)>

Public Member Functions
	LCM (std::string lcm_url="")
	Constructor. More...
	LCM (lcm_t *lcm_in)
	Constructor. More...
	~LCM ()
	Destructor. More...
bool	good () const
	Checks if initialization succeeded during object construction. More...
int	publish (const std::string &channel, const void *data, unsigned int datalen)
	Publishes a raw data message. More...
template<class MessageType >
int	publish (const std::string &channel, const MessageType *msg)
	Publishes a message with automatic message encoding. More...
int	getFileno ()
	Returns a file descriptor or socket that can be used with select(), poll(), or other event loops for asynchronous notification of incoming messages. More...
int	handle ()
	Waits for and dispatches messages. More...
int	handleTimeout (int timeout_millis)
	Waits for and dispatches messages, with a timeout. More...
template<class MessageType , class MessageHandlerClass >
Subscription *	subscribe (const std::string &channel, void(MessageHandlerClass::*handlerMethod)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg), MessageHandlerClass *handler)
	Subscribes a callback method of an object to a channel, with automatic message decoding. More...
template<class MessageHandlerClass >
Subscription *	subscribe (const std::string &channel, void(MessageHandlerClass::*handlerMethod)(const ReceiveBuffer *rbuf, const std::string &channel), MessageHandlerClass *handler)
	Subscribe a callback method of an object to a channel, without automatic message decoding. More...
template<class MessageType , class ContextClass >
Subscription *	subscribeFunction (const std::string &channel, void(*handler)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg, ContextClass context), ContextClass context)
	Subscribe a function callback to a channel, with automatic message decoding. More...
template<class ContextClass >
Subscription *	subscribeFunction (const std::string &channel, void(*handler)(const ReceiveBuffer *rbuf, const std::string &channel, ContextClass context), ContextClass context)
	Subscribe a function callback to a channel, without automatic message decoding. More...
template<class MessageType >
Subscription *	subscribe (const std::string &channel, HandlerFunction< MessageType > handler)
	Subscribes a callback function to a channel, with automatic message decoding. More...
int	unsubscribe (Subscription *subscription)
	Unsubscribes a message handler. More...
lcm_t *	getUnderlyingLCM ()
	retrives the lcm_t C data structure wrapped by this class. More...

Detailed Description

Core communications class for the C++ API.

Member Typedef Documentation

HandlerFunction

template<class MessageType >

using lcm::LCM::HandlerFunction = std::function<void(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)>

Type alias for the handler function type.

Constructor & Destructor Documentation

LCM() [1/2]

lcm::LCM::LCM ( std::string  lcm_url = "" )

inline

Constructor.

Initializes the LCM instance and connects it to the specified LCM network. See the documentation on lcm_create() in the C API for details on how lcm_url is formatted.

See also

lcm_create()

LCM() [2/2]

lcm::LCM::LCM ( lcm_t *  lcm_in )

inline

Constructor.

Initializes the c++ LCM instance from an existing C instance.

See also

lcm_create()

~LCM()

lcm::LCM::~LCM ( )

inline

Destructor.

Disconnects from the LCM network, and destroys all outstanding Subscription objects.

Member Function Documentation

getFileno()

int lcm::LCM::getFileno ( )

inline

Returns a file descriptor or socket that can be used with select(), poll(), or other event loops for asynchronous notification of incoming messages.

This method is useful when integrating LCM into another event loop, such as the Qt event loop (via QSocketNotifier), the GLib event loop (via GIOChannel), a custom select() - or poll() -based event loop, or any other event loop that supports file descriptors.

Todo:

link to example code.

Returns

a non-negative file descriptor on success, or -1 if something is wrong.

See also

lcm_get_fileno()

getUnderlyingLCM()

lcm_t* lcm::LCM::getUnderlyingLCM ( )

inline

retrives the lcm_t C data structure wrapped by this class.

This method should be used carefully and sparingly. An example use case would be extending the subscription mechanism to Boost Function objects.

Returns

the lcm_t instance wrapped by this object.

See also

lcm_t

good()

bool lcm::LCM::good ( ) const

inline

Checks if initialization succeeded during object construction.

Returns

true if initialization succeeded and the instance appears ready for communication, false if not.

handle()

int lcm::LCM::handle ( )

inline

Waits for and dispatches messages.

Returns

0 on success, -1 if something went wrong.

See also

lcm_handle()

handleTimeout()

int lcm::LCM::handleTimeout ( int  timeout_millis )

inline

Waits for and dispatches messages, with a timeout.

New in LCM 1.1.0.

Returns

>0 if a message was handled, 0 if the function timed out, and <0 if an error occured.

See also

lcm_handle_timeout()

publish() [1/2]

template<class MessageType >

int lcm::LCM::publish ( const std::string &  channel, const MessageType *  msg  )

inline

Publishes a message with automatic message encoding.

This template method is designed for use with C++ classes generated by lcm-gen.

Parameters

channel	the channel to publish the message on.
msg	the message to publish.

Returns

0 on success, -1 on failure.

publish() [2/2]

int lcm::LCM::publish ( const std::string &  channel, const void *  data, unsigned int  datalen  )

inline

Publishes a raw data message.

Parameters

channel	the channel to publish the message on.
data	data buffer containing the message to publish
datalen	length of the message, in bytes.

Returns

0 on success, -1 on failure.

subscribe() [1/3]

template<class MessageType >

Subscription* lcm::LCM::subscribe	(	const std::string &	channel,
		HandlerFunction< MessageType >	handler
	)

Subscribes a callback function to a channel, with automatic message decoding.

This method is designed for use with C++ classes generated by lcm-gen .

The callback function will be invoked on the object when a message arrives on the specified channel. Prior to method invocation, LCM will attempt to automatically decode the message to the specified message type MessageType , which should be a class generated by lcm-gen . If message decoding fails, the callback function is not invoked and an error message is printed to stderr.

The callback function is invoked during calls to LCM::handle(). Callback methods are invoked by the same thread that invokes LCM::handle(), in the order that they were subscribed.

For example:

#include <exlcm/example_t.lcm>
#include <lcm/lcm-cpp.hpp>
 
int main(int argc, char** argv) {
  lcm::LCM lcm;
  lcm::LCM::HandlerFunction<exlcm::example_t> func;
  func = [](const lcm::ReceiveBuffer* rbuf, const std::string& channel,
            const exlcm::example_t* msg) {
      // do something with the message
  }
  lcm.subscribe("CHANNEL", func);
  while(true)
    lcm.handle();
  return 0;
}

Parameters

channel	The channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handler	A handler function, for example a lambda.

Returns

a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

subscribe() [2/3]

template<class MessageHandlerClass >

Subscription* lcm::LCM::subscribe	(	const std::string &	channel,
		void(MessageHandlerClass::*)(const ReceiveBuffer *rbuf, const std::string &channel)	handlerMethod,
		MessageHandlerClass *	handler
	)

Subscribe a callback method of an object to a channel, without automatic message decoding.

This method is designed for use when automatic message decoding is not desired.

The callback method will be invoked on the object when a message arrives on the specified channel. Callback methods are invoked during calls to LCM::handle(), by the same thread that calls LCM::handle(). Callbacks are invoked in the order that they were subscribed.

For example:

#include <lcm/lcm-cpp.hpp>
 
class MyMessageHandler {
  void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel) {
     // do something with the message.  Raw message bytes are
     // accessible via rbuf->data
  }
};
 
int main(int argc, char** argv) {
  lcm::LCM lcm;
  MyMessageHandler handler;
  lcm.subscribe("CHANNEL", &MyMessageHandler::onMessage, &handler);
  while(true)
    lcm.handle();
  return 0;
}

Parameters

channel	The channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerMethod	A class method pointer identifying the callback method.
handler	A class instance that the callback method will be invoked on.

Returns

a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

subscribe() [3/3]

template<class MessageType , class MessageHandlerClass >

Subscription* lcm::LCM::subscribe	(	const std::string &	channel,
		void(MessageHandlerClass::*)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)	handlerMethod,
		MessageHandlerClass *	handler
	)

Subscribes a callback method of an object to a channel, with automatic message decoding.

This method is designed for use with C++ classes generated by lcm-gen .

The callback method will be invoked on the object when a message arrives on the specified channel. Prior to method invocation, LCM will attempt to automatically decode the message to the specified message type MessageType , which should be a class generated by lcm-gen . If message decoding fails, the callback method is not invoked and an error message is printed to stderr.

The callback method is invoked during calls to LCM::handle(). Callback methods are invoked by the same thread that invokes LCM::handle(), in the order that they were subscribed.

For example:

#include <exlcm/example_t.lcm>
#include <lcm/lcm-cpp.hpp>
 
class MyMessageHandler {
  void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel,
          const exlcm::example_t* msg) {
     // do something with the message
  }
};
 
int main(int argc, char** argv) {
  lcm::LCM lcm;
  MyMessageHandler handler;
  lcm.subscribe("CHANNEL", &MyMessageHandler::onMessage, &handler);
  while(true)
    lcm.handle();
  return 0;
}

Parameters

channel	The channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerMethod	A class method pointer identifying the callback method.
handler	A class instance that the callback method will be invoked on.

Returns

a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

subscribeFunction() [1/2]

template<class MessageType , class ContextClass >

Subscription* lcm::LCM::subscribeFunction	(	const std::string &	channel,
		void(*)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg, ContextClass context)	handler,
		ContextClass	context
	)

Subscribe a function callback to a channel, with automatic message decoding.

This method is designed for use with static member functions and C-style functions.

The callback function will be invoked on the object when a message arrives on the specified channel. Prior to callback invocation, LCM will attempt to automatically decode the message to the specified message type MessageType , which should be a class generated by lcm-gen . If message decoding fails, the callback function is not invoked and an error message is printed to stderr.

The callback function is invoked during calls to LCM::handle(). Callbacks are invoked by the same thread that invokes LCM::handle(), in the order that they were subscribed.

For example:

#include <lcm/lcm-cpp.hpp>
 
class State {
public:
  lcm::LCM lcm;
  int usefulVariable;
};
 
void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel, const MessageType*
msg, State* state) {
  // do something with the message.
}
 
int main(int argc, char** argv) {
  State* state = new State;
  state->lcm.subscribe("CHANNEL", onMessage, state);
  while(true)
    state->lcm.handle();
  delete state;
  return 0;
}

Parameters

channel	The channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handler	A function pointer identifying the callback function.
context	A context variable that will be passed to the callback function. This can be used to pass state or other information to the callback function. If not needed, then ContextClass can be set to void*, and this argument set to NULL.

Returns

a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

subscribeFunction() [2/2]

template<class ContextClass >

Subscription* lcm::LCM::subscribeFunction	(	const std::string &	channel,
		void(*)(const ReceiveBuffer *rbuf, const std::string &channel, ContextClass context)	handler,
		ContextClass	context
	)

Subscribe a function callback to a channel, without automatic message decoding.

This method is designed for use when automatic message decoding is not desired.

For example:

#include <lcm/lcm-cpp.hpp>
 
void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel, void*) {
  // do something with the message.  Raw message bytes are
  // accessible via rbuf->data
}
 
int main(int argc, char** argv) {
  LCM::lcm lcm;
  lcm.subscribe("CHANNEL", onMessage, NULL);
  while(true)
    lcm.handle();
  return 0;
}

Parameters

channel	The channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handler	A function pointer identifying the callback function.
context	A context variable that will be passed to the callback function. This can be used to pass state or other information to the callback function. If not needed, then ContextClass can be set to void*, and this argument set to NULL.

Returns

a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

unsubscribe()

int lcm::LCM::unsubscribe ( Subscription *  subscription )

inline

Unsubscribes a message handler.

After unsubscription, the callback registered by the original call to subscribe() or subscribeFunction() will no longer be invoked when messages are received. The Subscription object is destroyed by this method.

Parameters

subscription

a Subscription object previously returned by a call to subscribe() or subscribeFunction().

Returns

0 on success, -1 if subscription is not a valid subscription.

---

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

• lcm-cpp.hpp