iprotocolhandler.h

Go to the documentation of this file.

/* +---------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)               |
   |                          http://www.mrpt.org/                             |
   |                                                                           |
   | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file        |
   | See: http://www.mrpt.org/Authors - All rights reserved.                   |
   | Released under BSD License. See details in http://www.mrpt.org/License    |
   +---------------------------------------------------------------------------+ */
#ifndef IPROTOCOLHANDLER_H
#define IPROTOCOLHANDLER_H

#include "messagelocation.h"
#include <xsens/xsmessage.h>
#include <xsens/xsbytearray.h>

//--------------------------------------------------------------------------------
/*! \brief Interface class for protocol handlers
        \details Describes the interfaces of the protocol handling classes. The protocol handlers are
        used to convert a binary data stream into XsMessage objects.
*/
class IProtocolHandler
{
public:
        //! \brief Destructor
        virtual ~IProtocolHandler() {}

        /*! \brief Find the first message in the \a raw byte stream
                \details This function scans \a raw for a sequence of bytes that it can convert into an
                %XsMessage object. It returns the location and total byte size of the message so that the
                caller can remove those bytes from the stream. The return value can also describe that a 
                partial message has been found. Return values:
                \li \a startpos >= 0 and \a size > 0: A full message with \a size has been found at \a startpos.
                \li \a startpos >= 0 and \a size == 0: The start of a message has been found at \a startpos, but the size could not yet be determined.
                \li \a startpos >= 0 and \a size < 0: The start of a message has been found at \a startpos, and the size of the full message is at least \a -size.
                \li \a startpos < 0: No messages have been found.

                \param rcv If a message is read, it will be put in this object.
                \param raw The raw byte stream to analyze.
                \returns A %MessageLocation object that describes what was found.
        */
        virtual MessageLocation findMessage(XsMessage& rcv, const XsByteArray& raw) const = 0;
        /*! \brief Returns the minimum size of a valid message
                \details This value may differ for different protocols, but is always at least 1.
                \returns The minimum size of a valid message for the protocol.
        */
        virtual int minimumMessageSize() const = 0;
        /*! \brief Returns the maximum size of a valid message
                \details This value may differ for different protocols.
                \returns The maximum size of a valid message for the protocol.
        */
        virtual int maximumMessageSize() const = 0;
        /*! \brief Returns the type of the protocol handler
                \details Each protocol handler has a locally unique id that can be used for instantiation of
                the correct protocol handler.
                \returns The type id of the protocol handler.
        */
        virtual int type() const = 0;
};

//--------------------------------------------------------------------------------

#endif // file guard