LCM中C++的API介绍

LCM支持多种语言，也有很多版本，这里只介绍C++的几个类以及方法。

类型简介

C++的API，LC提供了三个类以及两个结构体来封装LCM，他们分别是：

    class   lcm::LCM
    struct  lcm::ReceiveBuffer
    class   lcm::Subscription
    struct  lcm::LogEvent
    class   lcm::LogFile

两个struct是配合类来使用的。前三个可以看成一组，后面两个是配合使用的。

lcm::ReceiveBuffer

这个结构体很眼熟，就是我们需要写的回调函数的第一个参数的指针类型，先看一下其定义：

/**
 * @brief Stores the raw bytes and timestamp of a received message.
 *
 * @headerfile lcm/lcm-cpp.hpp
 */
struct ReceiveBuffer {
    /**
     * Message payload data, represented as a raw byte buffer.
     */
    void *data;
    /**
     * Length of message payload, in bytes.
     */
    uint32_t data_size;
    /**
     * Timestamp identifying when the message was received.  Specified in
     * microseconds since the UNIX epoch.
     */
    int64_t recv_utime;
};

只有三个成员，data是我们的接收到的数据转换成字节流后的指针，也就是recvfrom调用收到的原始数据，第二个成员是数据大小，第三个是接收到数据时的时间戳。（LCM内部使用，我们一般不会用到）

lcm::Subscription

这个类其实是一个与文件描述符类似的东西，先看定义：

class Subscription {
    public:
        virtual ~Subscription() {}

        /**
         * @brief Adjusts the maximum number of received messages that can be
         * queued up for this subscription.
         *
         * @param num_messages the maximum queue size, in messages.  The
         * default is 30.
         *
         * Setting this to a low number may reduce
         * overall latency at the expense of dropping more messages.
         * Conversely, setting this to a high number may drop fewer messages at
         * the expense of increased latency.  A value of 0 indicates no limit,
         * and should be used very carefully.
         *
         */
        inline int setQueueCapacity(int num_messages);

    friend class LCM;
    protected:
        Subscription() {};
        /**
         * The underlying lcm_subscription_t object wrapped by this
         * subscription.
         */
        lcm_subscription_t *c_subs;
};

这个类不详细解释，LCM高级用法估计会详细的使用这个类，但是目前我们不需要，记得，这个类是可继承的就好。

这个类目前最大的用处就是作为lcm.unsubscribe()方法的参数，也是lcm.subscribe()方法的返回值，subscribe()方法是注册channel name返回一个标识，而unsubscribe方法就是删除此channel name。

lcm::LCM

• 构造函数

这个类是我们最重要的一个类，也是核心的一个类。这个类我们只介绍方法的含义。
它有两个构造函数，这里只介绍第一个：

LCM (std::string lcm_url="")

参数的含义是一个url，一般使用默认，这个url写了ip地址和端口号，我们查看一下lcm默认的地址:

"udpm://239.255.76.67:7667?ttl=1"

若需要更改，请按照此模板修改。

• 辅助方法

bool    good () const 

lcm对象是否构造成功，成功返回true，失败返回false

int     getFileno ()

返回底层的套接字描述符

lcm_t *     getUnderlyingLCM ()

得到底层的lcm_t结构体，一般不要使用。

• publish方法

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

这个publish方法不使用lcm格式的数据，直接转化为void*直接发送出去，第一个参数为channel name，第二个参数为数据指针，第三个参数是数据大小。
一般不使用此方法来发送数据。

template<class MessageType >
int     publish (const std::string &channel, const MessageType *msg)

这个函数就是官方例子中所使用的publish函数，功能和参数这里就不再详细解释。

• subscrise方法

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)

这个版本是调用某对象的某个公共方法作为回调函数，且接收的数据的格式必须是lcm格式，也是官方例子使用的版本。

template<class MessageHandlerClass >
Subscription *  subscribe (const std::string &channel, void(MessageHandlerClass::*handlerMethod)(const ReceiveBuffer *rbuf, const std::string &channel), MessageHandlerClass *handler)

这个接收函数，会发现在回调函数的声明上，与前一个有差异，这个就是接收不是lcm格式的数据所调用的回调函数。

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)

使用某个函数作为回调函数，接收lcm格式的信息，Context是传给回调函数的参数。

template<class ContextClass >
Subscription *  subscribeFunction (const std::string &channel, void(*handler)(const ReceiveBuffer *rbuf, const std::string &channel, ContextClass context), ContextClass context)

使用某个函数作为回调函数，接收不是lcm格式的信息,Context是传给回调函数的参数。

• handle方法

int     handle ()

开启事件等待循环，一直阻塞

int     handleTimeout (int timeout_millis)

开始事件循环，最多等待timeout_millis秒.

lcm::LogEvent

这个结构体是为了配合logfile类的，logfile是LCM中的日志系统，你可以把这个结构体看做是一个事件的封装。

/**
 * @brief Represents a single event (message) in a log file.
 *
 *
 *
 * This struct is the C++ counterpart for lcm_eventlog_event_t.
 *
 * @sa lcm_eventlog_event_t
 *
 * @headerfile lcm/lcm-cpp.hpp
 */
struct LogEvent {
    /**
     * Monotically increasing counter identifying the event number.  This field
     * is managed by LCM, and there should be no need to ever set it manually.
     */
    int64_t eventnum;
    /**
     * Timestamp identifying when the event was received.  Represented in
     * microseconds since the UNIX epoch.
     */
    int64_t timestamp;
    /**
     * The LCM channel on which the message was received.
     */
    std::string channel;
    /**
     * The length of the message payload, in bytes
     */
    int32_t datalen;
    /**
     * The message payload.
     */
    void* data;
};

其中eventnum不要赋值，这个是LCM自己赋值的。

lcm::LogFile

封装了日志系统的一个类

lcm::LogFile::LogFile   ( const std::string &   path,
        const std::string &     mode )      

构造函数，“r”或者“w”，含义，不解释，注意，打开文件使用的是标准函数fopen

bool lcm::LogFile::good ( ) const

查看文件是否打开，LogFile对象是否构造成功。

FILE * lcm::LogFile::getFilePtr ( )     

得到底层的文件的FILE*

const LogEvent * lcm::LogFile::readNextEvent ( )    

读一个日志事件

int lcm::LogFile::writeEvent    (   LogEvent *      event   )   

写一个日志事件

int lcm::LogFile::seekToTimestamp   (   int64_t     timestamp   )   

查找时间戳在timestamp附近的事件，若有返回0，无返回-1