Jamoma API  0.6.0.a19
TTSubscriber.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup modularLibrary
4  *
5  * @brief A contextual subscriber to register #TTObject as #TTNode in a #TTNodeDirectory
6  *
7  * @details TODO: Add more info
8  *
9  * @authors Théo de la Hogue
10  *
11  * @copyright © 2010, Théo de la Hogue @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_SUBSCRIBER_H__
18 #define __TT_SUBSCRIBER_H__
19 
20 #include "TTModularIncludes.h"
21 
22 /*
23 
24  The aim of a subscriber is to make a node refering on an object of our environnement and, if needed,
25  to create each upper nodes to make a path to this node in the tree structure.
26  To do that we need :
27 
28  - the #TTObject to subscribe.
29  - a Context : a pointer to a structural element of our environnement which contains the subscriber (e.g. a Max patcher, a Pd patcher, a html page, ...).
30  - a relative address of the subscriber in this Context to get the name and the instance (but this could be ommited and be generated automatically).
31  - a way to share the node which refers on that Context with other suscribers inside.
32  - or, a list containing all Contexts above since a top level Context (a pointer to a top level element of our environnement) until the subscriber's Context.
33 
34  Then, if the Context node is shared, we just build the node refering on our object (with all inter level nodes if needed)
35  else we insure that all Contexts node above are created before.
36 
37  */
38 
39 class TTData;
40 typedef TTData* TTDataPtr;
41 
42 class TTMODULAR_EXPORT TTSubscriber : public TTObjectBase
43 {
44 
45 public:
46 
47  TTCLASS_SETUP(TTSubscriber)
48 
49 private:
50 
51  TTObject mObject; ///< the object to subscribe
52 
53  TTAddress mRelativeAddress; ///< the address of this subscriber relative to the Context node
54 
55  TTAddress mNodeAddress; ///< cache the address of this subscriber in the tree structure
56 
57  TTAddress mContextAddress; ///< cache the address of the Context node in the tree structure
58 
59  TTBoolean mNewInstanceCreated; ///< a flag to know if a new instance has been automatically generated
60  TTBoolean mNewContextInstanceCreated; ///< a flag to know if a new context instance has been automatically generated
61 
62  TTBoolean mSubscribed; ///< a flag to know if a subcription is made
63 
64  TTHashPtr mExposedMessages;
65  TTHashPtr mExposedAttributes;
66 
67  /** Make all needed registrations to set up a TTNode in the tree strucuture for the given mObject
68  Note : if anObject is NULL the process will only retrieve all context info. This is usefull
69  to know the namespace without subscribing to it
70  Important Note :
71  - the top level context have to be the first element of the list.
72  - each element have to be TTValue with < context name, context pointer */
73  TTErr Subscribe(const TTValue& inputValue, TTValue& outputValue);
74 
75  /** */
76  TTErr Unsubscribe();
77 
78  /** Register each given Context of the list as TTNode if they don't exist yet and return the Context node */
79  TTNodePtr registerContextList(TTListPtr aContextList);
80 
81  friend TTErr TTMODULAR_EXPORT TTSubscriberMessageReturnValueCallback(const TTValue& baton, const TTValue& data);
82  friend TTErr TTMODULAR_EXPORT TTSubscriberAttributeReturnValueCallback(const TTValue& baton, const TTValue& data);
83  friend TTErr TTMODULAR_EXPORT TTSubscriberAttributeObserveValueCallback(const TTValue& baton, const TTValue& data);
84 
85 public:
86 
87  /** Expose a message of any #TTObject as #TTData in the same context than subscribed object */
88  TTErr exposeMessage(TTObject anObject, TTSymbol messageName, TTObject& returnedData);
89 
90  /** Expose an attribute of any #TTObject as #TTData (parameter or return) in the same context than subscribed object */
91  TTErr exposeAttribute(TTObject anObject, TTSymbol attributeName, TTSymbol service, TTObject& returnedData);
92 
93  /** Remove message exposition */
94  TTErr unexposeMessage(TTSymbol messageName);
95 
96  /** Remove attribute exposition */
97  TTErr unexposeAttribute(TTSymbol attributeName);
98 };
99 
100 typedef TTSubscriber* TTSubscriberPtr;
101 
102 TTErr TTMODULAR_EXPORT TTSubscriberMessageReturnValueCallback(const TTValue& baton, const TTValue& data);
103 
104 TTErr TTMODULAR_EXPORT TTSubscriberAttributeReturnValueCallback(const TTValue& baton, const TTValue& data);
105 
106 TTErr TTMODULAR_EXPORT TTSubscriberAttributeObserveValueCallback(const TTValue& baton, const TTValue& data);
107 
108 #endif // __TT_SUBSCRIBER_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTModular Library.
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
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
Maintain a collection of TTValue objects indexed by TTSymbol pointers.
Definition: TTHash.h:36
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTData establishes a control point, which is to say a TTNode that is dramaticly expanded, for a model to get/set its state.
Definition: TTData.h:28
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34