2
* Whiteboard session manager
3
* XML node tracking facility
6
* David Yip <yipdw@rose-hulman.edu>
8
* Copyright (c) 2005 Authors
10
* Released under GNU GPL, read the file 'COPYING' for more information
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"
26
namespace Whiteboard {
31
* std::less-like functor for C-style strings.
33
struct strcmpless : public std::binary_function< char const*, char const*, bool >
35
bool operator()(char const* _x, char const* _y) const
37
return (strcmp(_x, _y) < 0);
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.
50
* XMLNodeTracker generates and watches unique IDs for XML::Nodes for use in
51
* document event serialization and deserialization.
53
* More specifically, it has three tasks:
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>
60
* XML::Nodes are assigned an ID that follows one of two forms:
62
* <li>unsigned integer;user JID</li>
63
* <li>unsigned integer;chatroom@conference server/handle</li>
66
* Form 1 is used in user-to-user sessions; form 2 is used in chatroom sessions.
68
class XMLNodeTracker {
73
* \param sm The SessionManager with which an XMLNodeTracker instance is to be associated with.
75
XMLNodeTracker(SessionManager* sm);
79
* Insert a (key,node) pair into the tracker.
81
* \param key The key to associate with the node.
82
* \param node The node to associate with the key.
84
void put(std::string key, XML::Node& node);
87
* Insert a (key,node) pair into the tracker.
89
* \param key The key to associate with the node.
90
* \param node The node to associate with the key.
92
void put(std::string key, XML::Node const& node);
95
* Insert a range of (key,node) pairs into the tracker.
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.
101
void put(KeyToNodeMap& newids, NodeToKeyMap& newnodes);
104
* Process a list of node actions to add and remove nodes from the tracker.
106
* \param actions The action list to process.
108
void process(KeyToNodeActionList& actions);
111
* Retrieve an XML::Node given a key.
113
* \param key Reference to a string key.
114
* \return Pointer to an XML::Node, or NULL if no associated node could be found.
116
XML::Node* get(std::string& key);
119
* Retrieve an XML::Node given a key.
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.
124
XML::Node* get(std::string const& key);
127
* Retrieve a string key given a reference to an XML::Node.
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.
132
std::string const get(XML::Node& node);
135
* Retrieve a string key given a reference to an XML::Node.
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.
140
std::string const get(XML::Node const& node);
143
* Remove an entry from the tracker based on key.
145
* \param The key of the entry to remove.
147
void remove(std::string& key);
150
* Remove an entry from the tracker based on XML::Node.
152
* \param A reference to the XML::Node associated with the entry to remove.
154
void remove(XML::Node& node);
157
* Return whether or not a (key,node) pair is being tracked, given a string key.
159
* \param The key associated with the pair to check.
160
* \return Whether or not the pair is being tracked.
162
bool isTracking(std::string& key);
165
* Return whether or not a (key,node) pair is being tracked, given a string key.
167
* \param The key associated with the pair to check.
168
* \return Whether or not the pair is being tracked.
170
bool isTracking(std::string const& key);
173
* Return whether or not a (key,node) pair is being tracked, given a node.
175
* \param The node associated with the pair to check.
176
* \return Whether or not the pair is being tracked.
178
bool isTracking(XML::Node& node);
181
* Return whether or not a (key,node) pair is being tracked, given a node.
183
* \param The node associated with the pair to check.
184
* \return Whether or not the pair is being tracked.
186
bool isTracking(XML::Node const& node);
189
* Return whether or not a node identified by a given name is a special node.
191
* \see Inkscape::Whiteboard::specialnodekeys
192
* \see Inkscape::Whiteboard::specialnodenames
194
* \param The name associated with the node.
195
* \return Whether or not the node is a special node.
197
bool isSpecialNode(char const* name);
200
* Return whether or not a node identified by a given name is a special node.
202
* \see Inkscape::Whiteboard::specialnodekeys
203
* \see Inkscape::Whiteboard::specialnodenames
205
* \param The name associated with the node.
206
* \return Whether or not the node is a special node.
208
bool isSpecialNode(std::string const& name);
211
* Retrieve the key of a special node given the name of a special node.
213
* \see Inkscape::Whiteboard::specialnodekeys
214
* \see Inkscape::Whiteboard::specialnodenames
216
* \param The name associated with the node.
217
* \return The key of the special node.
219
std::string const getSpecialNodeKeyFromName(Glib::ustring const& name);
222
* Retrieve the key of a special node given the name of a special node.
224
* \see Inkscape::Whiteboard::specialnodekeys
225
* \see Inkscape::Whiteboard::specialnodenames
227
* \param The name associated with the node.
228
* \return The key of the special node.
230
std::string const getSpecialNodeKeyFromName(Glib::ustring const* name);
233
* Returns whether or not the given node is the root node of the SPDocument associated
234
* with an XMLNodeTracker's SessionManager.
236
* \param Reference to an XML::Node to test.
237
* \return Whether or not the given node is the document root node.
239
bool isRootNode(XML::Node& node);
242
* Generate a node key given a JID.
244
* \param The JID to use in the key.
245
* \return A node string key.
247
std::string generateKey(gchar const* JID);
250
* Generate a node key given the JID specified in the SessionData structure associated
251
* with an XMLNodeTracker's SessionManager.
253
* \return A node string key.
255
std::string generateKey();
257
// TODO: remove debugging function
262
void createSpecialNodeTables();
265
unsigned int _counter;
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&);
294
c-file-style:"stroustrup"
295
c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
300
// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :