LCM

List of all members | Public Member Functions
lcm::LCM Class Reference
C++ API Reference

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

`#include <lcm/lcm-cpp.hpp>`

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

## 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/2]

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() [2/2]

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

lcm::LCM::subscribe
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.
lcm::ReceiveBuffer
Stores the raw bytes and timestamp of a received message.
Definition: lcm-cpp.hpp:470
lcm::LCM
Core communications class for the C++ API.
Definition: lcm-cpp.hpp:43
lcm::LCM::handle
int handle()
Waits for and dispatches messages.