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 #include <glibmm.h>
61 //#include <string>
63 //# Unfortunate hack for a name collision
64 #ifdef SEVERITY_ERROR
65 #undef SEVERITY_ERROR
66 #endif
68 #define XMLNSNAME "http://www.w3.org/2000/xmlns/"
70 namespace org
71 {
72 namespace w3c
73 {
74 namespace dom
75 {
78 /**
79 * This is the org::w3c::dom::DOMString definition.
80 * Which type do we want?
81 */
82 typedef Glib::ustring DOMString;
83 typedef gunichar XMLCh;
85 //typedef std::string DOMString;
86 //typedef unsigned short XMLCh;
89 /**
90 * At least 64 bit time stamp value.
91 */
92 typedef unsigned long long DOMTimeStamp;
94 /**
95 * This is used for storing refs to user-supplied data.
96 */
97 typedef void DOMUserData;
101 /**
102 * This is used for opaque references to arbitrary objects from
103 * the DOM tree.
104 */
105 typedef void DOMObject;
108 /**
109 * Forward references. These are needed because of extensive
110 * inter-referencing within the DOM tree.
111 */
112 class NodeList;
113 class NamedNodeMap;
114 class DOMException;
115 class DOMStringList;
116 class NameList;
117 class DOMImplementationList;
118 class DOMImplementationSource;
119 class DOMImplementation;
120 class TypeInfo;
121 class UserDataHandler;
122 class DOMError;
123 class DOMErrorHandler;
124 class DOMLocator;
125 class DOMConfiguration;
127 /**
128 * Smart pointer definitions. Most methods that return references to
129 * Nodes of various types, will return one of these smart pointers instead,
130 * to allow refcounting and GC.
131 */
132 class Node;
133 typedef Ptr<Node> NodePtr;
134 class CharacterData;
135 typedef Ptr<CharacterData> CharacterDataPtr;
136 class Attr;
137 typedef Ptr<Attr> AttrPtr;
138 class Element;
139 typedef Ptr<Element> ElementPtr;
140 class Text;
141 typedef Ptr<Text> TextPtr;
142 class Comment;
143 typedef Ptr<Comment> CommentPtr;
144 class DocumentType;
145 typedef Ptr<DocumentType> DocumentTypePtr;
146 class CDATASection;
147 typedef Ptr<CDATASection> CDATASectionPtr;
148 class Notation;
149 typedef Ptr<Notation> NotationPtr;
150 class Entity;
151 typedef Ptr<Entity> EntityPtr;
152 class EntityReference;
153 typedef Ptr<EntityReference> EntityReferencePtr;
154 class ProcessingInstruction;
155 typedef Ptr<ProcessingInstruction> ProcessingInstructionPtr;
156 class DocumentFragment;
157 typedef Ptr<DocumentFragment> DocumentFragmentPtr;
158 class Document;
159 typedef Ptr<Document> DocumentPtr;
164 /**
165 * NOTE: We were originally intending to split ALL specifications into
166 * interface and implementation. After consideration, though, it behooves
167 * us to simplify things by implementing the base exception and
168 * container classes directly:
169 *
170 * DOMException
171 * DOMStringList
172 * NameList
173 * DOMImplementationList
174 * DOMImplementationSource
175 * DOMImplementation
176 * NodeList
177 * NamedNodeMap
178 */
181 /*#########################################################################
182 ## DOMException
183 #########################################################################*/
185 /**
186 * An Exception class. Not an interface, since this is something that
187 * all implementations must support.
188 */
189 class DOMException
190 {
192 public:
194 /**
195 * ExceptionCode
196 */
197 typedef enum
198 {
199 INDEX_SIZE_ERR = 1,
200 DOMSTRING_SIZE_ERR = 2,
201 HIERARCHY_REQUEST_ERR = 3,
202 WRONG_DOCUMENT_ERR = 4,
203 INVALID_CHARACTER_ERR = 5,
204 NO_DATA_ALLOWED_ERR = 6,
205 NO_MODIFICATION_ALLOWED_ERR = 7,
206 NOT_FOUND_ERR = 8,
207 NOT_SUPPORTED_ERR = 9,
208 INUSE_ATTRIBUTE_ERR = 10,
209 INVALID_STATE_ERR = 11,
210 SYNTAX_ERR = 12,
211 INVALID_MODIFICATION_ERR = 13,
212 NAMESPACE_ERR = 14,
213 INVALID_ACCESS_ERR = 15,
214 VALIDATION_ERR = 16,
215 TYPE_MISMATCH_ERR = 17
216 } ExceptionCode;
220 DOMException(const DOMString &reasonMsg)
221 { msg = reasonMsg; }
223 DOMException(short theCode)
224 {
225 code = theCode;
226 }
228 virtual ~DOMException() throw()
229 {}
231 /**
232 * What type of exception? One of the ExceptionCodes above.
233 */
234 unsigned short code;
236 /**
237 * Some text describing the context that generated this exception.
238 */
239 DOMString msg;
241 /**
242 * Get a string, translated from the code.
243 * Like std::exception. Not in spec.
244 */
245 const char *what()
246 { return (const char *)msg.c_str(); }
250 };
257 /*#########################################################################
258 ## DOMStringList
259 #########################################################################*/
261 /**
262 * This holds a list of DOMStrings. This is likely the response to a query,
263 * or the value of an attribute.
264 */
265 class DOMStringList
266 {
267 public:
269 /**
270 * Get the nth string of the list
271 */
272 virtual DOMString item(unsigned long index)
273 {
274 if (index>=strings.size())
275 return "";
276 return strings[index];
277 }
279 /**
280 * How many strings in this list?
281 */
282 virtual unsigned long getLength()
283 {
284 return (unsigned long) strings.size();
285 }
287 /**
288 * Is the argument string present in this list? Lexically, not identically.
289 */
290 virtual bool contains(const DOMString &str)
291 {
292 for (unsigned int i=0; i<strings.size() ; i++)
293 {
294 if (strings[i] == str)
295 return true;
296 }
297 return false;
298 }
301 //##################
302 //# Non-API methods
303 //##################
305 /**
306 *
307 */
308 DOMStringList() {}
311 /**
312 *
313 */
314 DOMStringList(const DOMStringList &other)
315 {
316 strings = other.strings;
317 }
319 /**
320 *
321 */
322 DOMStringList &operator=(const DOMStringList &other)
323 {
324 strings = other.strings;
325 return *this;
326 }
328 /**
329 *
330 */
331 virtual ~DOMStringList() {}
334 protected:
336 /**
337 *
338 */
339 virtual void add(const DOMString &str)
340 {
341 strings.push_back(str);
342 }
344 std::vector<DOMString>strings;
346 };
350 /*#########################################################################
351 ## NameList
352 #########################################################################*/
355 /**
356 * Constains a list of namespaced names.
357 */
358 class NameList
359 {
360 private:
362 class NamePair
363 {
364 public:
365 NamePair(const DOMString &theNamespaceURI, const DOMString &theName)
366 {
367 namespaceURI = theNamespaceURI;
368 name = theName;
369 }
370 NamePair(const NamePair &other)
371 {
372 namespaceURI = other.namespaceURI;
373 name = other.name;
374 }
375 NamePair &operator=(const NamePair &other)
376 {
377 namespaceURI = other.namespaceURI;
378 name = other.name;
379 return *this;
380 }
381 virtual ~NamePair() {}
383 DOMString namespaceURI;
384 DOMString name;
385 };
387 public:
389 /**
390 * Returns a name at the given index. If out of range, return -1.
391 */
392 virtual DOMString getName(unsigned long index)
393 {
394 if (index>=namePairs.size())
395 return "";
396 return namePairs[index].name;
397 }
399 /**
400 * Returns a namespace at the given index. If out of range, return -1.
401 */
402 virtual DOMString getNamespaceURI(unsigned long index)
403 {
404 if (index>=namePairs.size())
405 return "";
406 return namePairs[index].namespaceURI;
407 }
409 /**
410 * Return the number of entries in this list.
411 */
412 virtual unsigned long getLength()
413 {
414 return (unsigned long)namePairs.size();
415 }
417 /**
418 * Return whether the name argument is present in the list.
419 * This is done lexically, not identically.
420 */
421 virtual bool contains(const DOMString &name)
422 {
423 for (unsigned int i=0; i<namePairs.size() ; i++)
424 {
425 if (namePairs[i].name == name )
426 return true;
427 }
428 return false;
429 }
431 /**
432 * Return whether the namespaced name argument is present in the list.
433 * This is done lexically, not identically.
434 */
435 virtual bool containsNS(const DOMString namespaceURI,const DOMString &name)
436 {
437 for (unsigned int i=0; i<namePairs.size() ; i++)
438 {
439 if (namePairs[i].namespaceURI == namespaceURI ||
440 namePairs[i].name == name )
441 return true;
442 }
443 return false;
444 }
447 //##################
448 //# Non-API methods
449 //##################
451 /**
452 *
453 */
454 NameList() {}
456 /**
457 *
458 */
459 NameList(const NameList &other)
460 {
461 namePairs = other.namePairs;
462 }
464 /**
465 *
466 */
467 NameList &operator=(const NameList &other)
468 {
469 namePairs = other.namePairs;
470 return *this;
471 }
473 /**
474 *
475 */
476 virtual ~NameList() {}
479 protected:
481 std::vector<NamePair> namePairs;
483 };
485 /*#########################################################################
486 ## DOMImplementationList
487 #########################################################################*/
489 /**
490 * Contains a list of DOMImplementations, with accessors.
491 */
492 class DOMImplementationList
493 {
494 public:
496 /**
497 * Return a DOMImplementation at the given index. If
498 * out of range, return NULL.
499 */
500 virtual DOMImplementation *item(unsigned long index)
501 {
502 if (index >implementations.size())
503 return NULL;
504 return implementations[index];
505 }
507 /**
508 * Return the number of DOMImplementations in this list.
509 */
510 virtual unsigned long getLength()
511 {
512 return (unsigned long) implementations.size();
513 }
516 //##################
517 //# Non-API methods
518 //##################
520 /**
521 *
522 */
523 DOMImplementationList() {}
526 /**
527 *
528 */
529 DOMImplementationList(const DOMImplementationList &other)
530 {
531 implementations = other.implementations;
532 }
534 /**
535 *
536 */
537 DOMImplementationList &operator=(const DOMImplementationList &other)
538 {
539 implementations = other.implementations;
540 return *this;
541 }
543 /**
544 *
545 */
546 virtual ~DOMImplementationList() {}
548 protected:
550 std::vector<DOMImplementation *>implementations;
552 };
555 /*#########################################################################
556 ## DOMImplementationSource
557 #########################################################################*/
559 /**
560 * This is usually the first item to be called when creating a Document.
561 * You will either find one DOMImplementation with a given set of features,
562 * or return a list that match. Using "" will get any implementation
563 * available.
564 */
565 class DOMImplementationSource
566 {
567 public:
569 /**
570 * Return the first DOMImplementation with the given set of features.
571 * Use "" to fetch any implementation.
572 */
573 virtual DOMImplementation *getDOMImplementation(const DOMString &features) = 0;
575 /**
576 * Return a list of DOMImplementations with the given set of features.
577 * Use "" to fetch any implementation.
578 */
579 virtual DOMImplementationList getDOMImplementationList(const DOMString &features) = 0;
581 //##################
582 //# Non-API methods
583 //##################
585 /**
586 *
587 */
588 virtual ~DOMImplementationSource() {}
590 };
596 /*#########################################################################
597 ## DOMImplementation
598 #########################################################################*/
600 /**
601 * This is the class that actually creates a Document.
602 */
603 class DOMImplementation
604 {
605 public:
607 /**
608 * Determine if this implementation has the given feature and version.
609 */
610 virtual bool hasFeature(const DOMString& feature, const DOMString& version) = 0;
613 /**
614 * Create a document type to be used in creating documents.
615 */
616 virtual DocumentTypePtr createDocumentType(
617 const DOMString& qualifiedName,
618 const DOMString& publicId,
619 const DOMString& systemId)
620 throw(DOMException) = 0;
622 /**
623 * Create a DOM document.
624 */
625 virtual DocumentPtr createDocument(const DOMString& namespaceURI,
626 const DOMString& qualifiedName,
627 DocumentTypePtr doctype)
628 throw(DOMException) = 0;
629 /**
630 * Return the thing which is the feature of this implementation. Since
631 * this is a "one size fits all" call, you will need to typecast the
632 * result to the expected type.
633 */
634 virtual DOMObject *getFeature(const DOMString& feature,
635 const DOMString& version) = 0;
638 //##################
639 //# Non-API methods
640 //##################
642 /**
643 *
644 */
645 virtual ~DOMImplementation() {}
647 };
653 /*#########################################################################
654 ## Node
655 #########################################################################*/
657 /**
658 * The basic Node class, which is the root of most other
659 * classes in DOM. Thus it is by far the most important, and the one
660 * whose implementation we must perform correctly.
661 */
662 class Node
663 {
664 public:
666 /**
667 * Which of the DOM Core node types is this node?
668 */
669 typedef enum
670 {
671 ELEMENT_NODE = 1,
672 ATTRIBUTE_NODE = 2,
673 TEXT_NODE = 3,
674 CDATA_SECTION_NODE = 4,
675 ENTITY_REFERENCE_NODE = 5,
676 ENTITY_NODE = 6,
677 PROCESSING_INSTRUCTION_NODE = 7,
678 COMMENT_NODE = 8,
679 DOCUMENT_NODE = 9,
680 DOCUMENT_TYPE_NODE = 10,
681 DOCUMENT_FRAGMENT_NODE = 11,
682 NOTATION_NODE = 12
683 } NodeType;
685 /**
686 * Return the name of this node.
687 */
688 virtual DOMString getNodeName() = 0;
690 /**
691 * Return the value of this node. The interpretation of the
692 * value is type-specific.
693 */
694 virtual DOMString getNodeValue() throw (DOMException) = 0;
696 /**
697 * Set the value of this node. The interpretation of the
698 * value is type-specific.
699 */
700 virtual void setNodeValue(const DOMString& val) throw (DOMException) = 0;
702 /**
703 * Return the type of this Node. One of the NodeType values above.
704 */
705 virtual unsigned short getNodeType() = 0;
707 /**
708 * Return the parent which references this node as a child in the DOM
709 * tree. Return NULL if there is none.
710 */
711 virtual NodePtr getParentNode() = 0;
713 /**
714 * Return a list of the children of this Node.
715 * NOTE: the spec expects this to be a "live" list that always
716 * reflects an accurate list of what the Node current possesses, not
717 * a snapshot. How do we do this?
718 */
719 virtual NodeList getChildNodes() = 0;
721 /**
722 * Return the first sibling of the chidren of this node. Return
723 * null if there is none.
724 */
725 virtual NodePtr getFirstChild() = 0;
727 /**
728 * Return the last sibling of the children of this node. Return
729 * null if there is none.
730 */
731 virtual NodePtr getLastChild() = 0;
733 /**
734 * Return the node that is previous to this one in the parent's
735 * list of children. Return null if there is none.
736 */
737 virtual NodePtr getPreviousSibling() = 0;
739 /**
740 * Return the node that is after this one in the parent's list
741 * of children. Return null if there is none.
742 */
743 virtual NodePtr getNextSibling() = 0;
745 /**
746 * Get the list of all attributes of this node.
747 */
748 virtual NamedNodeMap &getAttributes() = 0;
751 /**
752 * Return the document that created or inherited this node.
753 */
754 virtual DocumentPtr getOwnerDocument() = 0;
756 /**
757 * Insert a node as a new child. Place it before the referenced child.
758 * Place it at the end if the referenced child does not exist.
759 */
760 virtual NodePtr insertBefore(const NodePtr newChild,
761 const NodePtr refChild)
762 throw(DOMException) = 0;
764 /**
765 * Insert a node as a new child. Replace the referenced child with it.
766 * Place it at the end if the referenced child does not exist.
767 */
768 virtual NodePtr replaceChild(const NodePtr newChild,
769 const NodePtr oldChild)
770 throw(DOMException) = 0;
772 /**
773 * Remove a node from the list of children. Do nothing if the
774 * node is not a member of the child list.
775 */
776 virtual NodePtr removeChild(const NodePtr oldChild)
777 throw(DOMException) = 0;
779 /**
780 * Add the node to the end of this node's child list.
781 */
782 virtual NodePtr appendChild(const NodePtr newChild)
783 throw(DOMException) = 0;
785 /**
786 * Return true if this node has one or more children, else return false.
787 */
788 virtual bool hasChildNodes() = 0;
790 /**
791 * Return a new node which has the name, type, value, attributes, and
792 * child list as this one.
793 * If 'deep' is true, continue cloning recursively with this node's children,
794 * so that the child list also contains clones of their respective nodes.
795 */
796 virtual NodePtr cloneNode(bool deep) = 0;
798 /**
799 * Adjust this node and its children to have its namespaces and
800 * prefixes in "canonical" order.
801 */
802 virtual void normalize() = 0;
804 /**
805 * Return true if the named feature is supported by this node,
806 * else false.
807 */
808 virtual bool isSupported(const DOMString& feature,
809 const DOMString& version) = 0;
811 /**
812 * Return the namespace of this node. This would be whether the
813 * namespace were declared explicitly on this node, it has a namespace
814 * prefix, or it is inherits the namespace from an ancestor node.
815 */
816 virtual DOMString getNamespaceURI() = 0;
818 /**
819 * Return the namespace prefix of this node, if any. For example, if
820 * the tag were <svg:image> then the prefix would be "svg"
821 */
822 virtual DOMString getPrefix() = 0;
824 /**
825 * Sets the namespace prefix of this node to the given value. This
826 * does not change the namespaceURI value.
827 */
828 virtual void setPrefix(const DOMString& val) throw(DOMException) = 0;
830 /**
831 * Return the local name of this node. This is merely the name without
832 * any namespace or prefix.
833 */
834 virtual DOMString getLocalName() = 0;
836 /**
837 * Return true if this node has one or more attributes, else false.
838 */
839 virtual bool hasAttributes() = 0;
841 /**
842 * Return the base URI of this node. This is basically the "location" of this
843 * node, and is used in resolving the relative locations of other URIs.
844 */
845 virtual DOMString getBaseURI() = 0;
847 /**
848 * DocumentPosition.
849 * This is used to describe the position of one node relative
850 * to another in a document
851 */
852 typedef enum
853 {
854 DOCUMENT_POSITION_DISCONNECTED = 0x01,
855 DOCUMENT_POSITION_PRECEDING = 0x02,
856 DOCUMENT_POSITION_FOLLOWING = 0x04,
857 DOCUMENT_POSITION_CONTAINS = 0x08,
858 DOCUMENT_POSITION_CONTAINED_BY = 0x10,
859 DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20
860 } DocumentPosition;
863 /**
864 * Get the position of this node relative to the node argument.
865 */
866 virtual unsigned short compareDocumentPosition(
867 const NodePtr other) = 0;
869 /**
870 * This is a DOM L3 method. Return the text value of this node and its
871 * children. This is done by concatenating all of the TEXT_NODE and
872 * CDATA_SECTION nodes of this node and its children, in order, together.
873 * Very handy.
874 */
875 virtual DOMString getTextContent() throw(DOMException) = 0;
878 /**
879 * This is a DOM L3 method. Remember, this is a destructive call. This
880 * will replace all of the child nodes of this node with a single TEXT_NODE
881 * with the given text value.
882 */
883 virtual void setTextContent(const DOMString &val) throw(DOMException) = 0;
886 /**
887 * This will search the tree from this node up, for a prefix that
888 * has been assigned to the namespace argument. Return "" if not found.
889 */
890 virtual DOMString lookupPrefix(const DOMString &namespaceURI) =0;
893 /**
894 * Return true if this node is in the namespace of the argument, without
895 * requiring an explicit namespace declaration or a suffix.
896 */
897 virtual bool isDefaultNamespace(const DOMString &namespaceURI) =0;
900 /**
901 * This will search the tree from this node up, for a namespace that
902 * has been assigned the suffix in the argument. Return "" if not found.
903 */
904 virtual DOMString lookupNamespaceURI(const DOMString &prefix) =0;
907 /**
908 * Return true if the argument node is equal to this one. Use W3C rules
909 * for equality.
910 */
911 virtual bool isEqualNode(const NodePtr node) =0;
915 /**
916 * Return an opaque reference to the named feature. Return null if
917 * not supported. Using other than "" for the version will look for
918 * a feature with the given version.
919 */
920 virtual DOMObject *getFeature(const DOMString &feature,
921 const DOMString &version) =0;
923 /**
924 * Store a user data reference in this node, using the given key.
925 * A handler is an optional function object that will be called during
926 * future settings of this value. See UserDataHandler for more info.
927 */
928 virtual DOMUserData *setUserData(const DOMString &key,
929 const DOMUserData *data,
930 const UserDataHandler *handler) =0;
933 /**
934 * Return a reference to the named user data object. Return null
935 * if it does not exist.
936 */
937 virtual DOMUserData *getUserData(const DOMString &key) =0;
939 //##################
940 //# Non-API methods
941 //##################
943 /**
944 *
945 */
946 Node() : _refCnt(0)
947 {}
949 /**
950 *
951 */
952 virtual ~Node() {}
954 protected:
956 friend void incrementRefCount(Node *p);
957 friend void decrementRefCount(Node *p);
959 /**
960 * For the Ptr smart pointer
961 */
962 int _refCnt;
964 };
969 /*#########################################################################
970 ## NodeList
971 #########################################################################*/
973 /**
974 * Contains a list of Nodes. This is the standard API container for Nodes,
975 * and is used in lieu of other lists, arrays, etc, in order to provide
976 * a consistent API and algorithm.
977 */
978 class NodeList
979 {
980 public:
982 /**
983 * Retrieve the Node at the given index. Return NULL
984 * if out of range.
985 */
986 virtual NodePtr item(unsigned long index)
987 {
988 if (index>=nodes.size())
989 return NULL;
990 return nodes[index];
991 }
993 /**
994 * Get the number of nodes in this list
995 */
996 virtual unsigned long getLength()
997 {
998 return (unsigned long) nodes.size();
999 }
1002 //##################
1003 //# Non-API methods
1004 //##################
1006 /**
1007 *
1008 */
1009 NodeList() {}
1011 /**
1012 *
1013 */
1014 NodeList(const NodeList &other)
1015 {
1016 nodes = other.nodes;
1017 }
1019 /**
1020 *
1021 */
1022 NodeList &operator=(const NodeList &other)
1023 {
1024 nodes = other.nodes;
1025 return *this;
1026 }
1028 /**
1029 *
1030 */
1031 virtual ~NodeList() {}
1033 /**
1034 *
1035 */
1036 virtual void clear()
1037 {
1038 nodes.clear();
1039 }
1041 protected:
1043 friend class NodeImpl;
1044 friend class ElementImpl;
1046 /*
1047 *
1048 */
1049 virtual void add(const NodePtr node)
1050 {
1051 nodes.push_back(node);
1052 }
1054 protected:
1056 std::vector<NodePtr> nodes;
1058 };
1063 /*#########################################################################
1064 ## NamedNodeMap
1065 #########################################################################*/
1067 /**
1068 * Contains a mapping from name->NodePtr. Used for various purposes. For
1069 * example, a list of Attributes is a NamedNodeMap.
1070 */
1071 class NamedNodeMap
1072 {
1073 private:
1075 /**
1076 * table entry. Not an API item
1077 */
1078 class NamedNodeMapEntry
1079 {
1080 public:
1081 NamedNodeMapEntry(const DOMString &theNamespaceURI,
1082 const DOMString &theName,
1083 const NodePtr theNode)
1084 {
1085 namespaceURI = theNamespaceURI;
1086 name = theName;
1087 node = theNode;
1088 }
1089 NamedNodeMapEntry(const NamedNodeMapEntry &other)
1090 {
1091 assign(other);
1092 }
1093 NamedNodeMapEntry &operator=(const NamedNodeMapEntry &other)
1094 {
1095 assign(other);
1096 return *this;
1097 }
1098 virtual ~NamedNodeMapEntry()
1099 {
1100 }
1101 void assign(const NamedNodeMapEntry &other)
1102 {
1103 namespaceURI = other.namespaceURI;
1104 name = other.name;
1105 node = other.node;
1106 }
1107 DOMString namespaceURI;
1108 DOMString name;
1109 NodePtr node;
1110 };
1113 public:
1115 /**
1116 * Return the named node. Return nullptr if not found.
1117 */
1118 virtual NodePtr getNamedItem(const DOMString& name)
1119 {
1120 std::vector<NamedNodeMapEntry>::iterator iter;
1121 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1122 {
1123 if (iter->name == name)
1124 {
1125 NodePtr node = iter->node;
1126 return node;
1127 }
1128 }
1129 return NULL;
1130 }
1132 /**
1133 * Adds a node using its nodeName attribute. If a node with that name is already
1134 * present in this map, it is replaced by the new one. Replacing a node by itself
1135 * has no effect.
1136 */
1137 virtual NodePtr setNamedItem(NodePtr arg) throw(DOMException)
1138 {
1139 if (!arg)
1140 return NULL;
1141 DOMString namespaceURI = arg->getNamespaceURI();
1142 DOMString name = arg->getNodeName();
1143 std::vector<NamedNodeMapEntry>::iterator iter;
1144 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1145 {
1146 if (iter->name == name)
1147 {
1148 NodePtr node = iter->node;
1149 iter->node = arg;
1150 return node;
1151 }
1152 }
1153 NamedNodeMapEntry entry(namespaceURI, name, arg);
1154 entries.push_back(entry);
1155 return arg;
1156 }
1159 /**
1160 * Removes a node specified by name.
1161 */
1162 virtual NodePtr removeNamedItem(const DOMString& name) throw(DOMException)
1163 {
1164 std::vector<NamedNodeMapEntry>::iterator iter;
1165 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1166 {
1167 if (iter->name == name)
1168 {
1169 NodePtr node = iter->node;
1170 entries.erase(iter);
1171 return node;
1172 }
1173 }
1174 return NULL;
1175 }
1177 /**
1178 * Retrieves an item at the given index. If out of bounds, return NULL
1179 */
1180 virtual NodePtr item(unsigned long index)
1181 {
1182 if (index>=entries.size())
1183 return NULL;
1184 return entries[index].node;
1185 }
1187 /**
1188 * Return the number of items in this map
1189 */
1190 virtual unsigned long getLength()
1191 {
1192 return (unsigned long)entries.size();
1193 }
1195 /**
1196 * Retrieves a node specified by local name and namespace URI.
1197 */
1198 virtual NodePtr getNamedItemNS(const DOMString& namespaceURI,
1199 const DOMString& localName)
1200 {
1201 std::vector<NamedNodeMapEntry>::iterator iter;
1202 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1203 {
1204 if (iter->namespaceURI == namespaceURI && iter->name == localName)
1205 {
1206 NodePtr node = iter->node;
1207 return node;
1208 }
1209 }
1210 return NULL;
1211 }
1213 /**
1214 * Adds a node using its namespaceURI and localName. If a node with that
1215 * namespace URI and that local name is already present in this map, it is
1216 * replaced by the new one. Replacing a node by itself has no effect.
1217 */
1218 virtual NodePtr setNamedItemNS(NodePtr arg) throw(DOMException)
1219 {
1220 if (!arg)
1221 return NULL;
1222 DOMString namespaceURI = arg->getNamespaceURI();
1223 DOMString name = arg->getNodeName();
1224 std::vector<NamedNodeMapEntry>::iterator iter;
1225 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1226 {
1227 if (iter->namespaceURI == namespaceURI && iter->name == name)
1228 {
1229 NodePtr node = iter->node;
1230 iter->node = arg;
1231 return node;
1232 }
1233 }
1234 NamedNodeMapEntry entry(namespaceURI, name, arg);
1235 entries.push_back(entry);
1236 return arg;
1237 }
1239 /**
1240 * Removes a node specified by local name and namespace URI.
1241 */
1242 virtual NodePtr removeNamedItemNS(const DOMString& namespaceURI,
1243 const DOMString& localName)
1244 throw(DOMException)
1245 {
1246 std::vector<NamedNodeMapEntry>::iterator iter;
1247 for (iter = entries.begin() ; iter!=entries.end() ; iter++)
1248 {
1249 if (iter->namespaceURI == namespaceURI && iter->name == localName)
1250 {
1251 NodePtr node = iter->node;
1252 entries.erase(iter);
1253 return node;
1254 }
1255 }
1256 return NULL;
1257 }
1260 //##################
1261 //# Non-API methods
1262 //##################
1264 /**
1265 *
1266 */
1267 NamedNodeMap() {}
1270 /**
1271 *
1272 */
1273 NamedNodeMap(const NamedNodeMap &other)
1274 {
1275 entries = other.entries;
1276 }
1278 /**
1279 *
1280 */
1281 NamedNodeMap &operator=(const NamedNodeMap &other)
1282 {
1283 entries = other.entries;
1284 return *this;
1285 }
1288 /**
1289 *
1290 */
1291 virtual ~NamedNodeMap() {}
1293 protected:
1295 std::vector<NamedNodeMapEntry> entries;
1297 };
1302 /*#########################################################################
1303 ## CharacterData
1304 #########################################################################*/
1306 /**
1307 * This is the base class for other text-oriented Nodes, such as TEXT_NODE
1308 * or CDATA_SECTION_NODE. No DOM objects correspond directly to CharacterData.
1309 */
1310 class CharacterData : virtual public Node
1311 {
1312 public:
1314 /**
1315 * This is an alias for getNodeValue()
1316 */
1317 virtual DOMString getData() throw(DOMException) = 0;
1319 /**
1320 * This is an alias for setNodeValue()
1321 */
1322 virtual void setData(const DOMString& val) throw(DOMException) = 0;
1324 /**
1325 * Return the number of characters contained in this node's data
1326 */
1327 virtual unsigned long getLength() = 0;
1329 /**
1330 * Return a substring of this node's data, starting at offset, and
1331 * continuing for 'count' characters. Throw an exception if this goes
1332 * out of range.
1333 */
1334 virtual DOMString substringData(unsigned long offset,
1335 unsigned long count)
1336 throw(DOMException) = 0;
1338 /**
1339 * Append the argument string to the end of the node's current data.
1340 */
1341 virtual void appendData(const DOMString& arg) throw(DOMException) = 0;
1343 /**
1344 * Insert the argument string at the offset position into the node's
1345 * current data. If the position is out of range, throw an Exception.
1346 */
1347 virtual void insertData(unsigned long offset,
1348 const DOMString& arg)
1349 throw(DOMException) = 0;
1351 /**
1352 * Delete 'count' characters from the node's data starting from the
1353 * offset position. If this goes out of range, throw an Exception.
1354 */
1355 virtual void deleteData(unsigned long offset,
1356 unsigned long count)
1357 throw(DOMException) = 0;
1359 /**
1360 * Replace the 'count' characters at the offset position with the given
1361 * argument string. If this goes out of range, throw an Exception.
1362 */
1363 virtual void replaceData(unsigned long offset,
1364 unsigned long count,
1365 const DOMString& arg)
1366 throw(DOMException) = 0;
1369 //##################
1370 //# Non-API methods
1371 //##################
1374 /**
1375 *
1376 */
1377 virtual ~CharacterData() {}
1379 };
1384 /*#########################################################################
1385 ## Attr
1386 #########################################################################*/
1388 /**
1389 * The Attr interface represents an attribute in an Element object.
1390 * Typically the allowable values for the attribute are defined in a
1391 * schema associated with the document.
1392 * Since Attrs are not considered to be part of the DOM tree, parent,
1393 * previousSibling, and nextSibling are null.
1394 */
1395 class Attr : virtual public Node
1396 {
1397 public:
1399 /**
1400 * Returns the name of this attribute. If Node.localName is different
1401 * from null, this attribute is a qualified name.
1402 */
1403 virtual DOMString getName() = 0;
1405 /**
1406 * True if this attribute was explicitly given a value in the instance document,
1407 * false otherwise. If the application changed the value of this attribute node
1408 * (even if it ends up having the same value as the default value) then it is set
1409 * to true. The implementation may handle attributes with default values from
1410 * other schemas similarly but applications should use
1411 * Document.normalizeDocument() to guarantee this information is up-to-date.
1412 */
1413 virtual bool getSpecified() = 0;
1415 /**
1416 * Returns the value of the attribute
1417 */
1418 virtual DOMString getValue() = 0;
1420 /**
1421 * Sets the value of the attribute
1422 */
1423 virtual void setValue(const DOMString& val) throw(DOMException) = 0;
1425 /**
1426 * Return the Element that possesses this attribute
1427 */
1428 virtual ElementPtr getOwnerElement() = 0;
1431 /**
1432 * The type information associated with this attribute.
1433 */
1434 virtual TypeInfo &getSchemaTypeInfo() = 0;
1437 /**
1438 * Returns whether this attribute is known to be of type ID (i.e. to contain an
1439 * identifier for its owner element) or not. When it is and its value is unique,
1440 * the ownerElement of this attribute can be retrieved using the method
1441 * Document.getElementById.
1442 */
1443 virtual bool getIsId() = 0;
1445 //##################
1446 //# Non-API methods
1447 //##################
1450 /**
1451 *
1452 */
1453 virtual ~Attr() {}
1455 };
1461 /*#########################################################################
1462 ## Element
1463 #########################################################################*/
1465 /**
1466 * The Element interface represents an element in an XML document.
1467 * Elements may have attributes associated with them; since the Element interface
1468 * inherits from Node, the generic Node interface attribute attributes may be
1469 * used to retrieve the set of all attributes for an element. There are methods
1470 * on the Element interface to retrieve either an Attr object by name or an
1471 * attribute value by name. In XML, where an attribute value may contain entity
1472 * references, an Attr object should be retrieved to examine the possibly fairly
1473 * complex sub-tree representing the attribute value. On the other hand, in HTML,
1474 * where all attributes have simple string values, methods to directly access an
1475 * attribute value can safely be used as a convenience.
1476 */
1477 class Element : virtual public Node
1478 {
1479 public:
1482 /**
1483 * The name of the element. If Node.localName is different from null,
1484 * this attribute is a qualified name.
1485 */
1486 virtual DOMString getTagName() = 0;
1488 /**
1489 * Retrieves an attribute value by name.
1490 */
1491 virtual DOMString getAttribute(const DOMString& name) = 0;
1493 /**
1494 * Adds a new attribute. If an attribute with that name is already present in the
1495 * element, its value is changed to be that of the value parameter. This value is
1496 * a simple string; it is not parsed as it is being set. So any markup (such as
1497 * syntax to be recognized as an entity reference) is treated as literal text,
1498 * and needs to be appropriately escaped by the implementation when it is written
1499 * out. In order to assign an attribute value that contains entity references,
1500 * the user must create an Attr node plus any Text and EntityReference nodes,
1501 * build the appropriate subtree, and use setAttributeNode to assign it as the
1502 * value of an attribute.
1503 */
1504 virtual void setAttribute(const DOMString& name,
1505 const DOMString& value)
1506 throw(DOMException) = 0;
1508 /**
1509 * Removes an attribute by name. If no attribute with this name is found,
1510 * this method has no effect.
1511 */
1512 virtual void removeAttribute(const DOMString& name)
1513 throw(DOMException) = 0;
1515 /**
1516 * Retrieves an attribute node by name.
1517 */
1518 virtual AttrPtr getAttributeNode(const DOMString& name) = 0;
1520 /**
1521 * Adds a new attribute node. If an attribute with that name (nodeName)
1522 * is already present in the element, it is replaced by the new one.
1523 * Replacing an attribute node by itself has no effect.
1524 */
1525 virtual AttrPtr setAttributeNode(AttrPtr newAttr)
1526 throw(DOMException) = 0;
1528 /**
1529 * Removes the specified attribute node.
1530 */
1531 virtual AttrPtr removeAttributeNode(AttrPtr oldAttr)
1532 throw(DOMException) = 0;
1534 /**
1535 * Returns a NodeList of all descendant Elements with a given tag name,
1536 * in document order.
1537 */
1538 virtual NodeList getElementsByTagName(const DOMString& name) = 0;
1540 /**
1541 * Retrieves an attribute value by local name and namespace URI.
1542 * Per [XML Namespaces], applications must use the value null as the
1543 * namespaceURI parameter for methods if they wish to have no namespace.
1544 */
1545 virtual DOMString getAttributeNS(const DOMString& namespaceURI,
1546 const DOMString& localName) = 0;
1548 /**
1549 * Adds a new attribute. If an attribute with the same local name and namespace
1550 * URI is already present on the element, its prefix is changed to be the prefix
1551 * part of the qualifiedName, and its value is changed to be the value parameter.
1552 * This value is a simple string; it is not parsed as it is being set. So any
1553 * markup (such as syntax to be recognized as an entity reference) is treated as
1554 * literal text, and needs to be appropriately escaped by the implementation when
1555 * it is written out. In order to assign an attribute value that contains entity
1556 * references, the user must create an Attr node plus any Text and
1557 * EntityReference nodes, build the appropriate subtree, and use
1558 * setAttributeNodeNS or setAttributeNode to assign it as the value of an
1559 * attribute.
1560 */
1561 virtual void setAttributeNS(const DOMString& namespaceURI,
1562 const DOMString& qualifiedName,
1563 const DOMString& value)
1564 throw(DOMException) = 0;
1566 /**
1567 * Removes an attribute by local name and namespace URI.
1568 */
1569 virtual void removeAttributeNS(const DOMString& namespaceURI,
1570 const DOMString& localName)
1571 throw(DOMException) = 0;
1573 /**
1574 * Retrieves an Attr node by local name and namespace URI.
1575 */
1576 virtual AttrPtr getAttributeNodeNS(const DOMString& namespaceURI,
1577 const DOMString& localName) = 0;
1579 /**
1580 * Adds a new attribute. If an attribute with that local name and
1581 * that namespace URI is already present in the element, it is
1582 * replaced by the new one. Replacing an attribute node by itself has no effect.
1583 */
1584 virtual AttrPtr setAttributeNodeNS(AttrPtr newAttr)
1585 throw(DOMException) = 0;
1587 /**
1588 * Returns a NodeList of all the descendant Elements with a given
1589 * local name and namespace URI in document order.
1590 */
1591 virtual NodeList getElementsByTagNameNS(const DOMString& namespaceURI,
1592 const DOMString& localName) = 0;
1594 /**
1595 * Returns true when an attribute with a given name is specified on
1596 * this element or has a default value, false otherwise.
1597 */
1598 virtual bool hasAttribute(const DOMString& name) = 0;
1600 /**
1601 * Returns true when an attribute with a given local name and namespace
1602 * URI is specified on this element or has a default value, false otherwise.
1603 */
1604 virtual bool hasAttributeNS(const DOMString& namespaceURI,
1605 const DOMString& localName) = 0;
1607 /**
1608 * The type information associated with this element.
1609 */
1610 virtual TypeInfo &getSchemaTypeInfo() = 0;
1613 /**
1614 * If the parameter isId is true, this method declares the specified
1615 * attribute to be a user-determined ID attribute.
1616 */
1617 virtual void setIdAttribute(const DOMString &name,
1618 bool isId) throw (DOMException) = 0;
1620 /**
1621 * If the parameter isId is true, this method declares the specified
1622 * attribute to be a user-determined ID attribute.
1623 */
1624 virtual void setIdAttributeNS(const DOMString &namespaceURI,
1625 const DOMString &localName,
1626 bool isId) throw (DOMException) = 0;
1628 /**
1629 * If the parameter isId is true, this method declares the specified
1630 * attribute to be a user-determined ID attribute.
1631 */
1632 virtual void setIdAttributeNode(const AttrPtr idAttr,
1633 bool isId) throw (DOMException) = 0;
1635 //##################
1636 //# Non-API methods
1637 //##################
1639 /**
1640 *
1641 */
1642 virtual ~Element() {}
1644 };
1650 /*#########################################################################
1651 ## Text
1652 #########################################################################*/
1654 /**
1655 * The Text interface inherits from CharacterData and represents the textual
1656 * content (termed character data in XML) of an Element or Attr. If there is no
1657 * markup inside an element's content, the text is contained in a single object
1658 * implementing the Text interface that is the only child of the element. If
1659 * there is markup, it is parsed into the information items (elements, comments,
1660 * etc.) and Text nodes that form the list of children of the element.
1661 */
1662 class Text : virtual public CharacterData
1663 {
1664 public:
1666 /**
1667 * Breaks this node into two nodes at the specified offset, keeping both in the
1668 * tree as siblings. After being split, this node will contain all the content up
1669 * to the offset point. A new node of the same type, which contains all the
1670 * content at and after the offset point, is returned. If the original node had a
1671 * parent node, the new node is inserted as the next sibling of the original
1672 * node. When the offset is equal to the length of this node, the new node has no
1673 * data.
1674 */
1675 virtual TextPtr splitText(unsigned long offset)
1676 throw(DOMException) = 0;
1678 /**
1679 * Returns whether this text node contains element content whitespace, often
1680 * abusively called "ignorable whitespace". The text node is determined to
1681 * contain whitespace in element content during the load of the document or if
1682 * validation occurs while using Document.normalizeDocument().
1683 */
1684 virtual bool getIsElementContentWhitespace()= 0;
1686 /**
1687 * Returns all text of Text nodes logically-adjacent text nodes
1688 * to this node, concatenated in document order.
1689 */
1690 virtual DOMString getWholeText() = 0;
1693 /**
1694 * Replaces the text of the current node and all logically-adjacent text nodes
1695 * with the specified text. All logically-adjacent text nodes are removed
1696 * including the current node unless it was the recipient of the replacement text.
1697 *
1698 * This method returns the node which received the replacement text. The returned
1699 * node is:
1700 * o null, when the replacement text is the empty string;
1701 * o the current node, except when the current node is read-only;
1702 * o a new Text node of the same type (Text or CDATASection) as
1703 * the current node inserted at the location of the replacement.
1704 */
1705 virtual TextPtr replaceWholeText(const DOMString &content)
1706 throw(DOMException) = 0;
1708 //##################
1709 //# Non-API methods
1710 //##################
1713 /**
1714 *
1715 */
1716 virtual ~Text() {}
1718 };
1722 /*#########################################################################
1723 ## Comment
1724 #########################################################################*/
1726 /**
1727 * This interface inherits from CharacterData and represents the content of a
1728 * comment, i.e., all the characters between the starting '<!--' and ending '-->'.
1729 * Note that this is the definition of a comment in XML, and, in practice,
1730 * HTML, although some HTML tools may implement the full SGML comment structure.
1731 */
1732 class Comment : virtual public CharacterData
1733 {
1734 public:
1736 //##################
1737 //# Non-API methods
1738 //##################
1741 /**
1742 *
1743 */
1744 virtual ~Comment() {}
1747 };
1751 /*#########################################################################
1752 ## TypeInfo
1753 #########################################################################*/
1755 /**
1756 * The TypeInfo interface represents a type referenced from Element or Attr nodes,
1757 * specified in the schemas associated with the document. The type is a pair of
1758 * a namespace URI and name properties, and depends on the document's schema.
1759 */
1760 class TypeInfo
1761 {
1762 public:
1764 /**
1765 * The name of a type declared for the associated element or attribute,
1766 * or null if unknown.
1767 */
1768 virtual DOMString getTypeName()
1769 { return typeName; }
1771 /**
1772 * The namespace of the type declared for the associated element
1773 * or attribute or null if the element does not have declaration or
1774 * if no namespace information is available.
1775 */
1776 virtual DOMString getTypeNamespace()
1777 { return typeNameSpace; }
1779 /**
1780 * These are the available values for the derivationMethod parameter used by the
1781 * method TypeInfo.isDerivedFrom(). It is a set of possible types of derivation,
1782 * and the values represent bit positions. If a bit in the derivationMethod
1783 * parameter is set to 1, the corresponding type of derivation will be taken into
1784 * account when evaluating the derivation between the reference type definition
1785 * and the other type definition. When using the isDerivedFrom method, combining
1786 * all of them in the derivationMethod parameter is equivalent to invoking the
1787 * method for each of them separately and combining the results with the OR
1788 * boolean function. This specification only defines the type of derivation for
1789 * XML Schema.
1790 */
1791 typedef enum
1792 {
1793 DERIVATION_RESTRICTION = 0x00000001,
1794 DERIVATION_EXTENSION = 0x00000002,
1795 DERIVATION_UNION = 0x00000004,
1796 DERIVATION_LIST = 0x00000008
1797 } DerivationMethod;
1800 /**
1801 * This method returns if there is a derivation between the reference
1802 * type definition, i.e. the TypeInfo on which the method is being called,
1803 * and the other type definition, i.e. the one passed as parameters.
1804 */
1805 virtual bool isDerivedFrom(const DOMString &/*typeNamespaceArg*/,
1806 const DOMString &/*typeNameArg*/,
1807 DerivationMethod /*derivationMethod*/)
1808 { return false; }
1810 //##################
1811 //# Non-API methods
1812 //##################
1815 /**
1816 *
1817 */
1818 TypeInfo()
1819 {}
1821 /**
1822 *
1823 */
1824 TypeInfo(const TypeInfo &other)
1825 { assign(other); }
1827 /**
1828 *
1829 */
1830 TypeInfo &operator=(const TypeInfo &other)
1831 { assign(other); return *this; }
1833 /**
1834 *
1835 */
1836 virtual ~TypeInfo() {}
1838 private:
1840 void assign(const TypeInfo &other)
1841 {
1842 typeName = other.typeName;
1843 typeNameSpace = other.typeNameSpace;
1844 }
1846 DOMString typeName;
1847 DOMString typeNameSpace;
1848 };
1853 /*#########################################################################
1854 ## UserDataHandler
1855 #########################################################################*/
1857 /**
1858 * When associating an object to a key on a node using Node.setUserData() the
1859 * application can provide a handler that gets called when the node the object is
1860 * associated to is being cloned, imported, or renamed. This can be used by the
1861 * application to implement various behaviors regarding the data it associates to
1862 * the DOM nodes. This interface defines that handler.
1863 */
1864 class UserDataHandler
1865 {
1866 public:
1868 /**
1869 * An integer indicating the type of operation being performed on a node.
1870 */
1871 typedef enum
1872 {
1873 NODE_CLONED = 1,
1874 NODE_IMPORTED = 2,
1875 NODE_DELETED = 3,
1876 NODE_RENAMED = 4,
1877 NODE_ADOPTED = 5
1878 } OperationType;
1881 /**
1882 * This method is called whenever the node for which this handler
1883 * is registered is imported or cloned.
1884 */
1885 virtual void handle(unsigned short operation,
1886 const DOMString &key,
1887 const DOMUserData *data,
1888 const NodePtr src,
1889 const NodePtr dst) =0;
1891 //##################
1892 //# Non-API methods
1893 //##################
1896 /**
1897 *
1898 */
1899 virtual ~UserDataHandler() {}
1901 };
1904 /*#########################################################################
1905 ## DOMError
1906 #########################################################################*/
1908 /**
1909 * DOMError is an interface that describes an error.
1910 */
1911 class DOMError
1912 {
1913 public:
1915 /**
1916 * An integer indicating the severity of the error.
1917 */
1918 typedef enum
1919 {
1920 SEVERITY_WARNING = 1,
1921 SEVERITY_ERROR = 2,
1922 SEVERITY_FATAL_ERROR = 3
1923 } ErrorSeverity;
1926 /**
1927 * The severity of the error, either SEVERITY_WARNING, SEVERITY_ERROR,
1928 * or SEVERITY_FATAL_ERROR.
1929 */
1930 virtual unsigned short getSeverity() =0;
1932 /**
1933 * An implementation specific string describing the error that occurred.
1934 */
1935 virtual DOMString getMessage() =0;
1937 /**
1938 * A DOMString indicating which related data is expected in relatedData.
1939 * Users should refer to the specification of the error in order to find
1940 * its DOMString type and relatedData definitions if any.
1941 */
1942 virtual DOMString getType() =0;
1944 /**
1945 * The related platform dependent exception if any.
1946 */
1947 virtual DOMObject *getRelatedException() =0;
1949 /**
1950 * The related DOMError.type dependent data if any.
1951 */
1952 virtual DOMObject *getRelatedData() =0;
1954 /**
1955 * The location of the error.
1956 */
1957 virtual DOMLocator *getLocation() =0;
1960 //##################
1961 //# Non-API methods
1962 //##################
1965 /**
1966 *
1967 */
1968 virtual ~DOMError() {}
1970 };
1973 /*#########################################################################
1974 ## DOMErrorHandler
1975 #########################################################################*/
1977 /**
1978 * DOMErrorHandler is a callback interface that the DOM implementation can call
1979 * when reporting errors that happens while processing XML data, or when doing
1980 * some other processing (e.g. validating a document). A DOMErrorHandler object
1981 * can be attached to a Document using the "error-handler" on the
1982 * DOMConfiguration interface. If more than one error needs to be reported during
1983 * an operation, the sequence and numbers of the errors passed to the error
1984 * handler are implementation dependent.
1985 */
1986 class DOMErrorHandler
1987 {
1988 public:
1990 /**
1991 * This method is called on the error handler when an error occurs.
1992 * If an exception is thrown from this method, it is considered to be
1993 * equivalent of returning true.
1994 */
1995 virtual bool handleError(const DOMError *error) =0;
1998 //##################
1999 //# Non-API methods
2000 //##################
2002 /**
2003 *
2004 */
2005 virtual ~DOMErrorHandler() {}
2007 };
2011 /*#########################################################################
2012 ## DOMLocator
2013 #########################################################################*/
2015 /**
2016 * DOMLocator is an interface that describes a location (e.g. where an error occurred).
2017 */
2018 class DOMLocator
2019 {
2020 public:
2022 /**
2023 * The line number this locator is pointing to, or -1 if there is
2024 * no column number available.
2025 */
2026 virtual long getLineNumber() =0;
2028 /**
2029 * The column number this locator is pointing to, or -1 if there is
2030 * no column number available.
2031 */
2032 virtual long getColumnNumber() =0;
2034 /**
2035 * The byte offset into the input source this locator is pointing to
2036 * or -1 if there is no byte offset available.
2037 */
2038 virtual long getByteOffset() =0;
2040 /**
2041 * The UTF-16, as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646],
2042 * offset into the input source this locator is pointing to or -1
2043 * if there is no UTF-16 offset available.
2044 */
2045 virtual long getUtf16Offset() =0;
2048 /**
2049 * The node this locator is pointing to, or null if no node is available.
2050 */
2051 virtual NodePtr getRelatedNode() =0;
2054 /**
2055 * The URI this locator is pointing to, or null if no URI is available.
2056 */
2057 virtual DOMString getUri() =0;
2059 //##################
2060 //# Non-API methods
2061 //##################
2063 /**
2064 *
2065 */
2066 virtual ~DOMLocator() {}
2067 };
2070 /*#########################################################################
2071 ## DOMConfiguration
2072 #########################################################################*/
2074 /**
2075 * The DOMConfiguration interface represents the configuration of a document and
2076 * maintains a table of recognized parameters. Using the configuration, it is
2077 * possible to change Document.normalizeDocument() behavior, such as replacing
2078 * the CDATASection nodes with Text nodes or specifying the type of the schema
2079 * that must be used when the validation of the Document is requested.
2080 * DOMConfiguration objects are also used in [DOM Level 3 Load and Save] in the
2081 * DOMParser and DOMSerializer interfaces.
2082 *
2083 * Look here for a list of valid parameters:
2084 * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration
2085 */
2086 class DOMConfiguration
2087 {
2088 public:
2090 /**
2091 * Set the value of a parameter.
2092 */
2093 virtual void setParameter(const DOMString &name,
2094 const DOMUserData *value)
2095 throw (DOMException) =0;
2097 /**
2098 * Return the value of a parameter if known.
2099 */
2100 virtual DOMUserData *getParameter(const DOMString &name)
2101 throw (DOMException) =0;
2103 /**
2104 * Check if setting a parameter to a specific value is supported.
2105 */
2106 virtual bool canSetParameter(const DOMString &name,
2107 const DOMUserData *data) =0;
2109 /**
2110 * The list of the parameters supported by this DOMConfiguration
2111 * object and for which at least one value can be set by the application.
2112 * Note that this list can also contain parameter names defined outside
2113 * this specification.
2114 */
2115 virtual DOMStringList *getParameterNames() =0;
2117 //##################
2118 //# Non-API methods
2119 //##################
2122 /**
2123 *
2124 */
2125 virtual ~DOMConfiguration() {}
2127 };
2134 /*#########################################################################
2135 ## CDATASection
2136 #########################################################################*/
2138 /**
2139 * CDATA sections are used to escape blocks of text containing characters that
2140 * would otherwise be regarded as markup. The only delimiter that is recognized
2141 * in a CDATA section is the "]]>" string that ends the CDATA section. CDATA
2142 * sections cannot be nested. Their primary purpose is for including material
2143 * such as XML fragments, without needing to escape all the delimiters.
2144 */
2145 class CDATASection : virtual public Text
2146 {
2147 public:
2149 //##################
2150 //# Non-API methods
2151 //##################
2154 /**
2155 *
2156 */
2157 virtual ~CDATASection() {}
2159 };
2164 /*#########################################################################
2165 ## DocumentType
2166 #########################################################################*/
2168 /**
2169 * Each Document has a doctype attribute whose value is either null or a
2170 * DocumentType object. The DocumentType interface in the DOM Core provides an
2171 * interface to the list of entities that are defined for the document, and
2172 * little else because the effect of namespaces and the various XML schema
2173 * efforts on DTD representation are not clearly understood as of this writing.
2174 */
2175 class DocumentType : virtual public Node
2176 {
2177 public:
2179 /**
2180 * The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
2181 */
2182 virtual DOMString getName() = 0;
2184 /**
2185 * A NamedNodeMap containing the general entities, both external and
2186 * internal, declared in the DTD. Parameter entities are not contained.
2187 * Duplicates are discarded.
2188 */
2189 virtual NamedNodeMap getEntities() = 0;
2191 /**
2192 * A NamedNodeMap containing the notations declared in the DTD. Duplicates
2193 * are discarded. Every node in this map also implements the
2194 * Notation interface.
2195 */
2196 virtual NamedNodeMap getNotations() = 0;
2198 /**
2199 * The public identifier of the external subset.
2200 */
2201 virtual DOMString getPublicId() = 0;
2203 /**
2204 * The system identifier of the external subset. This may be an
2205 * absolute URI or not.
2206 */
2207 virtual DOMString getSystemId() = 0;
2209 /**
2210 * The internal subset as a string, or null if there is none. This
2211 * does not contain the delimiting square brackets.
2212 */
2213 virtual DOMString getInternalSubset() = 0;
2215 //##################
2216 //# Non-API methods
2217 //##################
2219 /**
2220 *
2221 */
2222 virtual ~DocumentType() {}
2224 };
2230 /*#########################################################################
2231 ## Notation
2232 #########################################################################*/
2234 /**
2235 * This interface represents a notation declared in the DTD. A notation either
2236 * declares, by name, the format of an unparsed entity (see section 4.7 of the
2237 * XML 1.0 specification [XML 1.0]), or is used for formal declaration of
2238 * processing instruction targets (see section 2.6 of the XML 1.0 specification
2239 * [XML 1.0]). The nodeName attribute inherited from Node is set to the declared
2240 * name of the notation.
2241 */
2242 class Notation : virtual public Node
2243 {
2244 public:
2246 /**
2247 * The public identifier of this notation. If the public identifier was
2248 * not specified, this is null.
2249 */
2250 virtual DOMString getPublicId() = 0;
2252 /**
2253 * The system identifier of this notation. If the system identifier was
2254 * not specified, this is null. This may be an absolute URI or not.
2255 */
2256 virtual DOMString getSystemId() = 0;
2258 //##################
2259 //# Non-API methods
2260 //##################
2263 /**
2264 *
2265 */
2266 virtual ~Notation() {}
2267 };
2274 /*#########################################################################
2275 ## Entity
2276 #########################################################################*/
2278 /**
2279 * This interface represents a known entity, either parsed or unparsed, in an XML
2280 * document. Note that this models the entity itself not the entity declaration.
2281 */
2282 class Entity : virtual public Node
2283 {
2284 public:
2286 /**
2287 * The public identifier associated with the entity if specified,
2288 * and null otherwise.
2289 */
2290 virtual DOMString getPublicId() = 0;
2292 /**
2293 * The system identifier associated with the entity if specified,
2294 * and null otherwise. This may be an absolute URI or not.
2295 */
2296 virtual DOMString getSystemId() = 0;
2298 /**
2299 * For unparsed entities, the name of the notation for the entity.
2300 * For parsed entities, this is null.
2301 */
2302 virtual DOMString getNotationName() = 0;
2304 /**
2305 * An attribute specifying the encoding used for this entity at the
2306 * time of parsing, when it is an external parsed entity. This is null
2307 * if it an entity from the internal subset or if it is not known.
2308 */
2309 virtual DOMString getInputEncoding() = 0;
2311 /**
2312 * An attribute specifying, as part of the text declaration, the encoding
2313 * of this entity, when it is an external parsed entity. This is null otherwise.
2314 */
2315 virtual DOMString getXmlEncoding() = 0;
2317 /**
2318 * An attribute specifying, as part of the text declaration, the version
2319 * number of this entity, when it is an external parsed entity.
2320 * This is null otherwise.
2321 */
2322 virtual DOMString getXmlVersion() = 0;
2324 //##################
2325 //# Non-API methods
2326 //##################
2329 /**
2330 *
2331 */
2332 virtual ~Entity() {}
2333 };
2339 /*#########################################################################
2340 ## EntityReference
2341 #########################################################################*/
2343 /**
2344 * EntityReference nodes may be used to represent an entity reference in the tree.
2345 */
2346 class EntityReference : virtual public Node
2347 {
2348 public:
2351 //##################
2352 //# Non-API methods
2353 //##################
2355 /**
2356 *
2357 */
2358 virtual ~EntityReference() {}
2359 };
2365 /*#########################################################################
2366 ## ProcessingInstruction
2367 #########################################################################*/
2369 /**
2370 * The ProcessingInstruction interface represents a "processing instruction",
2371 * used in XML as a way to keep processor-specific information in the text of the
2372 * document.
2373 */
2374 class ProcessingInstruction : virtual public Node
2375 {
2376 public:
2378 /**
2379 * The target of this processing instruction. XML defines this as being
2380 * the first token following the markup that begins the processing instruction.
2381 */
2382 virtual DOMString getTarget() = 0;
2384 /**
2385 * The content of this processing instruction. This is from the first non
2386 * white space character after the target to the character immediately
2387 * preceding the ?>.
2388 */
2389 virtual DOMString getData() = 0;
2391 /**
2392 * Sets the content above.
2393 */
2394 virtual void setData(const DOMString& val) throw(DOMException) = 0;
2396 //##################
2397 //# Non-API methods
2398 //##################
2401 /**
2402 *
2403 */
2404 virtual ~ProcessingInstruction() {}
2406 };
2412 /*#########################################################################
2413 ## DocumentFragment
2414 #########################################################################*/
2416 /**
2417 * DocumentFragment is a "lightweight" or "minimal" Document object. It is very
2418 * common to want to be able to extract a portion of a document's tree or to
2419 * create a new fragment of a document. Imagine implementing a user command like
2420 * cut or rearranging a document by moving fragments around. It is desirable to
2421 * have an object which can hold such fragments and it is quite natural to use a
2422 * Node for this purpose. While it is true that a Document object could fulfill
2423 * this role, a Document object can potentially be a heavyweight object,
2424 * depending on the underlying implementation. What is really needed for this is
2425 * a very lightweight object. DocumentFragment is such an object.
2426 */
2427 class DocumentFragment : virtual public Node
2428 {
2429 public:
2431 //##################
2432 //# Non-API methods
2433 //##################
2436 /**
2437 *
2438 */
2439 virtual ~DocumentFragment() {}
2440 };
2447 /*#########################################################################
2448 ## Document
2449 #########################################################################*/
2451 /**
2452 * From the spec:
2453 *
2454 * The Document interface represents the entire HTML or XML document.
2455 * Conceptually, it is the root of the document tree, and provides the primary
2456 * access to the document's data.
2457 *
2458 * Since elements, text nodes, comments, processing instructions, etc. cannot
2459 * exist outside the context of a Document, the Document interface also contains
2460 * the factory methods needed to create these objects. The Node objects created
2461 * have a ownerDocument attribute which associates them with the Document within
2462 * whose context they were created.
2463 *
2464 */
2465 class Document : virtual public Node
2466 {
2467 public:
2469 /**
2470 * The Document Type Declaration (see DocumentType) associated with this document.
2471 */
2472 virtual DocumentTypePtr getDoctype() = 0;
2474 /**
2475 * The DOMImplementation object that handles this document. A DOM application
2476 * may use objects from multiple implementations.
2477 */
2478 virtual DOMImplementation *getImplementation() = 0;
2480 /**
2481 * This is a convenience attribute that allows direct access to the child
2482 * node that is the document element of the document.
2483 */
2484 virtual ElementPtr getDocumentElement() = 0;
2486 /**
2487 * Creates an element of the type specified.
2488 */
2489 virtual ElementPtr createElement(const DOMString& tagName)
2490 throw(DOMException) = 0;
2492 /**
2493 * Creates a new, empty DocumentFragment
2494 */
2495 virtual DocumentFragmentPtr createDocumentFragment() = 0;
2497 /**
2498 * Creates an Text node with the text data specified.
2499 */
2500 virtual TextPtr createTextNode(const DOMString& text) = 0;
2502 /**
2503 * Creates a new Comment node with the argument text
2504 */
2505 virtual CommentPtr createComment(const DOMString& text) = 0;
2507 /**
2508 * Creates a new CDATASection node with the argument text
2509 */
2510 virtual CDATASectionPtr createCDATASection(const DOMString& text)
2511 throw(DOMException) = 0;
2513 /**
2514 * Creates a new ProcessingInstruction
2515 */
2516 virtual ProcessingInstructionPtr
2517 createProcessingInstruction(const DOMString& target,
2518 const DOMString& data)
2519 throw(DOMException) = 0;
2521 /**
2522 * Creates a new Attr with the given name, but no value.
2523 */
2524 virtual AttrPtr createAttribute(const DOMString& name)
2525 throw(DOMException) = 0;
2527 /**
2528 * Creates a new EntityReference
2529 */
2530 virtual EntityReferencePtr createEntityReference(const DOMString& name)
2531 throw(DOMException) = 0;
2533 /**
2534 * Searches the Document in document order for all elements with the given
2535 * tag name
2536 */
2537 virtual NodeList getElementsByTagName(const DOMString& tagname) = 0;
2540 /**
2541 * Imports a node from another document to this document, without altering or
2542 * removing the source node from the original document; this method creates a new
2543 * copy of the source node. The returned node has no parent; (parentNode is
2544 * null). For all nodes, importing a node creates a node object owned by the
2545 * importing document, with attribute values identical to the source node's
2546 * nodeName and nodeType, plus the attributes related to namespaces (prefix,
2547 * localName, and namespaceURI). As in the cloneNode operation, the source node
2548 * is not altered. User data associated to the imported node is not carried over.
2549 * However, if any UserDataHandlers has been specified along with the associated
2550 * data these handlers will be called with the appropriate parameters before this
2551 * method returns. Additional information is copied as appropriate to the
2552 * nodeType, attempting to mirror the behavior expected if a fragment of XML or
2553 * HTML source was copied from one document to another, recognizing that the two
2554 * documents may have different DTDs in the XML case. The following list
2555 * describes the specifics for each type of node.
2556 */
2557 virtual NodePtr importNode(const NodePtr importedNode,
2558 bool deep)
2559 throw(DOMException) = 0;
2561 /**
2562 * Creates a new Element with the given namespace and qualifiedName.
2563 * Use "" for no namespace
2564 */
2565 virtual ElementPtr createElementNS(const DOMString& namespaceURI,
2566 const DOMString& qualifiedName)
2567 throw(DOMException) = 0;
2569 /**
2570 * Creates a new Attr with the given namespace and qualifiedName.
2571 */
2572 virtual AttrPtr createAttributeNS(const DOMString& namespaceURI,
2573 const DOMString& qualifiedName)
2574 throw(DOMException) = 0;
2576 /**
2577 * Searches the Document in document order for all elements with the given
2578 * namespace and tag name
2579 */
2580 virtual NodeList getElementsByTagNameNS(const DOMString& namespaceURI,
2581 const DOMString& localName) = 0;
2583 /**
2584 * Gets the element with the given id if it exists, else null.
2585 */
2586 virtual ElementPtr getElementById(const DOMString& elementId) = 0;
2589 /**
2590 * Return the input encoding of this Document
2591 */
2592 virtual DOMString getInputEncoding() = 0;
2595 /**
2596 * Return the XML encoding of this Document
2597 */
2598 virtual DOMString getXmlEncoding() = 0;
2600 /**
2601 * An attribute specifying, as part of the XML declaration, whether
2602 * this document is standalone. This is false when unspecified.
2603 */
2604 virtual bool getXmlStandalone() = 0;
2606 /**
2607 * Sets whether this is a standalone XML document. No validation is
2608 * done here.
2609 */
2610 virtual void setXmlStandalone(bool val) throw (DOMException) = 0;
2612 /**
2613 * Gets the version (1.0, 1.1, etc) of this document.
2614 */
2615 virtual DOMString getXmlVersion() = 0;
2617 /**
2618 * Sets the XML version of this document.
2619 */
2620 virtual void setXmlVersion(const DOMString &version)
2621 throw (DOMException) = 0;
2623 /**
2624 * An attribute specifying whether error checking is enforced or not. When set to
2625 * false, the implementation is free to not test every possible error case
2626 * normally defined on DOM operations, and not raise any DOMException on DOM
2627 * operations or report errors while using Document.normalizeDocument(). In case
2628 * of error, the behavior is undefined. This attribute is true by default.
2629 */
2630 virtual bool getStrictErrorChecking() = 0;
2632 /**
2633 * Sets the value described above.
2634 */
2635 virtual void setStrictErrorChecking(bool val) = 0;
2638 /**
2639 * Gets the document URI (the base location) of this Document.
2640 */
2641 virtual DOMString getDocumentURI() = 0;
2643 /**
2644 * Sets the document URI (the base location) of this Document to the
2645 * argument uri.
2646 */
2647 virtual void setDocumentURI(const DOMString &uri) = 0;
2649 /**
2650 * Attempts to adopt a node from another document to this document. If supported,
2651 * it changes the ownerDocument of the source node, its children, as well as the
2652 * attached attribute nodes if there are any. If the source node has a parent it
2653 * is first removed from the child list of its parent. This effectively allows
2654 * moving a subtree from one document to another (unlike importNode() which
2655 * create a copy of the source node instead of moving it). When it fails,
2656 * applications should use Document.importNode() instead. Note that if the
2657 * adopted node is already part of this document (i.e. the source and target
2658 * document are the same), this method still has the effect of removing the
2659 * source node from the child list of its parent, if any.
2660 */
2661 virtual NodePtr adoptNode(const NodePtr source) throw (DOMException) = 0;
2663 /**
2664 * Get the configuration item associated with this Document
2665 */
2666 virtual DOMConfiguration *getDomConfig() = 0;
2668 /**
2669 * This method acts as if the document was going through a save and load cycle,
2670 * putting the document in a "normal" form. As a consequence, this method updates
2671 * the replacement tree of EntityReference nodes and normalizes Text nodes, as
2672 * defined in the method Node.normalize(). Otherwise, the actual result depends
2673 * on the features being set on the Document.domConfig object and governing what
2674 * operations actually take place. Noticeably this method could also make the
2675 * document namespace well-formed according to the algorithm described in
2676 * Namespace Normalization, check the character normalization, remove the
2677 * CDATASection nodes, etc. See DOMConfiguration for details.
2678 */
2679 virtual void normalizeDocument() = 0;
2681 /**
2682 *
2683 * Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE. When possible
2684 * this simply changes the name of the given node, otherwise this creates a new
2685 * node with the specified name and replaces the existing node with the new node
2686 * as described below. If simply changing the name of the given node is not
2687 * possible, the following operations are performed: a new node is created, any
2688 * registered event listener is registered on the new node, any user data
2689 * attached to the old node is removed from that node, the old node is removed
2690 * from its parent if it has one, the children are moved to the new node, if the
2691 * renamed node is an Element its attributes are moved to the new node, the new
2692 * node is inserted at the position the old node used to have in its parent's
2693 * child nodes list if it has one, the user data that was attached to the old
2694 * node is attached to the new node. When the node being renamed is an Element
2695 * only the specified attributes are moved, default attributes originated from
2696 * the DTD are updated according to the new element name. In addition, the
2697 * implementation may update default attributes from other schemas. Applications
2698 * should use Document.normalizeDocument() to guarantee these attributes are
2699 * up-to-date. When the node being renamed is an Attr that is attached to an
2700 * Element, the node is first removed from the Element attributes map. Then, once
2701 * renamed, either by modifying the existing node or creating a new one as
2702 * described above, it is put back.
2703 *
2704 * In addition,
2705 * a user data event NODE_RENAMED is fired,
2706 * when the implementation supports the feature "MutationNameEvents",
2707 * each mutation operation involved in this method fires the appropriate
2708 * event, and in the end the event {http://www.w3.org/2001/xml-events,
2709 * DOMElementNameChanged} or {http://www.w3.org/2001/xml-events,
2710 * DOMAttributeNameChanged} is fired.
2711 *
2712 */
2713 virtual NodePtr renameNode(const NodePtr n,
2714 const DOMString &namespaceURI,
2715 const DOMString &qualifiedName)
2716 throw (DOMException) = 0;
2719 //##################
2720 //# Non-API methods
2721 //##################
2723 /**
2724 *
2725 */
2726 virtual ~Document() {}
2728 };
2737 } //namespace dom
2738 } //namespace w3c
2739 } //namespace org
2742 #endif // __DOM_H__
2745 /*#########################################################################
2746 ## E N D O F F I L E
2747 #########################################################################*/