src/jabber_whiteboard/node-tracker.h

   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  */
  12
  13 #ifndef __WHITEBOARD_XML_NODE_TRACKER_H__
  14 #define __WHITEBOARD_XML_NODE_TRACKER_H__
  15
  16 #include "jabber_whiteboard/tracker-node.h"
  17 #include "jabber_whiteboard/defines.h"
  18
  19 #include <bitset>
  20 #include <cstring>
  21 #include <map>
  22 #include <glibmm.h>
  23
  24 namespace Inkscape {
  25
  26 namespace Whiteboard {
  27
  28 class SessionManager;
  29
  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 };
  40
  41
  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.
  48
  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         XMLNodeTracker();
  74
  75         /**
  76          * Constructor.
  77          *
  78          * \param sm The SessionManager with which an XMLNodeTracker instance is to be associated with.
  79          */
  80         XMLNodeTracker(SessionManager* sm);
  81
  82     virtual ~XMLNodeTracker();
  83
  84         void setSessionManager(const SessionManager *val);
  85
  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(const Glib::ustring &key, const XML::Node &node);
  93
  94         /**
  95          * Process a list of node actions to add and remove nodes from the tracker.
  96          *
  97          * \param actions The action list to process.
  98          */
  99         void process(const KeyToNodeActionList& actions);
 100
 101         /**
 102          * Retrieve an XML::Node given a key.
 103          *
 104          * \param key Reference to a const string key.
 105          * \return Pointer to an XML::Node, or NULL if no associated node could be found.
 106          */
 107         XML::Node* get(const Glib::ustring &key);
 108
 109         /**
 110          * Retrieve a string key given a reference to an XML::Node.
 111          *
 112          * \param node Reference to a const XML::Node.
 113          * \return The associated string key, or an empty string if no associated key could be found.
 114          */
 115         Glib::ustring get(const XML::Node &node);
 116
 117         /**
 118          * Remove an entry from the tracker based on key.
 119          *
 120          * \param The key of the entry to remove.
 121          */
 122         void remove(const Glib::ustring& key);
 123
 124         /**
 125          * Remove an entry from the tracker based on XML::Node.
 126          *
 127          * \param A reference to the XML::Node associated with the entry to remove.
 128          */
 129         void remove(const XML::Node& node);
 130
 131         /**
 132          * Return whether or not a (key,node) pair is being tracked, given a string key.
 133          *
 134          * \param The key associated with the pair to check.
 135          * \return Whether or not the pair is being tracked.
 136          */
 137         bool isTracking(const Glib::ustring &key);
 138
 139         /**
 140          * Return whether or not a (key,node) pair is being tracked, given a node.
 141          *
 142          * \param The node associated with the pair to check.
 143          * \return Whether or not the pair is being tracked.
 144          */
 145         bool isTracking(const XML::Node & node);
 146
 147         /**
 148          * Return whether or not a node identified by a given name is a special node.
 149          *
 150          * \see Inkscape::Whiteboard::specialnodekeys
 151          * \see Inkscape::Whiteboard::specialnodenames
 152          *
 153          * \param The name associated with the node.
 154          * \return Whether or not the node is a special node.
 155          */
 156         bool isSpecialNode(Glib::ustring const& name);
 157
 158         /**
 159          * Retrieve the key of a special node given the name of a special node.
 160          *
 161          * \see Inkscape::Whiteboard::specialnodekeys
 162          * \see Inkscape::Whiteboard::specialnodenames
 163          *
 164          * \param The name associated with the node.
 165          * \return The key of the special node.
 166          */
 167         Glib::ustring getSpecialNodeKeyFromName(
 168                                const Glib::ustring &name);
 169
 170         /**
 171          * Returns whether or not the given node is the root node of the SPDocument associated
 172          * with an XMLNodeTracker's SessionManager.
 173          *
 174          * \param Reference to an XML::Node to test.
 175          * \return Whether or not the given node is the document root node.
 176          */
 177         bool isRootNode(const XML::Node& node);
 178
 179         /**
 180          * Generate a node key given a JID.
 181          *
 182          * \param The JID to use in the key.
 183          * \return A node string key.
 184          */
 185         Glib::ustring generateKey(gchar const* JID);
 186
 187         /**
 188          * Generate a node key given the JID specified in the SessionData structure associated
 189          * with an XMLNodeTracker's SessionManager.
 190          *
 191          * \return A node string key.
 192          */
 193         Glib::ustring generateKey();
 194
 195         // TODO: remove debugging function
 196         void dump();
 197         void reset();
 198
 199 private:
 200         //common code called by constructors
 201         void init();
 202
 203         void createSpecialNodeTables();
 204         void _clear();
 205
 206         unsigned int _counter;
 207         SessionManager* _sm;
 208
 209         //KeyNodeTable keyNodeTable;
 210
 211         std::map< char const*, char const*, strcmpless > _specialnodes;
 212
 213         // Keys for special nodes
 214         Glib::ustring _rootKey;
 215         Glib::ustring _defsKey;
 216         Glib::ustring _namedviewKey;
 217         Glib::ustring _metadataKey;
 218
 219         // noncopyable, nonassignable
 220         XMLNodeTracker(XMLNodeTracker const&);
 221         XMLNodeTracker& operator=(XMLNodeTracker const&);
 222 };
 223
 224 }
 225
 226 }
 227
 228
 229 #endif
 230 /*
 231   Local Variables:
 232   mode:c++
 233   c-file-style:"stroustrup"
 234   c-file-offsets:((innamespace . 0)(inline-open . 0))
 235   indent-tabs-mode:nil
 236   fill-column:99
 237   End:
 238 */
 239 // vim: filetype=c++:expandtab:shiftwidth=4:tabstop=8:softtabstop=4 :