Jamoma API  0.6.0.a19
TTNodeDirectory.h
1 /*
2  * TTNodeDirectory
3  * Copyright © 2008, Théo de la Hogue & Tim Place
4  *
5  * License: This code is licensed under the terms of the "New BSD License"
6  * http://creativecommons.org/licenses/BSD/
7  */
8 
9 #if !defined( __TT_NODE_DIRECTORY_H__ ) && !defined ( DISABLE_NODELIB )
10 #define __TT_NODE_DIRECTORY_H__
11 
12 #ifdef WIN_VERSION
13  #pragma warning(disable:4083) //warning C4083: expected 'newline'; found identifier 's'
14 #endif // WIN_VERSION
15 
16 #include "TTObjectBase.h"
17 #include "TTSymbol.h"
18 #include "TTValue.h"
19 #include "TTHash.h"
20 #include "TTList.h"
21 #include "TTMutex.h"
22 #include "TTNode.h"
23 #include "TTAddress.h"
24 #include "TTAddressTable.h"
25 
26 class TTNode;
27 typedef TTNode* TTNodePtr;
28 class TTNodeDirectory;
30 class TTCallback;
31 typedef TTCallback* TTCallbackPtr;
32 
33 
34 /****************************************************************************************************/
35 // Class Specifications
36 
37 /**
38  We build a tree of TTNodes, and you can request a pointer for any TTNode, or add an observer to any TTNode, etc.
39 
40  Every time we create a TTNode (or a string passed to something somewhere?) then this gets added to the tree.
41  If a TTNode is specified, such as /degrade~/audio/mute,
42  and we assume degrade~ has been added to the tree but 'audio' hasn't, then 'audio' is added followed by adding 'mute',
43  so that the tree is properly completed.
44 
45  When a TTNode is requested, the tree is traversed to find the pointer for the TTNode.
46  After the traversal (assuming no wildcards) the pointer is returned and also stored
47  in a hash table so that future requests for that TTNode are faster.
48 
49  The case of wildcards is handled, because a request is cached (keyed on the request),
50  and the value is a linked list of all of the matches.
51 
52 */
53 
54 class TTFOUNDATION_EXPORT TTNodeDirectory {
55 
56 private:
57 
58  TTSymbol name; ///< the name of the tree
59  TTNodePtr root; ///< the root of the tree
60  TTHash directory; ///< a pointer to a global hashtab which reference all address of the tree
61  TTHash aliases; ///< a pointer to a global hashtab which reference all aliases of the tree
62  TTHash observers; ///< a pointer to a hashtab which register all life cycle observers below that node
63  ///< (address/relative/to/this/node, TTList of all observers below that address)
64  ///< e.g. so that you can receive notifications of changes to the tree of TTNodes
65  TTMutexPtr mutex; ///< a Mutex to protect the mObservers hash table.
66 
67 public:
68 
69  /** Constructor */
70  TTNodeDirectory (TTSymbol aName);
71 
72  /** Destructor */
73  virtual ~TTNodeDirectory ();
74 
75  /** Initialize the TTNodeDirectory */
76  TTErr init();
77 
78  /** Set the name of the TTNodeDirectory.
79  @param newName The name to set */
80  TTErr setName(TTSymbol aname);
81 
82  /** Get the name of the TTNodeDirectory */
83  TTSymbol getName();
84 
85  /** Get the root of the TTNodeDirectory */
86  TTNodePtr getRoot();
87 
88  /** Get the directory of the TTNodeDirectory */
89  TTHashPtr getDirectory();
90 
91  /** Given an address, return a pointer to a TTNode.
92  @param anAddress A pointer to the address for which to find the TTNode (it is replaced by the real address if it contains an alias).
93  @param returnedTTNode The .
94  @return An error code. */
95  TTErr getTTNode(const char* anAddress, TTNodePtr *returnedTTNode);
96  TTErr getTTNode(TTAddress anAddress, TTNodePtr *returnedTTNode);
97 
98  /** Given an address, return an alias if exists
99  @param anAddress The address for which to find the TTNode.
100  @param returnedAlias The .
101  @return An error code if there is no alias. */
102  TTErr getAlias(TTAddress anAddress, TTAddress& returnedAlias);
103 
104  /** Given an address with alias, return an address with no alias if exists
105  @param anAddress The address with an alias inside to replace.
106  @return An error code if there is no alias. */
107  TTErr replaceAlias(TTAddress& anAddress);
108 
109  /** fill an address item using the TTNodeDirectory from an address
110  @param anAddressItem an address item
111  @param startAddress an address where to start from
112  @return An error code if the address item cannont be filled */
113  TTErr fillAddressItem(TTAddressItemPtr anAddressItem, TTAddress startAddress = kTTAdrsRoot);
114 
115  /** Find TTNodes by address
116  @param anAddress The address you wish to find, possibly including wildcards and instance names/numbers.
117  @param returnedTTNodes If non-null, a pointer will be set to the linked-list of TTNodes at the given address pattern.
118  @param firstReturnedTTNode If non-null, the address of the first TTNode object pointer that is found for the given pattern is returned here.
119  The value of the pointer will be set upon return.
120  @return An error code. */
121  TTErr Lookup(TTAddress anAddress, TTList& returnedTTNodes, TTNodePtr *firstReturnedTTNode);
122 
123  /** Find TTNodes by testing each TTNodes below an address
124  @param whereToSearch A TTNode list from where to start the research
125  @param testFunction the test function have to take a TTNode as first argument, and a pointer to something as second argument (a structure for example)
126  it have to return a boolean (true means that the node is ok).
127  @param argument argument for the testFunction
128  @param returnedTTNodes If non-null, a pointer will be set to the linked-list of TTNodes at the given address pattern.
129  @param firstReturnedTTNode If non-null, the address of the first TTNode object pointer that is found for the given pattern is returned here.
130  The value of the pointer will be set upon return.
131  @param depthLimit Precise the depth limit of the exploration (0 means no limit)
132  @param comparisonfunction To sort the children at each level
133  @return An error code. */
134  TTErr LookFor(TTListPtr whereToSearch, TTBoolean(*testFunction)(TTNodePtr node, TTPtr args), void *argument, TTList& returnedTTNodes, TTNodePtr *firstReturnedTTNode, TTUInt8 depthLimit=0, TTBoolean(*comparisonFunction)(TTValue& v1, TTValue& v2)=NULL);
135 
136  /** Is there is one TTNode or more that respect a test below an address
137  @param whereToSearch A TTNode list from where to start the research
138  @param testFunction the test function have to take a TTNode as first argument, and a pointer to something as second argument (a structure for example)
139  it have to return a boolean (true means that the node is ok).
140  @param argument argument for the testFunction.
141  @param isThere a pointer will be set to true if there is one node that respect the testFunction.
142  @param firstReturnedTTNode If non-null, the address of the first TTNode object pointer that is found for the given pattern is returned here.
143  The value of the pointer will be set upon return.
144  @return An error code. */
145  TTErr IsThere(TTListPtr whereToSearch, TTBoolean(*testFunction)(TTNodePtr node, void*args), void *argument, bool *isThere, TTNodePtr *firstTTNode);
146 
147  /** Create a new TTNode, at the given location in the tree.
148  @param anAddress The address for which you wish to create a TTNode.
149  The address may (optionally) include an instance name or number in the address of the terminal TTNode.
150  If you specify an instance name/number that already exists, then returnedTTNode will be a pointer to
151  the already existing TTNode upon return and no new TTNode will be created.
152  If you do not specify an instance name/number, then one will be generated for you automatically.
153  @param newObject The object, if applicable, that is represented by this TTNode.
154  @param aContext The context in which the object is.
155  @param returnedTTNode A pointer to the TTNode at the given address
156  @param nodeCreated A boolean : true if a TTNode have been created, else false
157  @return An error code. */
158  TTErr TTNodeCreate(TTAddress& anAddress, TTObject& newObject, void *aContext, TTNodePtr *returnedTTNode, TTBoolean *nodeCreated);
159 
160  /** Remove a TTNodefrom the directory.
161  @param anAddress The address for which you wish to remove the TTNode.
162  The address may (optionally) include an instance name or number in the address of the terminal TTNode.
163  @return An error code. */
164  TTErr TTNodeRemove(TTAddress& anAddress);
165 
166  /** Create an alias address
167  @param alias The alias address (absolute)
168  @param anAddress The address for which you wish to create an alias.
169  @return An error code. */
170  TTErr AliasCreate(TTAddress alias, TTAddress anAddress);
171 
172  /** Create an alias address
173  @param alias The alias address to remove
174  @return An error code. */
175  TTErr AliasRemove(TTAddress alias);
176 
177  /** Add a TTCallback as a life cycle observer of all nodes below this one
178  @param anAddress an address to observe
179  @param observer a #TTCallback object to add
180  @param maxDepthDifference precise the max depth difference to filter nodes which are below this limit
181  @return an error code */
182  TTErr addObserverForNotifications(TTAddress anAddress, TTObject& anObserver, TTInt8 maxDepthDifference=-1);
183 
184  /** Remove a TTCallback as a life cycle observer of all nodes below this one
185  @param anAddress an address
186  @param observer a #TTCallback object to remove
187  @return a kTTErrGeneric if there isn't observer */
188  TTErr removeObserverForNotifications(TTAddress anAddress, TTObject& anObserver);
189 
190  /** Notify life cycle observers that something appends below this TTNode
191  @param data an address where something append
192  @param aNode a TTNodePtr where something append (NULL in case of destruction)
193  @param flag a flag to notify about creation or destruction (or anything else)
194  @return a kTTErrGeneric if there isn't observer */
195  TTErr notifyObservers(TTAddress anAddress, TTNodePtr aNode, TTAddressNotificationFlag flag);
196 };
197 
198 /** An test tool : test the object stored inside the node.
199  This method could be used as testFunction for the LookFor or IsThere methods.
200  @param node A node
201  @param args An TTObjectBasePtr argument to retreive an object instance
202  @return true if the object is the same than the one passed in argument */
203 TTBoolean TTFOUNDATION_EXPORT testNodeObject(TTNodePtr n, TTPtr args);
204 
205 /** An test tool : test the type of the object stored inside the node.
206  This method could be used as testFunction for the LookFor or IsThere methods.
207  @param node A node
208  @param args An TTSymbolRef argument for the type
209  @return true if the object have the correct type */
210 TTBoolean TTFOUNDATION_EXPORT testNodeObjectType(TTNodePtr n, TTPtr args);
211 
212 /** An test tool : test the context of the object stored inside the node.
213  This method could be used as testFunction for the LookFor or IsThere methods.
214  @param node A node
215  @param args An TTSymbolRef argument for the type
216  @return true if the object have the correct context */
217 TTBoolean TTFOUNDATION_EXPORT testNodeContext(TTNodePtr n, TTPtr args);
218 
219 /** An test tool : test a node using a TTCallback.
220  This method could be used as testFunction for the LookFor or IsThere methods.
221  @param node A node
222  @param args A TTCallback argument
223  @return true if the TTCallback argument is replaced by kTTVal1 */
224 TTBoolean TTFOUNDATION_EXPORT testNodeUsingCallback(TTNodePtr n, TTPtr args);
225 
226 /** An test tool : test a node using a list of filter from a bank.
227  In default exclusion mode, if one field of a filter matches a node, this node is excluded.
228  In inclusion mode, if all fields of a filter match a node, this node is included.
229  This method could be used as testFunction for the LookFor or IsThere methods.
230  @param node A node
231  @param args A TTValuePtr containing a TTHashPtr (the bank) and a TTListPtr (the name of the filter)
232  @return true if the node have to be include in the result */
233 TTBoolean TTFOUNDATION_EXPORT testNodeUsingFilter(TTNodePtr n, TTPtr args);
234 
235 /** An comparison tool : compare the priority attribute of to object's node then if equal the name and then the instance to sort them aphabeticaly
236  This method could be used as comparison function to sort a node list.
237  @param v1 first node
238  @param v2 second node
239  @return true if priority of first node is lower than the second node (but a priority of 0 is always higher than any other value)*/
240 TTBoolean TTFOUNDATION_EXPORT compareNodePriorityThenNameThenInstance(TTValue& v1, TTValue& v2);
241 
242 /** An method used to find an observer in the observers table */
243 void findObserver(const TTValue& value, TTPtr observerToMatch, TTBoolean& found);
244 
245 
246 #endif // __TT_NODE_DIRECTORY_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
The Jamoma Object Base Class.
This class is used to be sensitive to any TTObject notifications and report them using a function wit...
Definition: TTCallback.h:28
We build a directory of TTNodes, and you can request a pointer for any TTNode, or add an observer to ...
Definition: TTNode.h:59
The TTAddress class is used to represent a string and efficiently pass and compare that string...
Definition: TTAddress.h:29
Create and use Jamoma object instances.
Definition: TTObject.h:29
TTAddressNotificationFlag
Notification flags to notify observers of a directory.
Definition: TTAddressBase.h:55
Maintain a collection of TTValue objects indexed by TTSymbol pointers.
Definition: TTHash.h:36
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTCallback * TTCallbackPtr
Pointer to a TTCallback object.
Definition: TTCallback.h:75
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
signed char TTInt8
8 bit signed integer (char)
Definition: TTBase.h:173
References an object using a name, an instance and any contextual environnement information.
Provides a common way of representing composite values.
We build a tree of TTNodes, and you can request a pointer for any TTNode, or add an observer to any T...
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
unsigned char TTUInt8
8 bit unsigned integer (char)
Definition: TTBase.h:174