Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

# Tools/MessageQueue/InMessage.h

Go to the documentation of this file.

    00001 /**
    00002 * @file InMessage.h
    00003 *
    00004 * Declaration of class InMessageQueue, InBinaryMessage, InTextMessage,
    00005 * InConfigMessage, InMessage and MessageHandler.
    00006 *
    00007 * Include that file for the definition of classes that derive from MessageHandler.
    00008 *
    00009 * @author Martin Lötzsch
    00010 */
    00011
    00012 #ifndef __InMessage_h_
    00013 #define __InMessage_h_
    00014
    00015 #include "Tools/Streams/InStreams.h"
    00016 #include "Platform/MessageQueueBase.h"
    00017
    00018 /**
    00019 * @class InMessageQueue.
    00020 *
    00021 * A PhysicalInStream that reads the data from a MessageQueue.
    00022 */
    00023 class InMessageQueue : public PhysicalInStream
    00024 {
    00025 private:
    00026   /** The queue where the data are read from */
    00027   MessageQueueBase* queue;
    00028
    00029 public:
    00030   /** Default constructor */
    00031   InMessageQueue();
    00032
    00033
    00034   /**
    00035   * The function states whether the stream actually exists.
    00036   * @return Does the file exist?
    00037   */
    00038   virtual bool exists() const;
    00039
    00040   /**
    00041   * The function states whether the end of the file has been reached.
    00042   * @return End of file reached?
    00043   */
    00044   virtual bool getEof() const;
    00045
    00046 protected:
    00047 /**
    00048 * opens the stream.
    00049 * @param q A pointer to the message queue base
    00050   */
    00051   void open(MessageQueueBase* q);
    00052
    00053   /**
    00054   * The function reads a number of bytes from the stream.
    00055   * @param p The address the data is written to. Note that p
    00056   *          must point to a memory area that is at least
    00057   *          "size" bytes large.
    00058   * @param size The number of bytes to be read.
    00059   */
    00060   virtual void readFromStream(void* p,int size);
    00061 };
    00062
    00063 /**
    00064 * @class InBinaryMessage
    00065 *
    00066 * A binary stream from a message queue.
    00067 */
    00068 class InBinaryMessage : public InStream<InMessageQueue,InBinary>
    00069 {
    00070 public:
    00071 /**
    00072 * Constructor
    00073 * @param q A pointer to the message queue base
    00074   */
    00075   InBinaryMessage(MessageQueueBase* q);
    00076 };
    00077
    00078 /**
    00079 * @class InTextMessage
    00080 *
    00081 * A text stream from a message queue.
    00082 */
    00083 class InTextMessage : public InStream<InMessageQueue,InText>
    00084 {
    00085 public:
    00086 /**
    00087 * Constructor
    00088 * @param q A pointer to the message queue base
    00089   */
    00090   InTextMessage(MessageQueueBase* q);
    00091
    00092   /**
    00093   * Reads the complete stream into a character buffer rechanging the escaped characters.
    00094   * @param buf The buffer to fill. Note that buf must point
    00095   *              to a memory area that is large enough to carry
    00096   *              the whole string.
    00097   */
    00098   void readAll(char* buf);
    00099 };
    00100
    00101 /**
    00102 * @class InConfigMessage
    00103 *
    00104 * A config-file-style text stream from a message queue.
    00105 */
    00106 class InConfigMessage : public InStream<InMessageQueue,InConfig>
    00107 {
    00108 public:
    00109 /**
    00110 * Constructor
    00111 * @param q A pointer to the message queue base
    00112   */
    00113   InConfigMessage(MessageQueueBase* q);
    00114 };
    00115
    00116 /**
    00117 * @class InMessage
    00118 *
    00119 * An Interface for reading single messages from a MessageQueue that is used by
    00120 * MessageHandler derivates.
    00121 *
    00122 * Use the bin, text or config member for formated reading from a message queue.
    00123 */
    00124 class InMessage
    00125 {
    00126 private:
    00127 /**
    00128 * The message queue where the messages are read from. Note that the selection which message is
    00129 * read is not done by InMessageQueue but by MessageQueue itself.
    00130   */
    00131   MessageQueueBase& queue;
    00132
    00133 public:
    00134   /** An interface for reading binary messages from the queue */
    00135   InBinaryMessage bin;
    00136
    00137   /** An interface for reading text messages from the queue */
    00138   InTextMessage text;
    00139
    00140   /** An interface for reading config-file-style text messages from the queue */
    00141   InConfigMessage config;
    00142
    00143   /**
    00144   * Constructor
    00145   * @param queue A reference to a MessageQueueBase
    00146   */
    00147   InMessage(MessageQueueBase& queue);
    00148
    00149   /** returns the time stamp of the current message */
    00150   unsigned long getTimeStamp() const;
    00151
    00152   /** returns the message id of the current message */
    00153   MessageID getMessageID() const;
    00154
    00155   /** returns the message size of the current message */
    00156   int getMessageSize() const;
    00157
    00158   /** returns the team color of the robot that sent this message. Can be undefined. */
    00159   Player::teamColor getTeamColor() const;
    00160
    00161   /** returns the player number of the robot that sent this message. Can be undefined. */
    00162   Player::playerNumber getPlayerNumber() const;
    00163
    00164   /**
    00165   * returns the robot number of the robot that sent this message.
    00166   * @return 0: red1, 3:red4, 4:blue1, 7:blue4, 8:undefined */
    00167   int getRobotNumber() const;
    00168
    00169   /**
    00170   * returns whether the message was sent from a physical robot.
    00171   * This is true, when the message was sent from the Aperios/OpenR platform,
    00172   * otherwise false.
    00173   */
    00174   bool getMessageWasSentFromAPhysicalRobot() const;
    00175
    00176   /** sets the read position to 0 so that the message can be read again */
    00177   void resetReadPosition();
    00178
    00179 //protected:
    00180   /**
    00181   * Gives a direct read access to the message.
    00182   * @return The adress of the first byte of the message.
    00183   */
    00184   const char* getData() const;
    00185
    00186   /** gives the class MessageQueue access to protected members */
    00187   friend class MessageQueue;
    00188
    00189   /** gives the operator that copies a InMessage to another queue access to protected members */
    00190   friend void operator >> (InMessage& message, MessageQueue& queue);
    00191
    00192   /** Gives the stream operator access to protected members */
    00193   friend Out& operator<<(Out& stream, const MessageQueue& messageQueue);
    00194 };
    00195
    00196 /**
    00197 * @class MessageHandler
    00198 *
    00199 * Responsible for distribution of incoming messages.
    00200 * Derive any class that shall receive messages from MessageHandler and implement the
    00201 * handleMessage() function.
    00202 *
    00203 * The MessageQueue needs a reference to a MessageHandler to distribute incoming messages.
    00204 */
    00205 class MessageHandler
    00206 {
    00207 public:
    00208   /**
    00209   * Called from a MessageQueue to distribute messages.
    00210   * Use message.getMessageID to decide if the message is relavant for
    00211   * the MesssageHandler derivate.
    00212   * Use message.bin, message.text or message.config as In streams to get the data from.
    00213   * @param message The message that can be read.
    00214   * @return true if the message was read (handled).
    00215   */
    00216   virtual bool handleMessage(InMessage& message) = 0;
    00217 };
    00218
    00219 #endif //__InMessage_h_