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 and WOscMethodInfo source 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 00040 #include "WOscMethod.h" 00041 #include "WOscException.h" 00042 #include "WOscContainer.h" 00043 00044 /* ----------------------------------------------------------------------- */ 00045 /* WOscMethodInfo */ 00046 /* ----------------------------------------------------------------------- */ 00047 00048 /** Constructs a method-info from a string. 00049 * The string should contain some information about the method. 00050 * 00051 * \param description 00052 * String with method description. 00053 * 00054 * \throws None. 00055 */ 00056 WOscMethodInfo::WOscMethodInfo(const char* description) : WOscInfo(description) 00057 { } 00058 00059 /** Constructs an empty method-info object. 00060 * The internal buffer is initialized to zero. 00061 * 00062 * \throws None. 00063 */ 00064 WOscMethodInfo::WOscMethodInfo() :WOscInfo() 00065 { } 00066 00067 /* ----------------------------------------------------------------------- */ 00068 /* WOscMethod */ 00069 /* ----------------------------------------------------------------------- */ 00070 00071 /** Constructor. 00072 * Osc-methods can only be constructed in presence of a parent container, since 00073 * method-orphans are not allowed. Additionally they have to be instantiated 00074 * dynamically because the OSC-address-tree (formed by WOscContainer objects) 00075 * handles the clean-up of all tree-elements. Therefor the destructor is private. 00076 * 00077 * \param info 00078 * Info about this method. 00079 * 00080 * \param parent 00081 * Pointer of the container that's going to be the parent of this method. 00082 * 00083 * \param context 00084 * A void pointer for later use from within the method. This can be used to pass 00085 * an object pointer on which the method should operate lateron (As implemented in 00086 * WOscReceiver). 00087 * 00088 * \param name 00089 * The OSC-pattern that will be the name of this method in the OSC-address 00090 * space. If WOSC_ADDR_WILDCARDS is defined 1, wildcard matching will be 00091 * performed on the address path segments. 00092 * 00093 * \throws WOscException 00094 * When illegal parent pointers are passed (i.e. NULL). 00095 */ 00096 WOscMethod::WOscMethod(WOscContainer* parent, const char* name, 00097 WOscMethodInfo* info) : 00098 m_parent(parent), m_info(info) 00099 { 00100 if ( parent == NULL ) 00101 throw WOscException(ERR_PARENT_POINTER_NULL, __FILE__, __LINE__); 00102 m_parent->AddMethod(this, name, false); 00103 } 00104 00105 /** Adds this method as alias to the list of methods of the 00106 * container passed as argument. 00107 * 00108 * \param parent 00109 * Parent container to which this method should be added as alias. 00110 * 00111 * \param alias 00112 * New (aliased) name of the method. 00113 * 00114 * \throws WOscException 00115 * When passing an illegal parent pointer (i.e. NULL). 00116 * 00117 * \see 00118 * WOscContainer::addContainerAlias(WOscContainer* parent, char* alias) 00119 */ 00120 void WOscMethod::AddMethodAlias(WOscContainer* parent, const char* alias) 00121 { 00122 if ( parent == NULL ) // should not happen 00123 throw WOscException(ERR_PARENT_POINTER_NULL, __FILE__, __LINE__); 00124 parent->AddMethod(this, alias, true); 00125 } 00126 00127 // will be overridden 00128 /** The OSC method. 00129 * This is the function that will be called, when a certain OSC-address in a message 00130 * matches the address of this method-object. The message is then passed together 00131 * with a network-return-address and a timeTag which contains the point in time of the 00132 * invokation. 00133 * 00134 * Each message object can access the programm-ressources without global variables 00135 * by using the context-pointer. 00136 * 00137 * \param message 00138 * Message causing this call (eventually containing arguments). 00139 * 00140 * \param when 00141 * Time of invokation (should be current time, when a priority queue, system time and 00142 * a fast update-rate is used. 00143 * 00144 * \param networkReturnAddress 00145 * The network address where the message came from. 00146 * 00147 * \throws 00148 * Not in this, but perhaps in inherited classes and in their function-calls. 00149 00150 void WOscMethod::method(WOscMessage *message, 00151 WOscTimeTag& when, 00152 WOscNetReturn* networkReturnAddress){ 00153 00154 } 00155 */ 00156 00157 /** Gets the name (the single pattern, \b not the OSC-address) 00158 * of this node. 00159 * If a container is named "xyz" and it's located in the 00160 * OSC-address-space at "/abcd/klm/xyz/lalala", only xyz is returned. 00161 * 00162 * \returns 00163 * The name of this container as WOscString. 00164 * 00165 */ 00166 WOscString WOscMethod::GetName() 00167 { 00168 /* search all children of parent for not aliased name */ 00169 const std::vector<WOscMethodEntry>& methEntries = m_parent->m_methodEntries; 00170 for ( int i = methEntries.size()-1; i >= 0; i-- ) 00171 if ( methEntries[i].m_method == this && !methEntries[i].m_isAlias ) { 00172 return WOscString(methEntries[i].m_name.c_str()); 00173 } 00174 00175 return WOscString(); 00176 } 00177 00178 /** Returns the whole OSC-address-space as seen from root. 00179 * The address-space contains only addresses with valid 00180 * leaves (OSC-methods). 00181 * 00182 * \returns 00183 * All OSC-addresses which form the OSC-address-space, 00184 * separated by '\n'-characters. 00185 * 00186 */ 00187 WOscString 00188 WOscMethod::GetAddressSpace() 00189 { 00190 const WOscContainer* root = m_parent->FindRoot(); 00191 return root->GetMethodList(); 00192 } 00193 00194 00195 /** Returns the OSC-address of this container as seen from the root. 00196 * If this container should be aliased, it returns the main, 00197 * not aliased, address. 00198 * 00199 * \returns 00200 * OSC-address as WOscString. 00201 * 00202 * \remarks 00203 * Remember: Container-addresses end with '/', method-addresses 00204 * with no slash. 00205 * 00206 */ 00207 WOscString WOscMethod::GetAddress() 00208 { 00209 WOscContainer* momentaryParent = m_parent; 00210 WOscString address = GetName(); 00211 WOscString tmp; 00212 00213 /* traverse tree upwards until root is reached */ 00214 while ( momentaryParent != NULL ){ 00215 if (momentaryParent->m_parent == NULL) break; 00216 WOscString tmp = momentaryParent->GetName(); 00217 tmp += '/'; 00218 address = tmp + address; 00219 00220 momentaryParent = momentaryParent->m_parent; 00221 } 00222 tmp = '/'; 00223 00224 return tmp + address; 00225 } 00226 00227 00228 /** Returns the main parent-container (not aliased ones!). 00229 * For use in the method-member function to get the calling- 00230 * container-context. 00231 * 00232 * \returns 00233 * The main parent container (not aliased). 00234 */ 00235 WOscContainer* WOscMethod::GetParent() 00236 { 00237 return m_parent; 00238 }