00001 /* 00002 * WOscLib, an object oriented OSC library. 00003 * Copyright (C) 2005 Uli Clemens Franke, Weiss Engineering LTD, Switzerland. 00004 * 00005 * This library is free software; you can redistribute it and/or 00006 * modify it under the terms of the GNU Lesser General Public 00007 * License as published by the Free Software Foundation; either 00008 * version 2.1 of the License, or (at your option) any later version. 00009 * 00010 * This library is distributed in the hope that it will be useful, 00011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 * Lesser General Public License for more details. 00014 * 00015 * You should have received a copy of the GNU Lesser General Public 00016 * License along with this library; if not, write to the Free Software 00017 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00018 * 00019 * For details see lgpl.txt 00020 * 00021 * Weiss Engineering LTD. 00022 * Florastrass 42 00023 * 8610 Uster 00024 * Switzerland 00025 * 00026 * uli.franke@weiss.ch 00027 */ 00028 00029 /** WOscMethod , WOscCallbackList and WOscCallbackListItem header file. 00030 * \file 00031 * 00032 * $Author: cls-nebadje $ ( \ref _UcfWOscLib ) 00033 * $Date: 2009-01-13 17:23:19 $ 00034 * $Revision: 1.5 $ 00035 * 00036 * Copyright (c) Weiss Engineering Ltd 00037 * 00038 */ 00039 #ifndef __WOSCMETHOD_H__ 00040 #define __WOSCMETHOD_H__ 00041 00042 #include "WOscNetReturn.h" 00043 #include "WOscLib.h" 00044 #include "WOscMessage.h" 00045 #include "WOscTimeTag.h" 00046 #include "WOscContainer.h" 00047 #include "WOscInfo.h" 00048 00049 /* ----------------------------------------------------------------------- */ 00050 /* WOscMethodInfo */ 00051 /* ----------------------------------------------------------------------- */ 00052 00053 /** Information about an OSC method. 00054 * When queried for information about a method, this class defines it. 00055 * 00056 */ 00057 class WOSC_EXPORT WOscMethodInfo: public WOscInfo 00058 { 00059 public: 00060 WOscMethodInfo(const char* description); 00061 WOscMethodInfo(); 00062 }; 00063 00064 /* ----------------------------------------------------------------------- */ 00065 /* WOscMethod */ 00066 /* ----------------------------------------------------------------------- */ 00067 00068 class WOscContainer; 00069 00070 /** OSC callback methods are objects that are mapped to a specific OSC-address. 00071 * Very similar to OSC-containers they are children of any container. 00072 * 00073 * If during dispatching and subsequent invoking an OSC-method gets called, the 00074 * message, which produced the invokation, and a network-return-address is passed. 00075 * 00076 * Methods can be seen as remote functions. Multiple computers communicate remotely 00077 * by calling each others functions and passing arguments. 00078 * 00079 * Inherit your own methods from this class or - when using WOscReceiver - from WOscReceiverMethod. 00080 * 00081 * \see 00082 * WOscCallbackList | WOscCallbackListItem | WOscReceiverMethod 00083 */ 00084 class WOSC_EXPORT WOscMethod 00085 { 00086 public: 00087 00088 WOscMethod(WOscContainer* parent, const char* name, 00089 WOscMethodInfo* info = NULL); 00090 00091 /** The OSC method. 00092 * This is the function that will be called, when a certain OSC-address in a message 00093 * matches the address of this method-object. The message is then passed together 00094 * with a network-return-address and a timeTag which contains the point in time of the 00095 * invocation. 00096 * 00097 * Each message object can access the program resources without global variables 00098 * by using the context-pointer. 00099 * 00100 * \param message 00101 * Message causing this call (eventually containing arguments). 00102 * 00103 * \param when 00104 * Time of invocation (should be current time, when a priority queue, system time and 00105 * a fast update-rate is used. 00106 * 00107 * \param networkReturnAddress 00108 * The network address where the message came from. 00109 * 00110 * \throws 00111 * Not in this, but perhaps in inherited classes and in their function-calls. 00112 */ 00113 virtual void Method(const WOscMessage* message, const WOscTimeTag& when, 00114 const WOscNetReturn* networkReturnAddress) = 0; 00115 void AddMethodAlias(WOscContainer* parent, const char* alias); 00116 WOscContainer* GetParent(); 00117 00118 /* Address related functions */ 00119 WOscString GetName(); 00120 WOscString GetAddress(); 00121 WOscString GetAddressSpace(); 00122 /** Retrieve the proprietary info which can be set in the constructor. 00123 * NULL if not set. 00124 */ 00125 const WOscMethodInfo* GetInfo() const { return m_info; } 00126 00127 protected: 00128 /** WOscContainer controls the deletion of registered methods. */ 00129 friend class WOscContainer; 00130 /** Destructor. A WOscMethod can be deleted only by WOscContainers. Does 00131 * nothing currently. */ 00132 virtual ~WOscMethod() { delete m_info; } 00133 00134 private: 00135 WOscMethod(); /**< Disabled default constructor.*/ 00136 WOscMethod(WOscMethod &rhs);/**< Disabled copy constructor.*/ 00137 00138 WOscContainer* m_parent; /**< Parent container.*/ 00139 WOscMethodInfo* m_info; /**< Info object.*/ 00140 }; 00141 00142 00143 #include <string.h> // memcpy 00144 00145 /** Callback list. Gets filled with matching methods from an OSC address space. 00146 * Adjusts its size as soon its capacity is too low but keeps its size to avoid 00147 * unnecessary memory allocations. 00148 */ 00149 class WOscCallbackList 00150 { 00151 private: 00152 WOscMethod** m_methods; 00153 unsigned int m_count; 00154 unsigned int m_capacity; 00155 /** Doubles the internal capacity and copies the old elements over to the 00156 * new (bigger) internal buffer. 00157 */ 00158 void Double() 00159 { 00160 WOscMethod** newMethods = new WOscMethod*[m_capacity*2]; 00161 memcpy(newMethods, m_methods, sizeof(WOscMethod*)*m_capacity); 00162 m_capacity *= 2; 00163 delete [] m_methods; 00164 m_methods = newMethods; 00165 } 00166 public: 00167 /** Constructor. 00168 * @param initialCapacity 00169 * Initial (default) capacity of the call-back list. 00170 */ 00171 WOscCallbackList(unsigned int initialCapacity = 32) 00172 { 00173 m_methods = new WOscMethod*[initialCapacity]; 00174 m_capacity = initialCapacity; 00175 m_count = 0; 00176 } 00177 /** Destructor. */ 00178 virtual ~WOscCallbackList() 00179 { 00180 delete [] m_methods; 00181 } 00182 /** Just sets the number of callback items to zero but keeps the allocated 00183 * buffer which is reused the next time items are filled into the call-back 00184 * list. 00185 */ 00186 void Reset() { m_count = 0; } 00187 /** Append a method to the call-back list. */ 00188 void Append(WOscMethod* method) 00189 { 00190 if ( m_count >= m_capacity ) 00191 Double(); 00192 m_methods[m_count++] = method; 00193 } 00194 void Invoke(const WOscMessage* message, const WOscTimeTag& when, 00195 const WOscNetReturn* networkReturnAddress) 00196 { 00197 WOscMethod** method = m_methods; 00198 for ( int i = m_count-1; i >= 0; i-- ) 00199 (*(method++))->Method(message, when, networkReturnAddress); 00200 } 00201 00202 /** Returns the number of items in the call-back list. */ 00203 unsigned int GetCount() const { return m_count; } 00204 }; 00205 00206 00207 #endif // #ifndef __WOSCMETHOD_H__ 00208