1 /**
2 * Whiteboard session manager
3 * XML node tracking facility
4 *
5 * Authors:
6 * David Yip <yipdw@rose-hulman.edu>
7 *
8 * Copyright (c) 2005 Authors
9 *
10 * Released under GNU GPL, read the file 'COPYING' for more information
11 */
13 #ifndef __WHITEBOARD_XML_NODE_TRACKER_H__
14 #define __WHITEBOARD_XML_NODE_TRACKER_H__
16 #include "jabber_whiteboard/tracker-node.h"
17 #include "jabber_whiteboard/typedefs.h"
19 #include <bitset>
20 #include <cstring>
21 #include <map>
22 #include <glibmm.h>
24 namespace Inkscape {
26 namespace Whiteboard {
28 class SessionManager;
30 /**
31 * std::less-like functor for C-style strings.
32 */
33 struct strcmpless : public std::binary_function< char const*, char const*, bool >
34 {
35 bool operator()(char const* _x, char const* _y) const
36 {
37 return (strcmp(_x, _y) < 0);
38 }
39 };
42 // TODO: This is a pretty heinous mess of methods that accept
43 // both pointers and references -- a lot of it has to do with
44 // XML::Node& in the node observer and XML::Node* elsewhere,
45 // although some of it (like Glib::ustring const& vs.
46 // Glib::ustring const*) is completely mea culpa. When possible
47 // it'd be good to thin this class out.
49 /**
50 * XMLNodeTracker generates and watches unique IDs for XML::Nodes for use in
51 * document event serialization and deserialization.
52 *
53 * More specifically, it has three tasks:
54 * <ol>
55 * <li>Association XML::Nodes with string IDs, and vice versa.</li>
56 * <li>Facilitation of lookup of a string ID or XML::Node given the other key.</li>
57 * <li>Generation of new string IDs for XML::Nodes.</li>
58 * </ol>
59 *
60 * XML::Nodes are assigned an ID that follows one of two forms:
61 * <ol>
62 * <li>unsigned integer;user JID</li>
63 * <li>unsigned integer;chatroom@conference server/handle</li>
64 * </ol>
65 *
66 * Form 1 is used in user-to-user sessions; form 2 is used in chatroom sessions.
67 */
68 class XMLNodeTracker {
69 public:
70 /**
71 * Constructor.
72 *
73 * \param sm The SessionManager with which an XMLNodeTracker instance is to be associated with.
74 */
75 XMLNodeTracker(SessionManager* sm);
76 ~XMLNodeTracker();
78 /**
79 * Insert a (key,node) pair into the tracker.
80 *
81 * \param key The key to associate with the node.
82 * \param node The node to associate with the key.
83 */
84 void put(std::string key, XML::Node& node);
86 /**
87 * Insert a (key,node) pair into the tracker.
88 *
89 * \param key The key to associate with the node.
90 * \param node The node to associate with the key.
91 */
92 void put(std::string key, XML::Node const& node);
94 /**
95 * Insert a range of (key,node) pairs into the tracker.
96 *
97 * The size of the two maps must be the same.
98 * \param newids The keys to associate with the nodes.
99 * \param newnodes The nodes to associate with the keys.
100 */
101 void put(KeyToNodeMap& newids, NodeToKeyMap& newnodes);
103 /**
104 * Process a list of node actions to add and remove nodes from the tracker.
105 *
106 * \param actions The action list to process.
107 */
108 void process(KeyToNodeActionList& actions);
110 /**
111 * Retrieve an XML::Node given a key.
112 *
113 * \param key Reference to a string key.
114 * \return Pointer to an XML::Node, or NULL if no associated node could be found.
115 */
116 XML::Node* get(std::string& key);
118 /**
119 * Retrieve an XML::Node given a key.
120 *
121 * \param key Reference to a const string key.
122 * \return Pointer to an XML::Node, or NULL if no associated node could be found.
123 */
124 XML::Node* get(std::string const& key);
126 /**
127 * Retrieve a string key given a reference to an XML::Node.
128 *
129 * \param node Reference to an XML::Node.
130 * \return The associated string key, or an empty string if no associated key could be found.
131 */
132 std::string const get(XML::Node& node);
134 /**
135 * Retrieve a string key given a reference to an XML::Node.
136 *
137 * \param node Reference to a const XML::Node.
138 * \return The associated string key, or an empty string if no associated key could be found.
139 */
140 std::string const get(XML::Node const& node);
142 /**
143 * Remove an entry from the tracker based on key.
144 *
145 * \param The key of the entry to remove.
146 */
147 void remove(std::string& key);
149 /**
150 * Remove an entry from the tracker based on XML::Node.
151 *
152 * \param A reference to the XML::Node associated with the entry to remove.
153 */
154 void remove(XML::Node& node);
156 /**
157 * Return whether or not a (key,node) pair is being tracked, given a string key.
158 *
159 * \param The key associated with the pair to check.
160 * \return Whether or not the pair is being tracked.
161 */
162 bool isTracking(std::string& key);
164 /**
165 * Return whether or not a (key,node) pair is being tracked, given a string key.
166 *
167 * \param The key associated with the pair to check.
168 * \return Whether or not the pair is being tracked.
169 */
170 bool isTracking(std::string const& key);
172 /**
173 * Return whether or not a (key,node) pair is being tracked, given a node.
174 *
175 * \param The node associated with the pair to check.
176 * \return Whether or not the pair is being tracked.
177 */
178 bool isTracking(XML::Node& node);
180 /**
181 * Return whether or not a (key,node) pair is being tracked, given a node.
182 *
183 * \param The node associated with the pair to check.
184 * \return Whether or not the pair is being tracked.
185 */
186 bool isTracking(XML::Node const& node);
188 /**
189 * Return whether or not a node identified by a given name is a special node.
190 *
191 * \see Inkscape::Whiteboard::specialnodekeys
192 * \see Inkscape::Whiteboard::specialnodenames
193 *
194 * \param The name associated with the node.
195 * \return Whether or not the node is a special node.
196 */
197 bool isSpecialNode(char const* name);
199 /**
200 * Return whether or not a node identified by a given name is a special node.
201 *
202 * \see Inkscape::Whiteboard::specialnodekeys
203 * \see Inkscape::Whiteboard::specialnodenames
204 *
205 * \param The name associated with the node.
206 * \return Whether or not the node is a special node.
207 */
208 bool isSpecialNode(std::string const& name);
210 /**
211 * Retrieve the key of a special node given the name of a special node.
212 *
213 * \see Inkscape::Whiteboard::specialnodekeys
214 * \see Inkscape::Whiteboard::specialnodenames
215 *
216 * \param The name associated with the node.
217 * \return The key of the special node.
218 */
219 std::string const getSpecialNodeKeyFromName(Glib::ustring const& name);
221 /**
222 * Retrieve the key of a special node given the name of a special node.
223 *
224 * \see Inkscape::Whiteboard::specialnodekeys
225 * \see Inkscape::Whiteboard::specialnodenames
226 *
227 * \param The name associated with the node.
228 * \return The key of the special node.
229 */
230 std::string const getSpecialNodeKeyFromName(Glib::ustring const* name);
232 /**
233 * Returns whether or not the given node is the root node of the SPDocument associated
234 * with an XMLNodeTracker's SessionManager.
235 *
236 * \param Reference to an XML::Node to test.
237 * \return Whether or not the given node is the document root node.
238 */
239 bool isRootNode(XML::Node& node);
241 /**
242 * Generate a node key given a JID.
243 *
244 * \param The JID to use in the key.
245 * \return A node string key.
246 */
247 std::string generateKey(gchar const* JID);
249 /**
250 * Generate a node key given the JID specified in the SessionData structure associated
251 * with an XMLNodeTracker's SessionManager.
252 *
253 * \return A node string key.
254 */
255 std::string generateKey();
257 // TODO: remove debugging function
258 void dump();
259 void reset();
261 private:
262 void createSpecialNodeTables();
263 void _clear();
265 unsigned int _counter;
266 SessionManager* _sm;
268 // defined in typedefs.h
269 KeyToTrackerNodeMap _keyToNode;
270 TrackerNodeToKeyMap _nodeToKey;
272 std::map< char const*, char const*, strcmpless > _specialnodes;
274 // Keys for special nodes
275 std::string _rootKey;
276 std::string _defsKey;
277 std::string _namedviewKey;
278 std::string _metadataKey;
280 // noncopyable, nonassignable
281 XMLNodeTracker(XMLNodeTracker const&);
282 XMLNodeTracker& operator=(XMLNodeTracker const&);
283 };
285 }
287 }
290 #endif
291 /*
292 Local Variables:
293 mode:c++
294 c-file-style:"stroustrup"
295 c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
296 indent-tabs-mode:nil
297 fill-column:99
298 End:
299 */
300 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :