1 #ifndef __DOM_H__
2 #define __DOM_H__
3 /**
4 * Phoebe DOM Implementation.
5 *
6 * This is a C++ approximation of the W3C DOM model, which follows
7 * fairly closely the specifications in the various .idl files, copies of
8 * which are provided for reference. Most important is this one:
9 *
10 * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/idl-definitions.html
11 *
12 * More thorough explanations of the various classes and their algorithms
13 * can be found there.
14 *
15 *
16 * Authors:
17 * Bob Jamison
18 *
19 * Copyright (C) 2006-2008 Bob Jamison
20 *
21 * This library is free software; you can redistribute it and/or
22 * modify it under the terms of the GNU Lesser General Public
23 * License as published by the Free Software Foundation; either
24 * version 2.1 of the License, or (at your option) any later version.
25 *
26 * This library is distributed in the hope that it will be useful,
27 * but WITHOUT ANY WARRANTY; without even the implied warranty of
28 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
29 * Lesser General Public License for more details.
30 *
31 * You should have received a copy of the GNU Lesser General Public
32 * License along with this library; if not, write to the Free Software
33 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
34 *
35 * =======================================================================
36 * NOTES:
37 *
38 * Notice that many of the classes defined here are pure virtual. In other
39 * words, they are purely unimplemented interfaces. For the implementations
40 * of them, look in domimpl.h and domimpl.cpp.
41 *
42 * Also, note that there is a domptr.cpp file that has a couple of necessary
43 * functions which cannot be in a .h file.
44 *
45 * Some of the comments below are quoted from the W3C spec:
46 * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html
47 *
48 */
50 #include <vector>
52 #include "domptr.h"
55 /**
56 * What type of string do we want? Pick one of the following
57 * Then below, select one of the corresponding typedefs.
58 */
60 #ifdef DOM_STANDALONE
61 #include <string>
62 #else
63 #include <glibmm.h>
64 #endif
66 //# Unfortunate hack for a name collision
67 #ifdef SEVERITY_ERROR
68 #undef SEVERITY_ERROR
69 #endif
71 #define XMLNSNAME "http://www.w3.org/2000/xmlns/"
73 namespace org
74 {
75 namespace w3c
76 {
77 namespace dom
78 {
81 /**
82 * This is the org::w3c::dom::DOMString definition.
83 * Which type do we want?
84 */
85 #ifdef DOM_STANDALONE
86 typedef std::string DOMString;
87 typedef unsigned short XMLCh;
88 #else
89 typedef Glib::ustring DOMString;
90 typedef gunichar XMLCh;
91 #endif
93 /**
94 * At least 64 bit time stamp value.
95 */
96 typedef unsigned long long DOMTimeStamp;
98 /**
99 * This is used for storing refs to user-supplied data.
100 */
101 typedef void DOMUserData;
105 /**
106 * This is used for opaque references to arbitrary objects from
107 * the DOM tree.
108 */
109 typedef void DOMObject;
112 /**
113 * Forward references. These are needed because of extensive
114 * inter-referencing within the DOM tree.
115 */
116 class NodeList;
117 class NamedNodeMap;
118 class DOMException;
119 class DOMStringList;
120 class NameList;
121 class DOMImplementationList;
122 class DOMImplementationSource;
123 class DOMImplementation;
124 class TypeInfo;
125 class UserDataHandler;
126 class DOMError;
127 class DOMErrorHandler;
128 class DOMLocator;
129 class DOMConfiguration;
131 /**
132 * Smart pointer definitions. Most methods that return references to
133 * Nodes of various types, will return one of these smart pointers instead,
134 * to allow refcounting and GC.
135 */
136 class Node;
137 typedef Ptr<Node> NodePtr;
138 class CharacterData;
139 typedef Ptr<CharacterData> CharacterDataPtr;
140 class Attr;
141 typedef Ptr<Attr> AttrPtr;
142 class Element;
143 typedef Ptr<Element> ElementPtr;
144 class Text;
145 typedef Ptr<Text> TextPtr;
146 class Comment;
147 typedef Ptr<Comment> CommentPtr;
148 class DocumentType;
149 typedef Ptr<DocumentType> DocumentTypePtr;
150 class CDATASection;
151 typedef Ptr<CDATASection> CDATASectionPtr;
152 class Notation;
153 typedef Ptr<Notation> NotationPtr;
154 class Entity;
155 typedef Ptr<Entity> EntityPtr;
156 class EntityReference;
157 typedef Ptr<EntityReference> EntityReferencePtr;
158 class ProcessingInstruction;
159 typedef Ptr<ProcessingInstruction> ProcessingInstructionPtr;
160 class DocumentFragment;
161 typedef Ptr<DocumentFragment> DocumentFragmentPtr;
162 class Document;
163 typedef Ptr<Document> DocumentPtr;
168 /**
169 * NOTE: We were originally intending to split ALL specifications into
170 * interface and implementation. After consideration, though, it behooves
171 * us to simplify things by implementing the base exception and
172 * container classes directly:
173 *
174 * DOMException
175 * DOMStringList
176 * NameList
177 * DOMImplementationList
178 * DOMImplementationSource
179 * DOMImplementation
180 * NodeList
181 * NamedNodeMap
182 */
185 /*#########################################################################
186 ## DOMException
187 #########################################################################*/
189 /**
190 * An Exception class. Not an interface, since this is something that
191 * all implementations must support.
192 */
193 class DOMException
194 {
196 public:
198 /**
199 * ExceptionCode
200 */
201 typedef enum
202 {
203 INDEX_SIZE_ERR = 1,
204 DOMSTRING_SIZE_ERR = 2,
205 HIERARCHY_REQUEST_ERR = 3,
206 WRONG_DOCUMENT_ERR = 4,
207 INVALID_CHARACTER_ERR = 5,
208 NO_DATA_ALLOWED_ERR = 6,
209 NO_MODIFICATION_ALLOWED_ERR = 7,
210 NOT_FOUND_ERR = 8,
211 NOT_SUPPORTED_ERR = 9,
212 INUSE_ATTRIBUTE_ERR = 10,
213 INVALID_STATE_ERR = 11,
214 SYNTAX_ERR = 12,
215 INVALID_MODIFICATION_ERR = 13,
216 NAMESPACE_ERR = 14,
217 INVALID_ACCESS_ERR = 15,
218 VALIDATION_ERR = 16,
219 TYPE_MISMATCH_ERR = 17
220 } ExceptionCode;
224 DOMException(const DOMString &reasonMsg)
225 { msg = reasonMsg; }
227 DOMException(short theCode)
228 {
229 code = theCode;
230 }
232 virtual ~DOMException() throw()
233 {}
235 /**
236 * What type of exception? One of the ExceptionCodes above.
237 */
238 unsigned short code;
240 /**
241 * Some text describing the context that generated this exception.
242 */
243 DOMString msg;
245 /**
246 * Get a string, translated from the code.
247 * Like std::exception. Not in spec.
248 */
249 const char *what()
250 { return (const char *)msg.c_str(); }
254 };
261 /*#########################################################################
262 ## DOMStringList
263 #########################################################################*/
265 /**
266 * This holds a list of DOMStrings. This is likely the response to a query,
267 * or the value of an attribute.
268 */
269 class DOMStringList
270 {
271 public:
273 /**
274 * Get the nth string of the list
275 */
276 virtual DOMString item(unsigned long index)
277 {
278 if (index>=strings.size())
279 return "";
280 return strings[index];
281 }
283 /**
284 * How many strings in this list?
285 */
286 virtual unsigned long getLength()
287 {
288 return (unsigned long) strings.size();
289 }
291 /**
292 * Is the argument string present in this list? Lexically, not identically.
293 */
294 virtual bool contains(const DOMString &str)
295 {
296 for (unsigned int i=0; i<strings.size() ; i++)
297 {
298 if (strings[i] == str)
299 return true;
300 }
301 return false;
302 }
305 //##################
306 //# Non-API methods
307 //##################
309 /**
310 *
311 */
312 DOMStringList() {}
315 /**
316 *
317 */
318 DOMStringList(const DOMStringList &other)
319 {
320 strings = other.strings;
321 }
323 /**
324 *
325 */
326 DOMStringList &operator=(const DOMStringList &other)
327 {
328 strings = other.strings;
329 return *this;
330 }
332 /**
333 *
334 */
335 virtual ~DOMStringList() {}
338 protected:
340 /**
341 *
342 */
343 virtual void add(const DOMString &str)
344 {
345 strings.push_back(str);
346 }
348 std::vector<DOMString>strings;
350 };
354 /*#########################################################################
355 ## NameList
356 #########################################################################*/
359 /**
360 * Constains a list of namespaced names.
361 */
362 class NameList
363 {
364 private:
366 class NamePair
367 {
368 public:
369 NamePair(const DOMString &theNamespaceURI, const DOMString &theName)
370 {
371 namespaceURI = theNamespaceURI;
372 name = theName;
373 }
374 NamePair(const NamePair &other)
375 {
376 namespaceURI = other.namespaceURI;
377 name = other.name;
378 }
379 NamePair &operator=(const NamePair &other)
380 {
381 namespaceURI = other.namespaceURI;
382 name = other.name;
383 return *this;
384 }
385 virtual ~NamePair() {}
387 DOMString namespaceURI;
388 DOMString name;
389 };
391 public:
393 /**
394 * Returns a name at the given index. If out of range, return -1.
395 */
396 virtual DOMString getName(unsigned long index)
397 {
398 if (index>=namePairs.size())
399 return "";
400 return namePairs[index].name;
401 }
403 /**
404 * Returns a namespace at the given index. If out of range, return -1.
405 */
406 virtual DOMString getNamespaceURI(unsigned long index)
407 {
408 if (index>=namePairs.size())
409 return "";
410 return namePairs[index].namespaceURI;
411 }
413 /**
414 * Return the number of entries in this list.
415 */
416 virtual unsigned long getLength()
417 {
418 return (unsigned long)namePairs.size();
419 }
421 /**
422 * Return whether the name argument is present in the list.
423 * This is done lexically, not identically.
424 */
425 virtual bool contains(const DOMString &name)
426 {
427 for (unsigned int i=0; i<namePairs.size() ; i++)
428 {
429 if (namePairs[i].name == name )
430 return true;
431 }
432 return false;
433 }
435 /**
436 * Return whether the namespaced name argument is present in the list.
437 * This is done lexically, not identically.
438 */
439 virtual bool containsNS(const DOMString namespaceURI,const DOMString &name)
440 {
441 for (unsigned int i=0; i<namePairs.size() ; i++)
442 {
443 if (namePairs[i].namespaceURI == namespaceURI ||
444 namePairs[i].name == name )
445 return true;
446 }
447 return false;
448 }
451 //##################
452 //# Non-API methods
453 //##################
455 /**
456 *
457 */
458 NameList() {}
460 /**
461 *
462 */
463 NameList(const NameList &other)
464 {
465 namePairs = other.namePairs;
466 }
468 /**
469 *
470 */
471 NameList &operator=(const NameList &other)
472 {
473 namePairs = other.namePairs;
474 return *this;
475 }
477 /**
478 *
479 */
480 virtual ~NameList() {}
483 protected:
485 std::vector<NamePair> namePairs;
487 };
489 /*#########################################################################
490 ## DOMImplementationList
491 #########################################################################*/
493 /**
494 * Contains a list of DOMImplementations, with accessors.
495 */
496 class DOMImplementationList
497 {
498 public:
500 /**
501 * Return a DOMImplementation at the given index. If
502 * out of range, return NULL.
503 */
504 virtual DOMImplementation *item(unsigned long index)
505 {
506 if (index >implementations.size())
507 return NULL;
508 return implementations[index];
509 }
511 /**
512 * Return the number of DOMImplementations in this list.
513 */
514 virtual unsigned long getLength()
515 {
516 return (unsigned long) implementations.size();
517 }
520 //##################
521 //# Non-API methods
522 //##################
524 /**
525 *
526 */
527 DOMImplementationList() {}
530 /**
531 *
532 */
533 DOMImplementationList(const DOMImplementationList &other)
534 {
535 implementations = other.implementations;
536 }
538 /**
539 *
540 */
541 DOMImplementationList &operator=(const DOMImplementationList &other)
542 {
543 implementations = other.implementations;
544 return *this;
545 }
547 /**
548 *
549 */
550 virtual ~DOMImplementationList() {}
552 protected:
554 std::vector<DOMImplementation *>implementations;
556 };
559 /*#########################################################################
560 ## DOMImplementationSource
561 #########################################################################*/
563 /**
564 * This is usually the first item to be called when creating a Document.
565 * You will either find one DOMImplementation with a given set of features,
566 * or return a list that match. Using "" will get any implementation
567 * available.
568 */
569 class DOMImplementationSource
570 {
571 public:
573 /**
574 * Return the first DOMImplementation with the given set of features.
575 * Use "" to fetch any implementation.
576 */
577 virtual DOMImplementation *getDOMImplementation(const DOMString &features) = 0;
579 /**
580 * Return a list of DOMImplementations with the given set of features.
581 * Use "" to fetch any implementation.
582 */
583 virtual DOMImplementationList getDOMImplementationList(const DOMString &features) = 0;
585 //##################
586 //# Non-API methods
587 //##################
589 /**
590 *
591 */
592 virtual ~DOMImplementationSource() {}
594 };
600 /*#########################################################################
601 ## DOMImplementation
602 #########################################################################*/
604 /**
605 * This is the class that actually creates a Document.
606 */
607 class DOMImplementation
608 {
609 public:
611 /**
612 * Determine if this implementation has the given feature and version.
613 */
614 virtual bool hasFeature(const DOMString& feature, const DOMString& version) = 0;
617 /**
618 * Create a document type to be used in creating documents.
619 */
620 virtual DocumentTypePtr createDocumentType(
621 const DOMString& qualifiedName,
622 const DOMString& publicId,
623 const DOMString& systemId)
624 throw(DOMException) = 0;
626 /**
627 * Create a DOM document.
628 */
629 virtual DocumentPtr createDocument(const DOMString& namespaceURI,
630 const DOMString& qualifiedName,
631 DocumentTypePtr doctype)
632 throw(DOMException) = 0;
633 /**
634 * Return the thing which is the feature of this implementation. Since
635 * this is a "one size fits all" call, you will need to typecast the
636 * result to the expected type.
637 */
638 virtual DOMObject *getFeature(const DOMString& feature,
639 const DOMString& version) = 0;
642 //##################
643 //# Non-API methods
644 //##################
646 /**
647 *
648 */
649 virtual ~DOMImplementation() {}
651 };
657 /*#########################################################################
658 ## Node
659 #########################################################################*/
661 /**
662 * The basic Node class, which is the root of most other
663 * classes in DOM. Thus it is by far the most important, and the one
664 * whose implementation we must perform correctly.
665 */
666 class Node
667 {
668 public:
670 /**
671 * Which of the DOM Core node types is this node?
672 */
673 typedef enum
674 {
675 ELEMENT_NODE = 1,
676 ATTRIBUTE_NODE = 2,
677 TEXT_NODE = 3,
678 CDATA_SECTION_NODE = 4,
679 ENTITY_REFERENCE_NODE = 5,
680 ENTITY_NODE = 6,
681 PROCESSING_INSTRUCTION_NODE = 7,
682 COMMENT_NODE = 8,
683 DOCUMENT_NODE = 9,
684 DOCUMENT_TYPE_NODE = 10,
685 DOCUMENT_FRAGMENT_NODE = 11,
686 NOTATION_NODE = 12
687 } NodeType;
689 /**
690 * Return the name of this node.
691 */
692 virtual DOMString getNodeName() = 0;
694 /**
695 * Return the value of this node. The interpretation of the
696 * value is type-specific.
697 */
698 virtual DOMString getNodeValue() throw (DOMException) = 0;
700 /**
701 * Set the value of this node. The interpretation of the
702 * value is type-specific.
703 */
704 virtual void setNodeValue(const DOMString& val) throw (DOMException) = 0;
706 /**
707 * Return the type of this Node. One of the NodeType values above.
708 */
709 virtual unsigned short getNodeType() = 0;
711 /**
712 * Return the parent which references this node as a child in the DOM
713 * tree. Return NULL if there is none.
714 */
715 virtual NodePtr getParentNode() = 0;
717 /**
718 * Return a list of the children of this Node.
719 * NOTE: the spec expects this to be a "live" list that always
720 * reflects an accurate list of what the Node current possesses, not
721 * a snapshot. How do we do this?
722 */
723 virtual NodeList getChildNodes() = 0;
725 /**
726 * Return the first sibling of the chidren of this node. Return
727 * null if there is none.
728 */
729 virtual NodePtr getFirstChild() = 0;
731 /**
732 * Return the last sibling of the children of this node. Return
733 * null if there is none.
734 */
735 virtual NodePtr getLastChild() = 0;
737 /**
738 * Return the node that is previous to this one in the parent's
739 * list of children. Return null if there is none.
740 */
741 virtual NodePtr getPreviousSibling() = 0;
743 /**
744 * Return the node that is after this one in the parent's list
745 * of children. Return null if there is none.
746 */
747 virtual NodePtr getNextSibling() = 0;
749 /**
750 * Get the list of all attributes of this node.
751 */
752 virtual NamedNodeMap &getAttributes() = 0;
755 /**
756 * Return the document that created or inherited this node.
757 */
758 virtual DocumentPtr getOwnerDocument() = 0;
760 /**
761 * Insert a node as a new child. Place it before the referenced child.
762 * Place it at the end if the referenced child does not exist.
763 */
764 virtual NodePtr insertBefore(const NodePtr newChild,
765 const NodePtr refChild)
766 throw(DOMException) = 0;
768 /**
769 * Insert a node as a new child. Replace the referenced child with it.
770 * Place it at the end if the referenced child does not exist.
771 */
772 virtual NodePtr replaceChild(const NodePtr newChild,
773 const NodePtr oldChild)
774 throw(DOMException) = 0;
776 /**
777 * Remove a node from the list of children. Do nothing if the
778 * node is not a member of the child list.
779 */
780 virtual NodePtr removeChild(const NodePtr oldChild)
781 throw(DOMException) = 0;
783 /**
784 * Add the node to the end of this node's child list.
785 */
786 virtual NodePtr appendChild(const NodePtr newChild)
787 throw(DOMException) = 0;
789 /**
790 * Return true if this node has one or more children, else return false.
791 */
792 virtual bool hasChildNodes() = 0;
794 /**
795 * Return a new node which has the name, type, value, attributes, and
796 * child list as this one.
797 * If 'deep' is true, continue cloning recursively with this node's children,
798 * so that the child list also contains clones of their respective nodes.
799 */
800 virtual NodePtr cloneNode(bool deep) = 0;
802 /**
803 * Adjust this node and its children to have its namespaces and
804 * prefixes in "canonical" order.
805 */
806 virtual void normalize() = 0;
808 /**
809 * Return true if the named feature is supported by this node,
810 * else false.
811 */
812 virtual bool isSupported(const DOMString& feature,
813 const DOMString& version) = 0;
815 /**
816 * Return the namespace of this node. This would be whether the
817 * namespace were declared explicitly on this node, it has a namespace
818 * prefix, or it is inherits the namespace from an ancestor node.
819 */
820 virtual DOMString getNamespaceURI() = 0;
822 /**
823 * Return the namespace prefix of this node, if any. For example, if
824 * the tag were <svg:image> then the prefix would be "svg"
825 */
826 virtual DOMString getPrefix() = 0;
828 /**
829 * Sets the namespace prefix of this node to the given value. This
830 * does not change the namespaceURI value.
831 */
832 virtual void setPrefix(const DOMString& val) throw(DOMException) = 0;
834 /**
835 * Return the local name of this node. This is merely the name without
836 * any namespace or prefix.
837 */
838 virtual DOMString getLocalName() = 0;
840 /**
841 * Return true if this node has one or more attributes, else false.
842 */
843 virtual bool hasAttributes() = 0;
845 /**
846 * Return the base URI of this node. This is basically the "location" of this
847 * node, and is used in resolving the relative locations of other URIs.
848 */
849 virtual DOMString getBaseURI() = 0;
851 /**
852 * DocumentPosition.
853 * This is used to describe the position of one node relative
854 * to another in a document
855 */
856 typedef enum
857 {
858 DOCUMENT_POSITION_DISCONNECTED = 0x01,
859 DOCUMENT_POSITION_PRECEDING = 0x02,
860 DOCUMENT_POSITION_FOLLOWING = 0x04,
861 DOCUMENT_POSITION_CONTAINS = 0x08,
862 DOCUMENT_POSITION_CONTAINED_BY = 0x10,
863 DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20
864 } DocumentPosition;
867 /**
868 * Get the position of this node relative to the node argument.
869 */
870 virtual unsigned short compareDocumentPosition(
871 const NodePtr other) = 0;
873 /**
874 * This is a DOM L3 method. Return the text value of this node and its
875 * children. This is done by concatenating all of the TEXT_NODE and
876 * CDATA_SECTION nodes of this node and its children, in order, together.
877 * Very handy.
878 */
879 virtual DOMString getTextContent() throw(DOMException) = 0;
882 /**
883 * This is a DOM L3 method. Remember, this is a destructive call. This
884 * will replace all of the child nodes of this node with a single TEXT_NODE
885 * with the given text value.
886 */
887 virtual void setTextContent(const DOMString &val) throw(DOMException) = 0;
890 /**
891 * This will search the tree from this node up, for a prefix that
892 * has been assigned to the namespace argument. Return "" if not found.
893 */
894 virtual DOMString lookupPrefix(const DOMString &namespaceURI) =0;
897 /**
898 * Return true if this node is in the namespace of the argument, without
899 * requiring an explicit namespace declaration or a suffix.
900 */
901 virtual bool isDefaultNamespace(const DOMString &namespaceURI) =0;
904 /**
905 * This will search the tree from this node up, for a namespace that
906 * has been assigned the suffix in the argument. Return "" if not found.
907 */
908 virtual DOMString lookupNamespaceURI(const DOMString &prefix) =0;
911 /**
912 * Return true if the argument node is equal to this one. Use W3C rules
913 * for equality.
914 */
915 virtual bool isEqualNode(const NodePtr node) =0;
919 /**
920 * Return an opaque reference to the named feature. Return null if
921 * not supported. Using other than "" for the version will look for
922 * a feature with the given version.
923 */
924 virtual DOMObject *getFeature(const DOMString &feature,
925 const DOMString &version) =0;
927 /**
928 * Store a user data reference in this node, using the given key.
929 * A handler is an optional function object that will be called during
930 * future settings of this value. See UserDataHandler for more info.
931 */
932 virtual DOMUserData *setUserData(const DOMString &key,
933 const DOMUserData *data,
934 const UserDataHandler *handler) =0;
937 /**
938 * Return a reference to the named user data object. Return null
939 * if it does not exist.
940 */
941 virtual DOMUserData *getUserData(const DOMString &key) =0;
943 //##################
944 //# Non-API methods
945 //##################
947 /**
948 *
949 */
950 Node() : _refCnt(0)
951 {}
953 /**
954 *
955 */
956 virtual ~Node() {}
958 protected:
960 friend void incrementRefCount(Node *p);
961 friend void decrementRefCount(Node *p);
963 /**
964 * For the Ptr smart pointer
965 */
966 int _refCnt;
968 };
973 /*#########################################################################
974 ## NodeList
975 #########################################################################*/
977 /**
978 * Contains a list of Nodes. This is the standard API container for Nodes,
979 * and is used in lieu of other lists, arrays, etc, in order to provide
980 * a consistent API and algorithm.
981 */
982 class NodeList
983 {
984 public:
986 /**
987 * Retrieve the Node at the given index. Return NULL
988 * if out of range.
989 */
990 virtual NodePtr item(unsigned long index)
991 {
992 if (index>=nodes.size())
993 return NULL;
994 return nodes[index];
995 }
997 /**
998 * Get the number of nodes in this list
999 */
1000 virtual unsigned long getLength()
1001 {
1002 return (unsigned long) nodes.size();
1003 }
1006 //##################
1007 //# Non-API methods
1008 //##################
1010 /**
1011 *
1012 */
1013 NodeList() {}
1015 /**
1016 *
1017 */
1018 NodeList(const NodeList &other)
1019 {
1020 nodes = other.nodes;
1021 }
1023 /**
1024 *
1025 */
1026 NodeList &operator=(const NodeList &other)
1027 {
1028 nodes = other.nodes;
1029 return *this;
1030 }
1032 /**
1033 *
1034 */
1035 virtual ~NodeList() {}
1037 /**
1038 *
1039 */
1040 virtual void clear()
1041 {
1042 nodes.clear();
1043 }
1045 protected:
1047 friend class NodeImpl;
1048 friend class ElementImpl;
1050 /*
1051 *
1052 */
1053 virtual void add(const NodePtr node)
1054 {
1055 nodes.push_back(node);
1056 }
1058 protected:
1060 std::vector<NodePtr> nodes;
1062 };
1067 /*#########################################################################
1068 ## NamedNodeMap
1069 #########################################################################*/
1071 /**
1072 * Contains a mapping from name->NodePtr. Used for various purposes. For
1073 * example, a list of Attributes is a NamedNodeMap.
1074 */
1075 class NamedNodeMap
1076 {
1077 private:
1079 /**
1080 * table entry. Not an API item
1081 */
1082 class NamedNodeMapEntry
1083 {
1084 public:
1085 NamedNodeMapEntry(const DOMString &theNamespaceURI,
1086 const DOMString &theName,
1087 const NodePtr theNode)
1088 {
1089 namespaceURI = theNamespaceURI;
1090 name = theName;
1091 node = theNode;
1092 }
1093 NamedNodeMapEntry(const NamedNodeMapEntry &other)
1094 {
1095 assign(other);
1096 }
1097 NamedNodeMapEntry &operator=(const NamedNodeMapEntry &other)
1098 {
1099 assign(other);
1100 return *this;
1101 }
1102 virtual ~NamedNodeMapEntry()
1103 {
1104 }
1105 void assign(const NamedNodeMapEntry &other)
1106 {
1107 namespaceURI = other.namespaceURI;
1108 name = other.name;
1109 node = other.node;
1110 }
1111 DOMString namespaceURI;
1112 DOMString name;
1113 NodePtr node;
1114 };
1117 public:
1119 /**
1120 * Return the named node. Return nullptr if not found.
1121 */
1122 virtual NodePtr getNamedItem(const DOMString& name)
1123 {
1124 std::vector<NamedNodeMapEntry>::iterator iter;
1125 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1126 {
1127 if (iter->name == name)
1128 {
1129 NodePtr node = iter->node;
1130 return node;
1131 }
1132 }
1133 return NULL;
1134 }
1136 /**
1137 * Adds a node using its nodeName attribute. If a node with that name is already
1138 * present in this map, it is replaced by the new one. Replacing a node by itself
1139 * has no effect.
1140 */
1141 virtual NodePtr setNamedItem(NodePtr arg) throw(DOMException)
1142 {
1143 if (!arg)
1144 return NULL;
1145 DOMString namespaceURI = arg->getNamespaceURI();
1146 DOMString name = arg->getNodeName();
1147 std::vector<NamedNodeMapEntry>::iterator iter;
1148 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1149 {
1150 if (iter->name == name)
1151 {
1152 NodePtr node = iter->node;
1153 iter->node = arg;
1154 return node;
1155 }
1156 }
1157 NamedNodeMapEntry entry(namespaceURI, name, arg);
1158 entries.push_back(entry);
1159 return arg;
1160 }
1163 /**
1164 * Removes a node specified by name.
1165 */
1166 virtual NodePtr removeNamedItem(const DOMString& name) throw(DOMException)
1167 {
1168 std::vector<NamedNodeMapEntry>::iterator iter;
1169 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1170 {
1171 if (iter->name == name)
1172 {
1173 NodePtr node = iter->node;
1174 entries.erase(iter);
1175 return node;
1176 }
1177 }
1178 return NULL;
1179 }
1181 /**
1182 * Retrieves an item at the given index. If out of bounds, return NULL
1183 */
1184 virtual NodePtr item(unsigned long index)
1185 {
1186 if (index>=entries.size())
1187 return NULL;
1188 return entries[index].node;
1189 }
1191 /**
1192 * Return the number of items in this map
1193 */
1194 virtual unsigned long getLength()
1195 {
1196 return (unsigned long)entries.size();
1197 }
1199 /**
1200 * Retrieves a node specified by local name and namespace URI.
1201 */
1202 virtual NodePtr getNamedItemNS(const DOMString& namespaceURI,
1203 const DOMString& localName)
1204 {
1205 std::vector<NamedNodeMapEntry>::iterator iter;
1206 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1207 {
1208 if (iter->namespaceURI == namespaceURI && iter->name == localName)
1209 {
1210 NodePtr node = iter->node;
1211 return node;
1212 }
1213 }
1214 return NULL;
1215 }
1217 /**
1218 * Adds a node using its namespaceURI and localName. If a node with that
1219 * namespace URI and that local name is already present in this map, it is
1220 * replaced by the new one. Replacing a node by itself has no effect.
1221 */
1222 virtual NodePtr setNamedItemNS(NodePtr arg) throw(DOMException)
1223 {
1224 if (!arg)
1225 return NULL;
1226 DOMString namespaceURI = arg->getNamespaceURI();
1227 DOMString name = arg->getNodeName();
1228 std::vector<NamedNodeMapEntry>::iterator iter;
1229 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1230 {
1231 if (iter->namespaceURI == namespaceURI && iter->name == name)
1232 {
1233 NodePtr node = iter->node;
1234 iter->node = arg;
1235 return node;
1236 }
1237 }
1238 NamedNodeMapEntry entry(namespaceURI, name, arg);
1239 entries.push_back(entry);
1240 return arg;
1241 }
1243 /**
1244 * Removes a node specified by local name and namespace URI.
1245 */
1246 virtual NodePtr removeNamedItemNS(const DOMString& namespaceURI,
1247 const DOMString& localName)
1248 throw(DOMException)
1249 {
1250 std::vector<NamedNodeMapEntry>::iterator iter;
1251 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1252 {
1253 if (iter->namespaceURI == namespaceURI && iter->name == localName)
1254 {
1255 NodePtr node = iter->node;
1256 entries.erase(iter);
1257 return node;
1258 }
1259 }
1260 return NULL;
1261 }
1264 //##################
1265 //# Non-API methods
1266 //##################
1268 /**
1269 *
1270 */
1271 NamedNodeMap() {}
1274 /**
1275 *
1276 */
1277 NamedNodeMap(const NamedNodeMap &other)
1278 {
1279 entries = other.entries;
1280 }
1282 /**
1283 *
1284 */
1285 NamedNodeMap &operator=(const NamedNodeMap &other)
1286 {
1287 entries = other.entries;
1288 return *this;
1289 }
1292 /**
1293 *
1294 */
1295 virtual ~NamedNodeMap() {}
1297 protected:
1299 std::vector<NamedNodeMapEntry> entries;
1301 };
1306 /*#########################################################################
1307 ## CharacterData
1308 #########################################################################*/
1310 /**
1311 * This is the base class for other text-oriented Nodes, such as TEXT_NODE
1312 * or CDATA_SECTION_NODE. No DOM objects correspond directly to CharacterData.
1313 */
1314 class CharacterData : virtual public Node
1315 {
1316 public:
1318 /**
1319 * This is an alias for getNodeValue()
1320 */
1321 virtual DOMString getData() throw(DOMException) = 0;
1323 /**
1324 * This is an alias for setNodeValue()
1325 */
1326 virtual void setData(const DOMString& val) throw(DOMException) = 0;
1328 /**
1329 * Return the number of characters contained in this node's data
1330 */
1331 virtual unsigned long getLength() = 0;
1333 /**
1334 * Return a substring of this node's data, starting at offset, and
1335 * continuing for 'count' characters. Throw an exception if this goes
1336 * out of range.
1337 */
1338 virtual DOMString substringData(unsigned long offset,
1339 unsigned long count)
1340 throw(DOMException) = 0;
1342 /**
1343 * Append the argument string to the end of the node's current data.
1344 */
1345 virtual void appendData(const DOMString& arg) throw(DOMException) = 0;
1347 /**
1348 * Insert the argument string at the offset position into the node's
1349 * current data. If the position is out of range, throw an Exception.
1350 */
1351 virtual void insertData(unsigned long offset,
1352 const DOMString& arg)
1353 throw(DOMException) = 0;
1355 /**
1356 * Delete 'count' characters from the node's data starting from the
1357 * offset position. If this goes out of range, throw an Exception.
1358 */
1359 virtual void deleteData(unsigned long offset,
1360 unsigned long count)
1361 throw(DOMException) = 0;
1363 /**
1364 * Replace the 'count' characters at the offset position with the given
1365 * argument string. If this goes out of range, throw an Exception.
1366 */
1367 virtual void replaceData(unsigned long offset,
1368 unsigned long count,
1369 const DOMString& arg)
1370 throw(DOMException) = 0;
1373 //##################
1374 //# Non-API methods
1375 //##################
1378 /**
1379 *
1380 */
1381 virtual ~CharacterData() {}
1383 };
1388 /*#########################################################################
1389 ## Attr
1390 #########################################################################*/
1392 /**
1393 * The Attr interface represents an attribute in an Element object.
1394 * Typically the allowable values for the attribute are defined in a
1395 * schema associated with the document.
1396 * Since Attrs are not considered to be part of the DOM tree, parent,
1397 * previousSibling, and nextSibling are null.
1398 */
1399 class Attr : virtual public Node
1400 {
1401 public:
1403 /**
1404 * Returns the name of this attribute. If Node.localName is different
1405 * from null, this attribute is a qualified name.
1406 */
1407 virtual DOMString getName() = 0;
1409 /**
1410 * True if this attribute was explicitly given a value in the instance document,
1411 * false otherwise. If the application changed the value of this attribute node
1412 * (even if it ends up having the same value as the default value) then it is set
1413 * to true. The implementation may handle attributes with default values from
1414 * other schemas similarly but applications should use
1415 * Document.normalizeDocument() to guarantee this information is up-to-date.
1416 */
1417 virtual bool getSpecified() = 0;
1419 /**
1420 * Returns the value of the attribute
1421 */
1422 virtual DOMString getValue() = 0;
1424 /**
1425 * Sets the value of the attribute
1426 */
1427 virtual void setValue(const DOMString& val) throw(DOMException) = 0;
1429 /**
1430 * Return the Element that possesses this attribute
1431 */
1432 virtual ElementPtr getOwnerElement() = 0;
1435 /**
1436 * The type information associated with this attribute.
1437 */
1438 virtual TypeInfo &getSchemaTypeInfo() = 0;
1441 /**
1442 * Returns whether this attribute is known to be of type ID (i.e. to contain an
1443 * identifier for its owner element) or not. When it is and its value is unique,
1444 * the ownerElement of this attribute can be retrieved using the method
1445 * Document.getElementById.
1446 */
1447 virtual bool getIsId() = 0;
1449 //##################
1450 //# Non-API methods
1451 //##################
1454 /**
1455 *
1456 */
1457 virtual ~Attr() {}
1459 };
1465 /*#########################################################################
1466 ## Element
1467 #########################################################################*/
1469 /**
1470 * The Element interface represents an element in an XML document.
1471 * Elements may have attributes associated with them; since the Element interface
1472 * inherits from Node, the generic Node interface attribute attributes may be
1473 * used to retrieve the set of all attributes for an element. There are methods
1474 * on the Element interface to retrieve either an Attr object by name or an
1475 * attribute value by name. In XML, where an attribute value may contain entity
1476 * references, an Attr object should be retrieved to examine the possibly fairly
1477 * complex sub-tree representing the attribute value. On the other hand, in HTML,
1478 * where all attributes have simple string values, methods to directly access an
1479 * attribute value can safely be used as a convenience.
1480 */
1481 class Element : virtual public Node
1482 {
1483 public:
1486 /**
1487 * The name of the element. If Node.localName is different from null,
1488 * this attribute is a qualified name.
1489 */
1490 virtual DOMString getTagName() = 0;
1492 /**
1493 * Retrieves an attribute value by name.
1494 */
1495 virtual DOMString getAttribute(const DOMString& name) = 0;
1497 /**
1498 * Adds a new attribute. If an attribute with that name is already present in the
1499 * element, its value is changed to be that of the value parameter. This value is
1500 * a simple string; it is not parsed as it is being set. So any markup (such as
1501 * syntax to be recognized as an entity reference) is treated as literal text,
1502 * and needs to be appropriately escaped by the implementation when it is written
1503 * out. In order to assign an attribute value that contains entity references,
1504 * the user must create an Attr node plus any Text and EntityReference nodes,
1505 * build the appropriate subtree, and use setAttributeNode to assign it as the
1506 * value of an attribute.
1507 */
1508 virtual void setAttribute(const DOMString& name,
1509 const DOMString& value)
1510 throw(DOMException) = 0;
1512 /**
1513 * Removes an attribute by name. If no attribute with this name is found,
1514 * this method has no effect.
1515 */
1516 virtual void removeAttribute(const DOMString& name)
1517 throw(DOMException) = 0;
1519 /**
1520 * Retrieves an attribute node by name.
1521 */
1522 virtual AttrPtr getAttributeNode(const DOMString& name) = 0;
1524 /**
1525 * Adds a new attribute node. If an attribute with that name (nodeName)
1526 * is already present in the element, it is replaced by the new one.
1527 * Replacing an attribute node by itself has no effect.
1528 */
1529 virtual AttrPtr setAttributeNode(AttrPtr newAttr)
1530 throw(DOMException) = 0;
1532 /**
1533 * Removes the specified attribute node.
1534 */
1535 virtual AttrPtr removeAttributeNode(AttrPtr oldAttr)
1536 throw(DOMException) = 0;
1538 /**
1539 * Returns a NodeList of all descendant Elements with a given tag name,
1540 * in document order.
1541 */
1542 virtual NodeList getElementsByTagName(const DOMString& name) = 0;
1544 /**
1545 * Retrieves an attribute value by local name and namespace URI.
1546 * Per [XML Namespaces], applications must use the value null as the
1547 * namespaceURI parameter for methods if they wish to have no namespace.
1548 */
1549 virtual DOMString getAttributeNS(const DOMString& namespaceURI,
1550 const DOMString& localName) = 0;
1552 /**
1553 * Adds a new attribute. If an attribute with the same local name and namespace
1554 * URI is already present on the element, its prefix is changed to be the prefix
1555 * part of the qualifiedName, and its value is changed to be the value parameter.
1556 * This value is a simple string; it is not parsed as it is being set. So any
1557 * markup (such as syntax to be recognized as an entity reference) is treated as
1558 * literal text, and needs to be appropriately escaped by the implementation when
1559 * it is written out. In order to assign an attribute value that contains entity
1560 * references, the user must create an Attr node plus any Text and
1561 * EntityReference nodes, build the appropriate subtree, and use
1562 * setAttributeNodeNS or setAttributeNode to assign it as the value of an
1563 * attribute.
1564 */
1565 virtual void setAttributeNS(const DOMString& namespaceURI,
1566 const DOMString& qualifiedName,
1567 const DOMString& value)
1568 throw(DOMException) = 0;
1570 /**
1571 * Removes an attribute by local name and namespace URI.
1572 */
1573 virtual void removeAttributeNS(const DOMString& namespaceURI,
1574 const DOMString& localName)
1575 throw(DOMException) = 0;
1577 /**
1578 * Retrieves an Attr node by local name and namespace URI.
1579 */
1580 virtual AttrPtr getAttributeNodeNS(const DOMString& namespaceURI,
1581 const DOMString& localName) = 0;
1583 /**
1584 * Adds a new attribute. If an attribute with that local name and
1585 * that namespace URI is already present in the element, it is
1586 * replaced by the new one. Replacing an attribute node by itself has no effect.
1587 */
1588 virtual AttrPtr setAttributeNodeNS(AttrPtr newAttr)
1589 throw(DOMException) = 0;
1591 /**
1592 * Returns a NodeList of all the descendant Elements with a given
1593 * local name and namespace URI in document order.
1594 */
1595 virtual NodeList getElementsByTagNameNS(const DOMString& namespaceURI,
1596 const DOMString& localName) = 0;
1598 /**
1599 * Returns true when an attribute with a given name is specified on
1600 * this element or has a default value, false otherwise.
1601 */
1602 virtual bool hasAttribute(const DOMString& name) = 0;
1604 /**
1605 * Returns true when an attribute with a given local name and namespace
1606 * URI is specified on this element or has a default value, false otherwise.
1607 */
1608 virtual bool hasAttributeNS(const DOMString& namespaceURI,
1609 const DOMString& localName) = 0;
1611 /**
1612 * The type information associated with this element.
1613 */
1614 virtual TypeInfo &getSchemaTypeInfo() = 0;
1617 /**
1618 * If the parameter isId is true, this method declares the specified
1619 * attribute to be a user-determined ID attribute.
1620 */
1621 virtual void setIdAttribute(const DOMString &name,
1622 bool isId) throw (DOMException) = 0;
1624 /**
1625 * If the parameter isId is true, this method declares the specified
1626 * attribute to be a user-determined ID attribute.
1627 */
1628 virtual void setIdAttributeNS(const DOMString &namespaceURI,
1629 const DOMString &localName,
1630 bool isId) throw (DOMException) = 0;
1632 /**
1633 * If the parameter isId is true, this method declares the specified
1634 * attribute to be a user-determined ID attribute.
1635 */
1636 virtual void setIdAttributeNode(const AttrPtr idAttr,
1637 bool isId) throw (DOMException) = 0;
1639 //##################
1640 //# Non-API methods
1641 //##################
1643 /**
1644 *
1645 */
1646 virtual ~Element() {}
1648 };
1654 /*#########################################################################
1655 ## Text
1656 #########################################################################*/
1658 /**
1659 * The Text interface inherits from CharacterData and represents the textual
1660 * content (termed character data in XML) of an Element or Attr. If there is no
1661 * markup inside an element's content, the text is contained in a single object
1662 * implementing the Text interface that is the only child of the element. If
1663 * there is markup, it is parsed into the information items (elements, comments,
1664 * etc.) and Text nodes that form the list of children of the element.
1665 */
1666 class Text : virtual public CharacterData
1667 {
1668 public:
1670 /**
1671 * Breaks this node into two nodes at the specified offset, keeping both in the
1672 * tree as siblings. After being split, this node will contain all the content up
1673 * to the offset point. A new node of the same type, which contains all the
1674 * content at and after the offset point, is returned. If the original node had a
1675 * parent node, the new node is inserted as the next sibling of the original
1676 * node. When the offset is equal to the length of this node, the new node has no
1677 * data.
1678 */
1679 virtual TextPtr splitText(unsigned long offset)
1680 throw(DOMException) = 0;
1682 /**
1683 * Returns whether this text node contains element content whitespace, often
1684 * abusively called "ignorable whitespace". The text node is determined to
1685 * contain whitespace in element content during the load of the document or if
1686 * validation occurs while using Document.normalizeDocument().
1687 */
1688 virtual bool getIsElementContentWhitespace()= 0;
1690 /**
1691 * Returns all text of Text nodes logically-adjacent text nodes
1692 * to this node, concatenated in document order.
1693 */
1694 virtual DOMString getWholeText() = 0;
1697 /**
1698 * Replaces the text of the current node and all logically-adjacent text nodes
1699 * with the specified text. All logically-adjacent text nodes are removed
1700 * including the current node unless it was the recipient of the replacement text.
1701 *
1702 * This method returns the node which received the replacement text. The returned
1703 * node is:
1704 * o null, when the replacement text is the empty string;
1705 * o the current node, except when the current node is read-only;
1706 * o a new Text node of the same type (Text or CDATASection) as
1707 * the current node inserted at the location of the replacement.
1708 */
1709 virtual TextPtr replaceWholeText(const DOMString &content)
1710 throw(DOMException) = 0;
1712 //##################
1713 //# Non-API methods
1714 //##################
1717 /**
1718 *
1719 */
1720 virtual ~Text() {}
1722 };
1726 /*#########################################################################
1727 ## Comment
1728 #########################################################################*/
1730 /**
1731 * This interface inherits from CharacterData and represents the content of a
1732 * comment, i.e., all the characters between the starting '<!--' and ending '-->'.
1733 * Note that this is the definition of a comment in XML, and, in practice,
1734 * HTML, although some HTML tools may implement the full SGML comment structure.
1735 */
1736 class Comment : virtual public CharacterData
1737 {
1738 public:
1740 //##################
1741 //# Non-API methods
1742 //##################
1745 /**
1746 *
1747 */
1748 virtual ~Comment() {}
1751 };
1755 /*#########################################################################
1756 ## TypeInfo
1757 #########################################################################*/
1759 /**
1760 * The TypeInfo interface represents a type referenced from Element or Attr nodes,
1761 * specified in the schemas associated with the document. The type is a pair of
1762 * a namespace URI and name properties, and depends on the document's schema.
1763 */
1764 class TypeInfo
1765 {
1766 public:
1768 /**
1769 * The name of a type declared for the associated element or attribute,
1770 * or null if unknown.
1771 */
1772 virtual DOMString getTypeName()
1773 { return typeName; }
1775 /**
1776 * The namespace of the type declared for the associated element
1777 * or attribute or null if the element does not have declaration or
1778 * if no namespace information is available.
1779 */
1780 virtual DOMString getTypeNamespace()
1781 { return typeNameSpace; }
1783 /**
1784 * These are the available values for the derivationMethod parameter used by the
1785 * method TypeInfo.isDerivedFrom(). It is a set of possible types of derivation,
1786 * and the values represent bit positions. If a bit in the derivationMethod
1787 * parameter is set to 1, the corresponding type of derivation will be taken into
1788 * account when evaluating the derivation between the reference type definition
1789 * and the other type definition. When using the isDerivedFrom method, combining
1790 * all of them in the derivationMethod parameter is equivalent to invoking the
1791 * method for each of them separately and combining the results with the OR
1792 * boolean function. This specification only defines the type of derivation for
1793 * XML Schema.
1794 */
1795 typedef enum
1796 {
1797 DERIVATION_RESTRICTION = 0x00000001,
1798 DERIVATION_EXTENSION = 0x00000002,
1799 DERIVATION_UNION = 0x00000004,
1800 DERIVATION_LIST = 0x00000008
1801 } DerivationMethod;
1804 /**
1805 * This method returns if there is a derivation between the reference
1806 * type definition, i.e. the TypeInfo on which the method is being called,
1807 * and the other type definition, i.e. the one passed as parameters.
1808 */
1809 virtual bool isDerivedFrom(const DOMString &/*typeNamespaceArg*/,
1810 const DOMString &/*typeNameArg*/,
1811 DerivationMethod /*derivationMethod*/)
1812 { return false; }
1814 //##################
1815 //# Non-API methods
1816 //##################
1819 /**
1820 *
1821 */
1822 TypeInfo()
1823 {}
1825 /**
1826 *
1827 */
1828 TypeInfo(const TypeInfo &other)
1829 { assign(other); }
1831 /**
1832 *
1833 */
1834 TypeInfo &operator=(const TypeInfo &other)
1835 { assign(other); return *this; }
1837 /**
1838 *
1839 */
1840 virtual ~TypeInfo() {}
1842 private:
1844 void assign(const TypeInfo &other)
1845 {
1846 typeName = other.typeName;
1847 typeNameSpace = other.typeNameSpace;
1848 }
1850 DOMString typeName;
1851 DOMString typeNameSpace;
1852 };
1857 /*#########################################################################
1858 ## UserDataHandler
1859 #########################################################################*/
1861 /**
1862 * When associating an object to a key on a node using Node.setUserData() the
1863 * application can provide a handler that gets called when the node the object is
1864 * associated to is being cloned, imported, or renamed. This can be used by the
1865 * application to implement various behaviors regarding the data it associates to
1866 * the DOM nodes. This interface defines that handler.
1867 */
1868 class UserDataHandler
1869 {
1870 public:
1872 /**
1873 * An integer indicating the type of operation being performed on a node.
1874 */
1875 typedef enum
1876 {
1877 NODE_CLONED = 1,
1878 NODE_IMPORTED = 2,
1879 NODE_DELETED = 3,
1880 NODE_RENAMED = 4,
1881 NODE_ADOPTED = 5
1882 } OperationType;
1885 /**
1886 * This method is called whenever the node for which this handler
1887 * is registered is imported or cloned.
1888 */
1889 virtual void handle(unsigned short operation,
1890 const DOMString &key,
1891 const DOMUserData *data,
1892 const NodePtr src,
1893 const NodePtr dst) =0;
1895 //##################
1896 //# Non-API methods
1897 //##################
1900 /**
1901 *
1902 */
1903 virtual ~UserDataHandler() {}
1905 };
1908 /*#########################################################################
1909 ## DOMError
1910 #########################################################################*/
1912 /**
1913 * DOMError is an interface that describes an error.
1914 */
1915 class DOMError
1916 {
1917 public:
1919 /**
1920 * An integer indicating the severity of the error.
1921 */
1922 typedef enum
1923 {
1924 SEVERITY_WARNING = 1,
1925 SEVERITY_ERROR = 2,
1926 SEVERITY_FATAL_ERROR = 3
1927 } ErrorSeverity;
1930 /**
1931 * The severity of the error, either SEVERITY_WARNING, SEVERITY_ERROR,
1932 * or SEVERITY_FATAL_ERROR.
1933 */
1934 virtual unsigned short getSeverity() =0;
1936 /**
1937 * An implementation specific string describing the error that occurred.
1938 */
1939 virtual DOMString getMessage() =0;
1941 /**
1942 * A DOMString indicating which related data is expected in relatedData.
1943 * Users should refer to the specification of the error in order to find
1944 * its DOMString type and relatedData definitions if any.
1945 */
1946 virtual DOMString getType() =0;
1948 /**
1949 * The related platform dependent exception if any.
1950 */
1951 virtual DOMObject *getRelatedException() =0;
1953 /**
1954 * The related DOMError.type dependent data if any.
1955 */
1956 virtual DOMObject *getRelatedData() =0;
1958 /**
1959 * The location of the error.
1960 */
1961 virtual DOMLocator *getLocation() =0;
1964 //##################
1965 //# Non-API methods
1966 //##################
1969 /**
1970 *
1971 */
1972 virtual ~DOMError() {}
1974 };
1977 /*#########################################################################
1978 ## DOMErrorHandler
1979 #########################################################################*/
1981 /**
1982 * DOMErrorHandler is a callback interface that the DOM implementation can call
1983 * when reporting errors that happens while processing XML data, or when doing
1984 * some other processing (e.g. validating a document). A DOMErrorHandler object
1985 * can be attached to a Document using the "error-handler" on the
1986 * DOMConfiguration interface. If more than one error needs to be reported during
1987 * an operation, the sequence and numbers of the errors passed to the error
1988 * handler are implementation dependent.
1989 */
1990 class DOMErrorHandler
1991 {
1992 public:
1994 /**
1995 * This method is called on the error handler when an error occurs.
1996 * If an exception is thrown from this method, it is considered to be
1997 * equivalent of returning true.
1998 */
1999 virtual bool handleError(const DOMError *error) =0;
2002 //##################
2003 //# Non-API methods
2004 //##################
2006 /**
2007 *
2008 */
2009 virtual ~DOMErrorHandler() {}
2011 };
2015 /*#########################################################################
2016 ## DOMLocator
2017 #########################################################################*/
2019 /**
2020 * DOMLocator is an interface that describes a location (e.g. where an error occurred).
2021 */
2022 class DOMLocator
2023 {
2024 public:
2026 /**
2027 * The line number this locator is pointing to, or -1 if there is
2028 * no column number available.
2029 */
2030 virtual long getLineNumber() =0;
2032 /**
2033 * The column number this locator is pointing to, or -1 if there is
2034 * no column number available.
2035 */
2036 virtual long getColumnNumber() =0;
2038 /**
2039 * The byte offset into the input source this locator is pointing to
2040 * or -1 if there is no byte offset available.
2041 */
2042 virtual long getByteOffset() =0;
2044 /**
2045 * The UTF-16, as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646],
2046 * offset into the input source this locator is pointing to or -1
2047 * if there is no UTF-16 offset available.
2048 */
2049 virtual long getUtf16Offset() =0;
2052 /**
2053 * The node this locator is pointing to, or null if no node is available.
2054 */
2055 virtual NodePtr getRelatedNode() =0;
2058 /**
2059 * The URI this locator is pointing to, or null if no URI is available.
2060 */
2061 virtual DOMString getUri() =0;
2063 //##################
2064 //# Non-API methods
2065 //##################
2067 /**
2068 *
2069 */
2070 virtual ~DOMLocator() {}
2071 };
2074 /*#########################################################################
2075 ## DOMConfiguration
2076 #########################################################################*/
2078 /**
2079 * The DOMConfiguration interface represents the configuration of a document and
2080 * maintains a table of recognized parameters. Using the configuration, it is
2081 * possible to change Document.normalizeDocument() behavior, such as replacing
2082 * the CDATASection nodes with Text nodes or specifying the type of the schema
2083 * that must be used when the validation of the Document is requested.
2084 * DOMConfiguration objects are also used in [DOM Level 3 Load and Save] in the
2085 * DOMParser and DOMSerializer interfaces.
2086 *
2087 * Look here for a list of valid parameters:
2088 * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration
2089 */
2090 class DOMConfiguration
2091 {
2092 public:
2094 /**
2095 * Set the value of a parameter.
2096 */
2097 virtual void setParameter(const DOMString &name,
2098 const DOMUserData *value)
2099 throw (DOMException) =0;
2101 /**
2102 * Return the value of a parameter if known.
2103 */
2104 virtual DOMUserData *getParameter(const DOMString &name)
2105 throw (DOMException) =0;
2107 /**
2108 * Check if setting a parameter to a specific value is supported.
2109 */
2110 virtual bool canSetParameter(const DOMString &name,
2111 const DOMUserData *data) =0;
2113 /**
2114 * The list of the parameters supported by this DOMConfiguration
2115 * object and for which at least one value can be set by the application.
2116 * Note that this list can also contain parameter names defined outside
2117 * this specification.
2118 */
2119 virtual DOMStringList *getParameterNames() =0;
2121 //##################
2122 //# Non-API methods
2123 //##################
2126 /**
2127 *
2128 */
2129 virtual ~DOMConfiguration() {}
2131 };
2138 /*#########################################################################
2139 ## CDATASection
2140 #########################################################################*/
2142 /**
2143 * CDATA sections are used to escape blocks of text containing characters that
2144 * would otherwise be regarded as markup. The only delimiter that is recognized
2145 * in a CDATA section is the "]]>" string that ends the CDATA section. CDATA
2146 * sections cannot be nested. Their primary purpose is for including material
2147 * such as XML fragments, without needing to escape all the delimiters.
2148 */
2149 class CDATASection : virtual public Text
2150 {
2151 public:
2153 //##################
2154 //# Non-API methods
2155 //##################
2158 /**
2159 *
2160 */
2161 virtual ~CDATASection() {}
2163 };
2168 /*#########################################################################
2169 ## DocumentType
2170 #########################################################################*/
2172 /**
2173 * Each Document has a doctype attribute whose value is either null or a
2174 * DocumentType object. The DocumentType interface in the DOM Core provides an
2175 * interface to the list of entities that are defined for the document, and
2176 * little else because the effect of namespaces and the various XML schema
2177 * efforts on DTD representation are not clearly understood as of this writing.
2178 */
2179 class DocumentType : virtual public Node
2180 {
2181 public:
2183 /**
2184 * The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
2185 */
2186 virtual DOMString getName() = 0;
2188 /**
2189 * A NamedNodeMap containing the general entities, both external and
2190 * internal, declared in the DTD. Parameter entities are not contained.
2191 * Duplicates are discarded.
2192 */
2193 virtual NamedNodeMap getEntities() = 0;
2195 /**
2196 * A NamedNodeMap containing the notations declared in the DTD. Duplicates
2197 * are discarded. Every node in this map also implements the
2198 * Notation interface.
2199 */
2200 virtual NamedNodeMap getNotations() = 0;
2202 /**
2203 * The public identifier of the external subset.
2204 */
2205 virtual DOMString getPublicId() = 0;
2207 /**
2208 * The system identifier of the external subset. This may be an
2209 * absolute URI or not.
2210 */
2211 virtual DOMString getSystemId() = 0;
2213 /**
2214 * The internal subset as a string, or null if there is none. This
2215 * does not contain the delimiting square brackets.
2216 */
2217 virtual DOMString getInternalSubset() = 0;
2219 //##################
2220 //# Non-API methods
2221 //##################
2223 /**
2224 *
2225 */
2226 virtual ~DocumentType() {}
2228 };
2234 /*#########################################################################
2235 ## Notation
2236 #########################################################################*/
2238 /**
2239 * This interface represents a notation declared in the DTD. A notation either
2240 * declares, by name, the format of an unparsed entity (see section 4.7 of the
2241 * XML 1.0 specification [XML 1.0]), or is used for formal declaration of
2242 * processing instruction targets (see section 2.6 of the XML 1.0 specification
2243 * [XML 1.0]). The nodeName attribute inherited from Node is set to the declared
2244 * name of the notation.
2245 */
2246 class Notation : virtual public Node
2247 {
2248 public:
2250 /**
2251 * The public identifier of this notation. If the public identifier was
2252 * not specified, this is null.
2253 */
2254 virtual DOMString getPublicId() = 0;
2256 /**
2257 * The system identifier of this notation. If the system identifier was
2258 * not specified, this is null. This may be an absolute URI or not.
2259 */
2260 virtual DOMString getSystemId() = 0;
2262 //##################
2263 //# Non-API methods
2264 //##################
2267 /**
2268 *
2269 */
2270 virtual ~Notation() {}
2271 };
2278 /*#########################################################################
2279 ## Entity
2280 #########################################################################*/
2282 /**
2283 * This interface represents a known entity, either parsed or unparsed, in an XML
2284 * document. Note that this models the entity itself not the entity declaration.
2285 */
2286 class Entity : virtual public Node
2287 {
2288 public:
2290 /**
2291 * The public identifier associated with the entity if specified,
2292 * and null otherwise.
2293 */
2294 virtual DOMString getPublicId() = 0;
2296 /**
2297 * The system identifier associated with the entity if specified,
2298 * and null otherwise. This may be an absolute URI or not.
2299 */
2300 virtual DOMString getSystemId() = 0;
2302 /**
2303 * For unparsed entities, the name of the notation for the entity.
2304 * For parsed entities, this is null.
2305 */
2306 virtual DOMString getNotationName() = 0;
2308 /**
2309 * An attribute specifying the encoding used for this entity at the
2310 * time of parsing, when it is an external parsed entity. This is null
2311 * if it an entity from the internal subset or if it is not known.
2312 */
2313 virtual DOMString getInputEncoding() = 0;
2315 /**
2316 * An attribute specifying, as part of the text declaration, the encoding
2317 * of this entity, when it is an external parsed entity. This is null otherwise.
2318 */
2319 virtual DOMString getXmlEncoding() = 0;
2321 /**
2322 * An attribute specifying, as part of the text declaration, the version
2323 * number of this entity, when it is an external parsed entity.
2324 * This is null otherwise.
2325 */
2326 virtual DOMString getXmlVersion() = 0;
2328 //##################
2329 //# Non-API methods
2330 //##################
2333 /**
2334 *
2335 */
2336 virtual ~Entity() {}
2337 };
2343 /*#########################################################################
2344 ## EntityReference
2345 #########################################################################*/
2347 /**
2348 * EntityReference nodes may be used to represent an entity reference in the tree.
2349 */
2350 class EntityReference : virtual public Node
2351 {
2352 public:
2355 //##################
2356 //# Non-API methods
2357 //##################
2359 /**
2360 *
2361 */
2362 virtual ~EntityReference() {}
2363 };
2369 /*#########################################################################
2370 ## ProcessingInstruction
2371 #########################################################################*/
2373 /**
2374 * The ProcessingInstruction interface represents a "processing instruction",
2375 * used in XML as a way to keep processor-specific information in the text of the
2376 * document.
2377 */
2378 class ProcessingInstruction : virtual public Node
2379 {
2380 public:
2382 /**
2383 * The target of this processing instruction. XML defines this as being
2384 * the first token following the markup that begins the processing instruction.
2385 */
2386 virtual DOMString getTarget() = 0;
2388 /**
2389 * The content of this processing instruction. This is from the first non
2390 * white space character after the target to the character immediately
2391 * preceding the ?>.
2392 */
2393 virtual DOMString getData() = 0;
2395 /**
2396 * Sets the content above.
2397 */
2398 virtual void setData(const DOMString& val) throw(DOMException) = 0;
2400 //##################
2401 //# Non-API methods
2402 //##################
2405 /**
2406 *
2407 */
2408 virtual ~ProcessingInstruction() {}
2410 };
2416 /*#########################################################################
2417 ## DocumentFragment
2418 #########################################################################*/
2420 /**
2421 * DocumentFragment is a "lightweight" or "minimal" Document object. It is very
2422 * common to want to be able to extract a portion of a document's tree or to
2423 * create a new fragment of a document. Imagine implementing a user command like
2424 * cut or rearranging a document by moving fragments around. It is desirable to
2425 * have an object which can hold such fragments and it is quite natural to use a
2426 * Node for this purpose. While it is true that a Document object could fulfill
2427 * this role, a Document object can potentially be a heavyweight object,
2428 * depending on the underlying implementation. What is really needed for this is
2429 * a very lightweight object. DocumentFragment is such an object.
2430 */
2431 class DocumentFragment : virtual public Node
2432 {
2433 public:
2435 //##################
2436 //# Non-API methods
2437 //##################
2440 /**
2441 *
2442 */
2443 virtual ~DocumentFragment() {}
2444 };
2451 /*#########################################################################
2452 ## Document
2453 #########################################################################*/
2455 /**
2456 * From the spec:
2457 *
2458 * The Document interface represents the entire HTML or XML document.
2459 * Conceptually, it is the root of the document tree, and provides the primary
2460 * access to the document's data.
2461 *
2462 * Since elements, text nodes, comments, processing instructions, etc. cannot
2463 * exist outside the context of a Document, the Document interface also contains
2464 * the factory methods needed to create these objects. The Node objects created
2465 * have a ownerDocument attribute which associates them with the Document within
2466 * whose context they were created.
2467 *
2468 */
2469 class Document : virtual public Node
2470 {
2471 public:
2473 /**
2474 * The Document Type Declaration (see DocumentType) associated with this document.
2475 */
2476 virtual DocumentTypePtr getDoctype() = 0;
2478 /**
2479 * The DOMImplementation object that handles this document. A DOM application
2480 * may use objects from multiple implementations.
2481 */
2482 virtual DOMImplementation *getImplementation() = 0;
2484 /**
2485 * This is a convenience attribute that allows direct access to the child
2486 * node that is the document element of the document.
2487 */
2488 virtual ElementPtr getDocumentElement() = 0;
2490 /**
2491 * Creates an element of the type specified.
2492 */
2493 virtual ElementPtr createElement(const DOMString& tagName)
2494 throw(DOMException) = 0;
2496 /**
2497 * Creates a new, empty DocumentFragment
2498 */
2499 virtual DocumentFragmentPtr createDocumentFragment() = 0;
2501 /**
2502 * Creates an Text node with the text data specified.
2503 */
2504 virtual TextPtr createTextNode(const DOMString& text) = 0;
2506 /**
2507 * Creates a new Comment node with the argument text
2508 */
2509 virtual CommentPtr createComment(const DOMString& text) = 0;
2511 /**
2512 * Creates a new CDATASection node with the argument text
2513 */
2514 virtual CDATASectionPtr createCDATASection(const DOMString& text)
2515 throw(DOMException) = 0;
2517 /**
2518 * Creates a new ProcessingInstruction
2519 */
2520 virtual ProcessingInstructionPtr
2521 createProcessingInstruction(const DOMString& target,
2522 const DOMString& data)
2523 throw(DOMException) = 0;
2525 /**
2526 * Creates a new Attr with the given name, but no value.
2527 */
2528 virtual AttrPtr createAttribute(const DOMString& name)
2529 throw(DOMException) = 0;
2531 /**
2532 * Creates a new EntityReference
2533 */
2534 virtual EntityReferencePtr createEntityReference(const DOMString& name)
2535 throw(DOMException) = 0;
2537 /**
2538 * Searches the Document in document order for all elements with the given
2539 * tag name
2540 */
2541 virtual NodeList getElementsByTagName(const DOMString& tagname) = 0;
2544 /**
2545 * Imports a node from another document to this document, without altering or
2546 * removing the source node from the original document; this method creates a new
2547 * copy of the source node. The returned node has no parent; (parentNode is
2548 * null). For all nodes, importing a node creates a node object owned by the
2549 * importing document, with attribute values identical to the source node's
2550 * nodeName and nodeType, plus the attributes related to namespaces (prefix,
2551 * localName, and namespaceURI). As in the cloneNode operation, the source node
2552 * is not altered. User data associated to the imported node is not carried over.
2553 * However, if any UserDataHandlers has been specified along with the associated
2554 * data these handlers will be called with the appropriate parameters before this
2555 * method returns. Additional information is copied as appropriate to the
2556 * nodeType, attempting to mirror the behavior expected if a fragment of XML or
2557 * HTML source was copied from one document to another, recognizing that the two
2558 * documents may have different DTDs in the XML case. The following list
2559 * describes the specifics for each type of node.
2560 */
2561 virtual NodePtr importNode(const NodePtr importedNode,
2562 bool deep)
2563 throw(DOMException) = 0;
2565 /**
2566 * Creates a new Element with the given namespace and qualifiedName.
2567 * Use "" for no namespace
2568 */
2569 virtual ElementPtr createElementNS(const DOMString& namespaceURI,
2570 const DOMString& qualifiedName)
2571 throw(DOMException) = 0;
2573 /**
2574 * Creates a new Attr with the given namespace and qualifiedName.
2575 */
2576 virtual AttrPtr createAttributeNS(const DOMString& namespaceURI,
2577 const DOMString& qualifiedName)
2578 throw(DOMException) = 0;
2580 /**
2581 * Searches the Document in document order for all elements with the given
2582 * namespace and tag name
2583 */
2584 virtual NodeList getElementsByTagNameNS(const DOMString& namespaceURI,
2585 const DOMString& localName) = 0;
2587 /**
2588 * Gets the element with the given id if it exists, else null.
2589 */
2590 virtual ElementPtr getElementById(const DOMString& elementId) = 0;
2593 /**
2594 * Return the input encoding of this Document
2595 */
2596 virtual DOMString getInputEncoding() = 0;
2599 /**
2600 * Return the XML encoding of this Document
2601 */
2602 virtual DOMString getXmlEncoding() = 0;
2604 /**
2605 * An attribute specifying, as part of the XML declaration, whether
2606 * this document is standalone. This is false when unspecified.
2607 */
2608 virtual bool getXmlStandalone() = 0;
2610 /**
2611 * Sets whether this is a standalone XML document. No validation is
2612 * done here.
2613 */
2614 virtual void setXmlStandalone(bool val) throw (DOMException) = 0;
2616 /**
2617 * Gets the version (1.0, 1.1, etc) of this document.
2618 */
2619 virtual DOMString getXmlVersion() = 0;
2621 /**
2622 * Sets the XML version of this document.
2623 */
2624 virtual void setXmlVersion(const DOMString &version)
2625 throw (DOMException) = 0;
2627 /**
2628 * An attribute specifying whether error checking is enforced or not. When set to
2629 * false, the implementation is free to not test every possible error case
2630 * normally defined on DOM operations, and not raise any DOMException on DOM
2631 * operations or report errors while using Document.normalizeDocument(). In case
2632 * of error, the behavior is undefined. This attribute is true by default.
2633 */
2634 virtual bool getStrictErrorChecking() = 0;
2636 /**
2637 * Sets the value described above.
2638 */
2639 virtual void setStrictErrorChecking(bool val) = 0;
2642 /**
2643 * Gets the document URI (the base location) of this Document.
2644 */
2645 virtual DOMString getDocumentURI() = 0;
2647 /**
2648 * Sets the document URI (the base location) of this Document to the
2649 * argument uri.
2650 */
2651 virtual void setDocumentURI(const DOMString &uri) = 0;
2653 /**
2654 * Attempts to adopt a node from another document to this document. If supported,
2655 * it changes the ownerDocument of the source node, its children, as well as the
2656 * attached attribute nodes if there are any. If the source node has a parent it
2657 * is first removed from the child list of its parent. This effectively allows
2658 * moving a subtree from one document to another (unlike importNode() which
2659 * create a copy of the source node instead of moving it). When it fails,
2660 * applications should use Document.importNode() instead. Note that if the
2661 * adopted node is already part of this document (i.e. the source and target
2662 * document are the same), this method still has the effect of removing the
2663 * source node from the child list of its parent, if any.
2664 */
2665 virtual NodePtr adoptNode(const NodePtr source) throw (DOMException) = 0;
2667 /**
2668 * Get the configuration item associated with this Document
2669 */
2670 virtual DOMConfiguration *getDomConfig() = 0;
2672 /**
2673 * This method acts as if the document was going through a save and load cycle,
2674 * putting the document in a "normal" form. As a consequence, this method updates
2675 * the replacement tree of EntityReference nodes and normalizes Text nodes, as
2676 * defined in the method Node.normalize(). Otherwise, the actual result depends
2677 * on the features being set on the Document.domConfig object and governing what
2678 * operations actually take place. Noticeably this method could also make the
2679 * document namespace well-formed according to the algorithm described in
2680 * Namespace Normalization, check the character normalization, remove the
2681 * CDATASection nodes, etc. See DOMConfiguration for details.
2682 */
2683 virtual void normalizeDocument() = 0;
2685 /**
2686 *
2687 * Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE. When possible
2688 * this simply changes the name of the given node, otherwise this creates a new
2689 * node with the specified name and replaces the existing node with the new node
2690 * as described below. If simply changing the name of the given node is not
2691 * possible, the following operations are performed: a new node is created, any
2692 * registered event listener is registered on the new node, any user data
2693 * attached to the old node is removed from that node, the old node is removed
2694 * from its parent if it has one, the children are moved to the new node, if the
2695 * renamed node is an Element its attributes are moved to the new node, the new
2696 * node is inserted at the position the old node used to have in its parent's
2697 * child nodes list if it has one, the user data that was attached to the old
2698 * node is attached to the new node. When the node being renamed is an Element
2699 * only the specified attributes are moved, default attributes originated from
2700 * the DTD are updated according to the new element name. In addition, the
2701 * implementation may update default attributes from other schemas. Applications
2702 * should use Document.normalizeDocument() to guarantee these attributes are
2703 * up-to-date. When the node being renamed is an Attr that is attached to an
2704 * Element, the node is first removed from the Element attributes map. Then, once
2705 * renamed, either by modifying the existing node or creating a new one as
2706 * described above, it is put back.
2707 *
2708 * In addition,
2709 * a user data event NODE_RENAMED is fired,
2710 * when the implementation supports the feature "MutationNameEvents",
2711 * each mutation operation involved in this method fires the appropriate
2712 * event, and in the end the event {http://www.w3.org/2001/xml-events,
2713 * DOMElementNameChanged} or {http://www.w3.org/2001/xml-events,
2714 * DOMAttributeNameChanged} is fired.
2715 *
2716 */
2717 virtual NodePtr renameNode(const NodePtr n,
2718 const DOMString &namespaceURI,
2719 const DOMString &qualifiedName)
2720 throw (DOMException) = 0;
2723 //##################
2724 //# Non-API methods
2725 //##################
2727 /**
2728 *
2729 */
2730 virtual ~Document() {}
2732 };
2741 } //namespace dom
2742 } //namespace w3c
2743 } //namespace org
2746 #endif // __DOM_H__
2749 /*#########################################################################
2750 ## E N D O F F I L E
2751 #########################################################################*/