interpreter/preprocessor/faust-0.9.47mr3/architecture/osclib/faust/src/nodes/MessageDriven.h

   1 /*
   2
   3   Copyright (C) 2011 Grame
   4
   5   This library is free software; you can redistribute it and/or
   6   modify it under the terms of the GNU Lesser General Public
   7   License as published by the Free Software Foundation; either
   8   version 2.1 of the License, or (at your option) any later version.
   9
  10   This library is distributed in the hope that it will be useful,
  11   but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13   Lesser General Public License for more details.
  14
  15   You should have received a copy of the GNU Lesser General Public
  16   License along with this library; if not, write to the Free Software
  17   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19   Grame Research Laboratory, 9 rue du Garet, 69001 Lyon - France
  20   research@grame.fr
  21
  22 */
  23
  24
  25 #ifndef __MessageDriven__
  26 #define __MessageDriven__
  27
  28 #include <string>
  29 #include <vector>
  30
  31 #include "MessageProcessor.h"
  32 #include "smartpointer.h"
  33
  34 namespace oscfaust
  35 {
  36
  37 class Message;
  38 class OSCRegexp;
  39 class MessageDriven;
  40 typedef class SMARTP<MessageDriven>     SMessageDriven;
  41
  42 //--------------------------------------------------------------------------
  43 /*!
  44         \brief a base class for objects accepting OSC messages
  45
  46         Message driven objects are hierarchically organized in a tree.
  47         They provides the necessary to dispatch an OSC message to its destination
  48         node, according to the message OSC address.
  49
  50         The principle of the dispatch is the following:
  51         - first the processMessage() method should be called on the top level node
  52         - next processMessage call propose
  53
  54
  55 */
  56 class MessageDriven : public MessageProcessor, public smartable
  57 {
  58         std::string                                             fName;                  ///< the node name
  59         std::string                                             fOSCPrefix;             ///< the node OSC address prefix (OSCAddress = fOSCPrefix + '/' + fName)
  60         std::vector<SMessageDriven>             fSubNodes;              ///< the subnodes of the current node
  61
  62         protected:
  63                                  MessageDriven(const char *name, const char *oscprefix) : fName (name), fOSCPrefix(oscprefix) {}
  64                 virtual ~MessageDriven() {}
  65
  66         public:
  67                 static SMessageDriven create (const char* name, const char *oscprefix)  { return new MessageDriven(name, oscprefix); }
  68
  69                 /*!
  70                         \brief OSC message processing method.
  71                         \param msg the osc message to be processed
  72                         The method should be called on the top level node.
  73                 */
  74                 virtual void    processMessage( const Message* msg );
  75
  76                 /*!
  77                         \brief propose an OSc message at a given hierarchy level.
  78                         \param msg the osc message currently processed
  79                         \param regexp a regular expression based on the osc address head
  80                         \param addrTail the osc address tail
  81
  82                         The method first tries to match the regular expression with the object name.
  83                         When it matches:
  84                         - it calls \c accept when \c addrTail is empty
  85                         - or it \c propose the message to its subnodes when \c addrTail is not empty.
  86                           In this case a new \c regexp is computed with the head of \c addrTail and a new \c addrTail as well.
  87                 */
  88                 virtual void    propose( const Message* msg, const OSCRegexp* regexp, const std::string addrTail);
  89
  90                 /*!
  91                         \brief accept an OSC message.
  92                         \param msg the osc message currently processed
  93                         \return true when the message is processed by the node
  94
  95                         The method is called only for the destination nodes. The real message acceptance is the node
  96                         responsability and may depend on the message content.
  97                 */
  98                 virtual bool    accept( const Message* msg );
  99
 100                 /*!
 101                         \brief handler for the \c 'get' message
 102                         \param ipdest the output message destination IP
 103
 104                         The \c 'get' message is supported by every node:
 105                         - it is propagated to the subnodes until it reaches terminal nodes
 106                         - a terminal node send its state on \c 'get' request to the IP address given as parameter.
 107                         The \c get method is basically called by the accept method.
 108                 */
 109                 virtual void    get (unsigned long ipdest) const;               ///< handler for the 'get' message
 110
 111                 void                    add ( SMessageDriven node )     { fSubNodes.push_back (node); }
 112                 const char*             getName() const                         { return fName.c_str(); }
 113                 std::string             getOSCAddress() const;
 114                 int                             size () const                           { return fSubNodes.size (); }
 115
 116                 const std::string&      name() const                    { return fName; }
 117                 SMessageDriven  subnode (int i)                         { return fSubNodes[i]; }
 118 };
 119
 120 } // end namespoace
 121
 122 #endif