content/base/public/nsINodeInfo.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla Communicator client code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /*
  39  * nsINodeInfo is an interface to node info, such as name, prefix, namespace
  40  * ID and possibly other data that is shared between nodes (elements
  41  * and attributes) that have the same name, prefix and namespace ID within
  42  * the same document.
  43  *
  44  * nsNodeInfoManager's are internal objects that manage a list of
  45  * nsINodeInfo's, every document object should hold a strong reference to
  46  * a nsNodeInfoManager and every nsINodeInfo also holds a strong reference
  47  * to their owning manager. When a nsINodeInfo is no longer used it will
  48  * automatically remove itself from its owner manager, and when all
  49  * nsINodeInfo's have been removed from a nsNodeInfoManager and all external
  50  * references are released the nsNodeInfoManager deletes itself.
  51  *
  52  * -- jst@netscape.com
  53  */
  54
  55 #ifndef nsINodeInfo_h___
  56 #define nsINodeInfo_h___
  57
  58 #include "nsISupports.h"
  59 #include "nsIAtom.h"
  60 #include "nsINameSpaceManager.h"
  61 #include "nsNodeInfoManager.h"
  62 #include "nsCOMPtr.h"
  63
  64 #ifdef MOZILLA_INTERNAL_API
  65 #include "nsDOMString.h"
  66 #endif
  67
  68 // Forward declarations
  69 class nsIDocument;
  70 class nsIURI;
  71 class nsIPrincipal;
  72
  73 // IID for the nsINodeInfo interface
  74 // 35e53115-b884-4cfc-aa95-bdf0aa5152cf
  75 #define NS_INODEINFO_IID      \
  76 { 0x35e53115, 0xb884, 0x4cfc, \
  77  { 0xaa, 0x95, 0xbd, 0xf0, 0xaa, 0x51, 0x52, 0xcf } }
  78
  79 class nsINodeInfo : public nsISupports
  80 {
  81 public:
  82   NS_DECLARE_STATIC_IID_ACCESSOR(NS_INODEINFO_IID)
  83
  84   nsINodeInfo()
  85     : mInner(nsnull, nsnull, kNameSpaceID_None),
  86       mOwnerManager(nsnull)
  87   {
  88   }
  89
  90   /*
  91    * Get the name from this node as a string, this does not include the prefix.
  92    *
  93    * For the HTML element "<body>" this will return "body" and for the XML
  94    * element "<html:body>" this will return "body".
  95    */
  96   void GetName(nsAString& aName) const
  97   {
  98     mInner.mName->ToString(aName);
  99   }
 100
 101   /*
 102    * Get the name from this node as an atom, this does not include the prefix.
 103    * This function never returns a null atom.
 104    *
 105    * For the HTML element "<body>" this will return the "body" atom and for
 106    * the XML element "<html:body>" this will return the "body" atom.
 107    */
 108   nsIAtom* NameAtom() const
 109   {
 110     return mInner.mName;
 111   }
 112
 113   /*
 114    * Get the qualified name from this node as a string, the qualified name
 115    * includes the prefix, if one exists.
 116    *
 117    * For the HTML element "<body>" this will return "body" and for the XML
 118    * element "<html:body>" this will return "html:body".
 119    */
 120   virtual void GetQualifiedName(nsAString& aQualifiedName) const = 0;
 121
 122   /*
 123    * Get the local name from this node as a string, GetLocalName() gets the
 124    * same string as GetName() but only if the node has a prefix and/or a
 125    * namespace URI. If the node has neither a prefix nor a namespace URI the
 126    * local name is a null string.
 127    *
 128    * For the HTML element "<body>" in a HTML document this will return a null
 129    * string and for the XML element "<html:body>" this will return "body".
 130    */
 131   virtual void GetLocalName(nsAString& aLocalName) const = 0;
 132
 133 #ifdef MOZILLA_INTERNAL_API
 134   /*
 135    * Get the prefix from this node as a string.
 136    *
 137    * For the HTML element "<body>" this will return a null string and for
 138    * the XML element "<html:body>" this will return the string "html".
 139    */
 140   void GetPrefix(nsAString& aPrefix) const
 141   {
 142     if (mInner.mPrefix) {
 143       mInner.mPrefix->ToString(aPrefix);
 144     } else {
 145       SetDOMStringToNull(aPrefix);
 146     }
 147   }
 148 #endif
 149
 150   /*
 151    * Get the prefix from this node as an atom.
 152    *
 153    * For the HTML element "<body>" this will return a null atom and for
 154    * the XML element "<html:body>" this will return the "html" atom.
 155    */
 156   nsIAtom* GetPrefixAtom() const
 157   {
 158     return mInner.mPrefix;
 159   }
 160
 161   /*
 162    * Get the namespace URI for a node, if the node has a namespace URI.
 163    *
 164    * For the HTML element "<body>" in a HTML document this will return a null
 165    * string and for the XML element "<html:body>" (assuming that this element,
 166    * or one of it's ancestors has an
 167    * xmlns:html='http://www.w3.org/1999/xhtml' attribute) this will return
 168    * the string "http://www.w3.org/1999/xhtml".
 169    */
 170   virtual nsresult GetNamespaceURI(nsAString& aNameSpaceURI) const = 0;
 171
 172   /*
 173    * Get the namespace ID for a node if the node has a namespace, if not this
 174    * returns kNameSpaceID_None.
 175    *
 176    * For the HTML element "<body>" in a HTML document this will return
 177    * kNameSpaceID_None and for the XML element "<html:body>" (assuming that
 178    * this element, or one of it's ancestors has an
 179    * xmlns:html='http://www.w3.org/1999/xhtml' attribute) this will return
 180    * the namespace ID for "http://www.w3.org/1999/xhtml".
 181    */
 182   PRInt32 NamespaceID() const
 183   {
 184     return mInner.mNamespaceID;
 185   }
 186
 187   /*
 188    * Get and set the ID attribute atom for this node.
 189    * See http://www.w3.org/TR/1998/REC-xml-19980210#sec-attribute-types
 190    * for the definition of an ID attribute.
 191    *
 192    */
 193   nsIAtom* GetIDAttributeAtom() const
 194   {
 195     return mIDAttributeAtom;
 196   }
 197
 198   void SetIDAttributeAtom(nsIAtom* aID)
 199   {
 200     mIDAttributeAtom = aID;
 201   }
 202
 203   /**
 204    * Get the owning node info manager. Only to be used inside Gecko, you can't
 205    * really do anything with the pointer outside Gecko anyway.
 206    */
 207   nsNodeInfoManager *NodeInfoManager() const
 208   {
 209     return mOwnerManager;
 210   }
 211
 212   /*
 213    * Utility functions that can be used to check if a nodeinfo holds a specific
 214    * name, name and prefix, name and prefix and namespace ID, or just
 215    * namespace ID.
 216    */
 217   PRBool Equals(nsINodeInfo *aNodeInfo) const
 218   {
 219     return aNodeInfo == this || aNodeInfo->Equals(mInner.mName, mInner.mPrefix,
 220                                                   mInner.mNamespaceID);
 221   }
 222
 223   PRBool NameAndNamespaceEquals(nsINodeInfo *aNodeInfo) const
 224   {
 225     return aNodeInfo == this || aNodeInfo->Equals(mInner.mName,
 226                                                   mInner.mNamespaceID);
 227   }
 228
 229   PRBool Equals(nsIAtom *aNameAtom) const
 230   {
 231     return mInner.mName == aNameAtom;
 232   }
 233
 234   PRBool Equals(nsIAtom *aNameAtom, nsIAtom *aPrefixAtom) const
 235   {
 236     return (mInner.mName == aNameAtom) && (mInner.mPrefix == aPrefixAtom);
 237   }
 238
 239   PRBool Equals(nsIAtom *aNameAtom, PRInt32 aNamespaceID) const
 240   {
 241     return ((mInner.mName == aNameAtom) &&
 242             (mInner.mNamespaceID == aNamespaceID));
 243   }
 244
 245   PRBool Equals(nsIAtom *aNameAtom, nsIAtom *aPrefixAtom,
 246                 PRInt32 aNamespaceID) const
 247   {
 248     return ((mInner.mName == aNameAtom) &&
 249             (mInner.mPrefix == aPrefixAtom) &&
 250             (mInner.mNamespaceID == aNamespaceID));
 251   }
 252
 253   PRBool NamespaceEquals(PRInt32 aNamespaceID) const
 254   {
 255     return mInner.mNamespaceID == aNamespaceID;
 256   }
 257
 258   virtual PRBool Equals(const nsAString& aName) const = 0;
 259   virtual PRBool Equals(const nsAString& aName,
 260                         const nsAString& aPrefix) const = 0;
 261   virtual PRBool Equals(const nsAString& aName,
 262                         PRInt32 aNamespaceID) const = 0;
 263   virtual PRBool Equals(const nsAString& aName, const nsAString& aPrefix,
 264                         PRInt32 aNamespaceID) const = 0;
 265   virtual PRBool NamespaceEquals(const nsAString& aNamespaceURI) const = 0;
 266
 267   PRBool QualifiedNameEquals(nsIAtom* aNameAtom) const
 268   {
 269     NS_PRECONDITION(aNameAtom, "Must have name atom");
 270     if (!GetPrefixAtom())
 271       return Equals(aNameAtom);
 272
 273     const char* utf8;
 274     aNameAtom->GetUTF8String(&utf8);
 275     return QualifiedNameEqualsInternal(nsDependentCString(utf8));
 276   }
 277
 278   PRBool QualifiedNameEquals(const nsACString& aQualifiedName) const
 279   {
 280     if (!GetPrefixAtom())
 281       return mInner.mName->EqualsUTF8(aQualifiedName);
 282
 283     return QualifiedNameEqualsInternal(aQualifiedName);
 284   }
 285
 286   /*
 287    * Retrieve a pointer to the document that owns this node info.
 288    */
 289   nsIDocument* GetDocument() const
 290   {
 291     return mOwnerManager->GetDocument();
 292   }
 293
 294 protected:
 295   virtual PRBool
 296     QualifiedNameEqualsInternal(const nsACString& aQualifiedName) const = 0;
 297
 298   /*
 299    * nsNodeInfoInner is used for two things:
 300    *
 301    *   1. as a member in nsNodeInfo for holding the name, prefix and
 302    *      namespace ID
 303    *   2. as the hash key in the hash table in nsNodeInfoManager
 304    *
 305    * nsNodeInfoInner does not do any kind of reference counting,
 306    * that's up to the user of this class. Since nsNodeInfoInner is
 307    * typically used as a member of nsNodeInfo, the hash table doesn't
 308    * need to delete the keys. When the value (nsNodeInfo) is deleted
 309    * the key is automatically deleted.
 310    */
 311
 312   class nsNodeInfoInner
 313   {
 314   public:
 315     nsNodeInfoInner(nsIAtom *aName, nsIAtom *aPrefix, PRInt32 aNamespaceID)
 316       : mName(aName), mPrefix(aPrefix), mNamespaceID(aNamespaceID)
 317     {
 318     }
 319
 320     nsIAtom*            mName;
 321     nsIAtom*            mPrefix;
 322     PRInt32             mNamespaceID;
 323   };
 324
 325   // nsNodeInfoManager needs to pass mInner to the hash table.
 326   friend class nsNodeInfoManager;
 327
 328   nsNodeInfoInner mInner;
 329
 330   nsCOMPtr<nsIAtom> mIDAttributeAtom;
 331   nsNodeInfoManager* mOwnerManager; // Strong reference!
 332 };
 333
 334 NS_DEFINE_STATIC_IID_ACCESSOR(nsINodeInfo, NS_INODEINFO_IID)
 335
 336 #endif /* nsINodeInfo_h___ */