pupnp (libupnp) snapshot from SourceForge: git clone git://pupnp.git.sourceforge...
[igd2-for-linux:pandonghui1211s-igd2-for-linux.git] / pupnp_branch-1.6.x / ixml / inc / ixml.h
1 /**************************************************************************
2  *
3  * Copyright (c) 2000-2003 Intel Corporation 
4  * All rights reserved. 
5  *
6  * Redistribution and use in source and binary forms, with or without 
7  * modification, are permitted provided that the following conditions are met: 
8  *
9  * - Redistributions of source code must retain the above copyright notice, 
10  * this list of conditions and the following disclaimer. 
11  * - Redistributions in binary form must reproduce the above copyright notice, 
12  * this list of conditions and the following disclaimer in the documentation 
13  * and/or other materials provided with the distribution. 
14  * - Neither name of Intel Corporation nor the names of its contributors 
15  * may be used to endorse or promote products derived from this software 
16  * without specific prior written permission.
17  * 
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
22  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
25  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
26  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  *
30  **************************************************************************/
31
32
33 #ifndef IXML_H
34 #define IXML_H
35
36
37 /*!
38  * \file
39  *
40  * \defgroup XMLAPI XML API
41  *
42  * @{
43  */
44
45
46 #include "UpnpGlobal.h" /* For EXPORT_SPEC */
47
48
49 typedef int BOOL;
50
51
52 /*!
53  * \brief The type of DOM strings.
54  */
55 #define DOMString char *
56 /*typedef char *DOMString;*/
57
58
59 #ifndef TRUE
60 #define TRUE 1
61 #endif
62
63 #ifndef FALSE
64 #define FALSE 0
65 #endif
66
67 #ifndef IN
68 #define IN
69 #endif
70
71 #ifndef OUT
72 #define OUT
73 #endif
74
75 #ifndef INOUT
76 #define INOUT
77 #endif
78
79
80 /*!
81  * \name DOM Interfaces
82  *
83  * The Document Object Model consists of a set of objects and interfaces
84  * for accessing and manipulating documents.  IXML does not implement all
85  * the interfaces documented in the DOM2-Core recommendation but defines
86  * a subset of the most useful interfaces.  A description of the supported
87  * interfaces and methods is presented in this section.
88  *
89  * For a complete discussion on the object model, the object hierarchy,
90  * etc., refer to section 1.1 of the DOM2-Core recommendation.
91  *
92  * @{
93  */
94
95
96 /*!
97  * \brief The type of the DOM node
98  */
99 typedef enum {
100         eINVALID_NODE                = 0,
101         eELEMENT_NODE                = 1,
102         eATTRIBUTE_NODE              = 2,
103         eTEXT_NODE                   = 3,
104         eCDATA_SECTION_NODE          = 4,
105         eENTITY_REFERENCE_NODE       = 5,
106         eENTITY_NODE                 = 6,                
107         ePROCESSING_INSTRUCTION_NODE = 7,
108         eCOMMENT_NODE                = 8,
109         eDOCUMENT_NODE               = 9,
110         eDOCUMENT_TYPE_NODE          = 10,
111         eDOCUMENT_FRAGMENT_NODE      = 11,
112         eNOTATION_NODE               = 12,
113 }   IXML_NODE_TYPE;
114
115
116 /*!
117  * \brief Error codes returned by the XML API, see the DOM spec
118  */
119 typedef enum {
120         IXML_SUCCESS                     = 0,
121
122         IXML_INDEX_SIZE_ERR              = 1,
123         IXML_DOMSTRING_SIZE_ERR          = 2,
124         IXML_HIERARCHY_REQUEST_ERR       = 3,
125         IXML_WRONG_DOCUMENT_ERR          = 4,
126         IXML_INVALID_CHARACTER_ERR       = 5,
127         IXML_NO_DATA_ALLOWED_ERR         = 6,
128         IXML_NO_MODIFICATION_ALLOWED_ERR = 7,
129         IXML_NOT_FOUND_ERR               = 8,
130         IXML_NOT_SUPPORTED_ERR           = 9,
131         IXML_INUSE_ATTRIBUTE_ERR         = 10,
132         IXML_INVALID_STATE_ERR           = 11,
133         IXML_SYNTAX_ERR                  = 12,
134         IXML_INVALID_MODIFICATION_ERR    = 13,
135         IXML_NAMESPACE_ERR               = 14,
136         IXML_INVALID_ACCESS_ERR          = 15,
137
138         IXML_NO_SUCH_FILE                = 101,
139         IXML_INSUFFICIENT_MEMORY         = 102,
140         IXML_FILE_DONE                   = 104,
141         IXML_INVALID_PARAMETER           = 105,
142         IXML_FAILED                      = 106,
143         IXML_INVALID_ITEM_NUMBER         = 107,
144 } IXML_ERRORCODE;
145
146
147 #define DOCUMENTNODENAME    "#document"
148 #define TEXTNODENAME        "#text"
149 #define CDATANODENAME       "#cdata-section"
150
151
152 typedef struct _IXML_Document *Docptr;
153
154
155 typedef struct _IXML_Node     *Nodeptr;
156
157
158 /*!
159  * \brief Data structure common to all types of nodes.
160  */
161 typedef struct _IXML_Node
162 {
163         DOMString         nodeName;
164         DOMString         nodeValue;
165         IXML_NODE_TYPE    nodeType;
166         DOMString         namespaceURI;
167         DOMString         prefix;
168         DOMString         localName;
169         BOOL              readOnly;
170                           
171         Nodeptr           parentNode;
172         Nodeptr           firstChild;
173         Nodeptr           prevSibling;
174         Nodeptr           nextSibling;
175         Nodeptr           firstAttr;
176         Docptr            ownerDocument;
177 } IXML_Node;
178
179
180 /*!
181  * \brief Data structure representing the DOM Document.
182  */
183 typedef struct _IXML_Document
184 {
185         IXML_Node n;
186 } IXML_Document;
187
188
189 /*!
190  * \brief Data structure representing a CDATA section node.
191  */
192 typedef struct _IXML_CDATASection
193 {
194         IXML_Node n;
195 } IXML_CDATASection;
196
197
198 /*!
199  * \brief Data structure representing an Element node.
200  */
201 typedef struct _IXML_Element
202 {
203         IXML_Node n;
204         DOMString tagName;
205 } IXML_Element;
206
207
208 /*!
209  * \brief Data structure representing an Attribute node.
210  */
211 typedef struct _IXML_ATTR
212 {
213         IXML_Node n;
214         BOOL specified;
215         IXML_Element *ownerElement;
216 } IXML_Attr;
217
218
219 /*!
220  * \brief Data structure representing a Text node.
221  */
222 typedef struct _IXML_Text
223 {
224         IXML_Node n;
225 } IXML_Text;
226
227
228 /*!
229  * \brief Data structure representing a list of nodes.
230  */
231 typedef struct _IXML_NodeList
232 {
233         IXML_Node *nodeItem;
234         struct  _IXML_NodeList *next;
235 } IXML_NodeList;
236
237
238 /*!
239  * \brief Data structure representing a list of named nodes.
240  */
241 typedef struct _IXML_NamedNodeMap
242 {
243         IXML_Node *nodeItem;
244         struct _IXML_NamedNodeMap *next;
245 } IXML_NamedNodeMap;
246
247 /* @} DOM Interfaces */
248
249
250
251 #ifdef __cplusplus
252 extern "C" {
253 #endif
254
255
256 /*!
257  * \name Interface Node
258  *
259  * The \b Node interface forms the primary datatype for all other DOM 
260  * objects. Every other interface is derived from this interface, inheriting 
261  * its functionality. For more information, refer to DOM2-Core page 34.
262  *
263  * @{
264  */
265
266 /*!
267  * \brief Returns the name of the \b Node, depending on what type of 
268  * \b Node it is, in a read-only string.
269  *
270  * Refer to the table in the 
271  * DOM2-Core for a description of the node names for various interfaces.
272  *
273  * \return A constant \b DOMString of the node name.
274  */
275 EXPORT_SPEC const DOMString ixmlNode_getNodeName(
276         /*! [in] Pointer to the node to retrieve the name. */
277         IXML_Node *nodeptr);
278
279
280 /*!
281  * \brief Returns the value of the \b Node as a string.
282  *
283  * Note that this string is not a copy and modifying it will modify the value
284  * of the \b Node.
285  *
286  *  \return A \b DOMString of the \b Node value.
287  */
288 EXPORT_SPEC const DOMString ixmlNode_getNodeValue(
289         /*! [in] Pointer to the \b Node to retrieve the value. */
290         IXML_Node *nodeptr);
291
292
293 /*!
294  * \brief Assigns a new value to a \b Node.
295  *
296  * The \b newNodeValue string is duplicated and stored in the \b Node so that
297  * the original does not have to persist past this call.
298  *
299  *  \return An integer representing one of the following:
300  *      \li \c IXML_SUCCESS: The operation completed successfully.
301  *      \li \c IXML_INVALID_PARAMETER: The <b>Node *</b> is not a valid pointer.
302  *      \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists to
303  *              complete this operation.
304  */
305 EXPORT_SPEC int ixmlNode_setNodeValue(
306         /*! [in] The \b Node to which to assign a new value. */
307         IXML_Node *nodeptr, 
308         /*! [in] The new value of the \b Node. */
309         const char *newNodeValue);
310
311
312 /*!
313  * \brief Retrieves the type of a \b Node.
314  *
315  *  \return An enum IXML_NODE_TYPE representing the type of the \b Node.
316  */
317 EXPORT_SPEC unsigned short ixmlNode_getNodeType(
318         /*! [in] The \b Node from which to retrieve the type. */
319         IXML_Node *nodeptr);
320
321
322 /*!
323  * \brief Retrieves the parent \b Node for a \b Node.
324  *
325  * \return A pointer to the parent \b Node or \c NULL if the \b Node has no
326  *      parent.
327  */
328 EXPORT_SPEC IXML_Node *ixmlNode_getParentNode(
329         /*! [in] The \b Node from which to retrieve the parent. */ 
330         IXML_Node *nodeptr);
331
332
333 /*!
334  * \brief Retrieves the list of children of a \b Node in a \b NodeList 
335  * structure.
336  *
337  * If a \b Node has no children, \b ixmlNode_getChildNodes 
338  * returns a \b NodeList structure that contains no \b Nodes.
339  *
340  * \return A \b NodeList of the children of the \b Node.
341  */
342 EXPORT_SPEC IXML_NodeList *ixmlNode_getChildNodes(
343         /*! [in] The \b Node from which to retrieve the children. */
344         IXML_Node *nodeptr);
345
346
347 /*!
348  * \brief Retrieves the first child \b Node of a \b Node.
349  *
350  * \return A pointer to the first child \b Node or \c NULL if the \b Node does
351  * not have any children.
352  */
353 EXPORT_SPEC IXML_Node *ixmlNode_getFirstChild(
354         /*! [in] The \b Node from which to retrieve the first child. */ 
355         IXML_Node *nodeptr);
356
357
358 /*!
359  * \brief Retrieves the last child \b Node of a \b Node.
360  *
361  * \return A pointer to the last child \b Node or \c NULL if the \b Node does
362  * not have any children.
363  */
364 EXPORT_SPEC IXML_Node *ixmlNode_getLastChild(
365         /*! [in] The \b Node from which to retrieve the last child. */
366         IXML_Node *nodeptr);
367
368
369 /*!
370  * \brief Retrieves the sibling \b Node immediately preceding this \b Node.
371  *
372  * \return A pointer to the previous sibling \b Node or \c NULL if no such
373  * \b Node exists.
374  */
375 EXPORT_SPEC IXML_Node *ixmlNode_getPreviousSibling(
376         /*! [in] The \b Node for which to retrieve the previous sibling. */
377         IXML_Node *nodeptr);
378
379
380 /*!
381  * \brief Retrieves the sibling \b Node immediately following this \b Node.
382  *
383  *  \return A pointer to the next sibling \b Node or \c NULL if no such
384  *  \b Node exists.
385  */
386 EXPORT_SPEC IXML_Node *ixmlNode_getNextSibling(
387         /*! [in] The \b Node from which to retrieve the next sibling. */ 
388         IXML_Node *nodeptr);
389
390
391 /*!
392  * \brief Retrieves the attributes of a \b Node, if it is an \b Element node,
393  *  in a \b NamedNodeMap structure.
394  *
395  *  \return A \b NamedNodeMap of the attributes or \c NULL.
396  */
397 EXPORT_SPEC IXML_NamedNodeMap *ixmlNode_getAttributes(
398         /*! [in] The \b Node from which to retrieve the attributes. */ 
399         IXML_Node *nodeptr);
400
401
402 /*!
403  * \brief Retrieves the document object associated with this \b Node.
404  *
405  * This owner document \b Node allows other \b Nodes to be created in the
406  * context of this document.  Note that \b Document nodes do not have an
407  * owner document.
408  *
409  * \return A pointer to the owning \b Document or \c NULL, if the \b Node
410  * does not have an owner.
411  */
412 EXPORT_SPEC IXML_Document *ixmlNode_getOwnerDocument(
413         /*! [in] The \b Node from which to retrieve the owner document. */
414         IXML_Node *nodeptr);
415
416
417 /*!
418  * \brief Retrieves the namespace URI for a \b Node as a \b DOMString.
419  *
420  * Only \b Nodes of type \c eELEMENT_NODE or \c eATTRIBUTE_NODE can have a
421  * namespace URI.  \b Nodes created through the \b Document interface will
422  * only contain a namespace if created using \b ixmlDocument_createElementNS.
423  *
424  * \return A \b DOMString representing the URI of the namespace or \c NULL.
425  */
426 EXPORT_SPEC const DOMString ixmlNode_getNamespaceURI(
427         /*! [in] The \b Node for which to retrieve the namespace. */
428         IXML_Node *nodeptr);
429
430
431 /*!
432  * \brief Retrieves the namespace prefix, if present.
433  *
434  * The prefix is the name used as an alias for the namespace URI for this
435  * element.  Only \b Nodes of type \c eELEMENT_NODE or \c eATTRIBUTE_NODE can
436  * have a prefix. \b Nodes created through the \b Document interface will only
437  * contain a prefix if created using \b ixmlDocument_createElementNS.
438  *
439  *  \return A \b DOMString representing the namespace prefix or \c NULL.
440  */
441 EXPORT_SPEC const DOMString               
442 ixmlNode_getPrefix(
443         /*! The \b Node from which to retrieve the prefix. */
444         IXML_Node *nodeptr);
445
446
447 /*!
448  * \brief Retrieves the local name of a \b Node, if present.
449  *
450  * The local name is the tag name without the namespace prefix. Only \b Nodes
451  * of type \c eELEMENT_NODE or \c eATTRIBUTE_NODE can have a local name.
452  * \b Nodes created through the \b Document interface will only contain a local
453  * name if created using \b ixmlDocument_createElementNS.
454  *
455  *  \return A \b DOMString representing the local name of the \b Element or
456  *      \c NULL.
457  */
458 EXPORT_SPEC const DOMString ixmlNode_getLocalName(
459         /*! [in] The \b Node from which to retrieve the local name. */
460         IXML_Node *nodeptr);
461
462 /*! 
463  * \brief Inserts a new child \b Node before the existing child \b Node.
464  *
465  * \b refChild can be \c NULL, which inserts \b newChild at the
466  * end of the list of children.  Note that the \b Node (or \b Nodes) 
467  * in \b newChild must already be owned by the owner document (or have no
468  * owner at all) of \b nodeptr for insertion.  If not, the \b Node 
469  * (or \b Nodes) must be imported into the document using 
470  * \b ixmlDocument_importNode.  If \b newChild is already in the tree,
471  * it is removed first.
472  *
473  * \return An integer representing one of the following:
474  *     \li \c IXML_SUCCESS: The operation completed successfully.
475  *     \li \c IXML_INVALID_PARAMETER: Either \b nodeptr or 
476  *           \b newChild is \c NULL.
477  *     \li \c IXML_HIERARCHY_REQUEST_ERR: The type of the \b Node 
478  *           does not allow children of the type of \b newChild.
479  *     \li \c IXML_WRONG_DOCUMENT_ERR: \b newChild has an owner 
480  *           document that does not match the owner of \b nodeptr.
481  *     \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr is 
482  *           read-only or the parent of the \b Node being inserted is 
483  *           read-only.
484  *     \li \c IXML_NOT_FOUND_ERR: \b refChild is not a child of 
485  *           \b nodeptr.
486  */
487 EXPORT_SPEC int ixmlNode_insertBefore(
488         /*! [in] The parent of the \b Node before which to insert the new child. */
489         IXML_Node *nodeptr,   
490         /*! [in] The \b Node to insert into the tree. */
491         IXML_Node * newChild,
492         /*! [in] The reference child where the new \b Node should be inserted.
493          * The new \b Node will appear directly before the reference child. */
494         IXML_Node * refChild);
495
496
497 /*!
498  * \brief Replaces an existing child \b Node with a new child \b Node in the
499  * list of children of a \b Node.
500  *
501  * If \b newChild is already in the tree, it will first be removed.
502  * \b returnNode will contain the \b oldChild \b Node, appropriately removed
503  * from the tree (i.e. it will no longer have an owner document).
504  *
505  * \return An integer representing one of the following:
506  *      \li \c IXML_SUCCESS: The operation completed successfully.
507  *      \li \c IXML_INVALID_PARAMTER: Either \b nodeptr, \b newChild,
508  *              or \b oldChild is \c NULL.
509  *      \li \c IXML_HIERARCHY_REQUEST_ERR: The \b newChild is not 
510  *            a type of \b Node that can be inserted into this tree or 
511  *            \b newChild is an ancestor of \b nodePtr.
512  *      \li \c IXML_WRONG_DOCUMENT_ERR: \b newChild was created from 
513  *            a different document than \b nodeptr.
514  *      \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr or 
515  *            its parent is read-only.
516  *      \li \c IXML_NOT_FOUND_ERR: \b oldChild is not a child of 
517  *            \b nodeptr.
518  */
519 EXPORT_SPEC int ixmlNode_replaceChild(
520         /*! [in] The parent of the \b Node which contains the child to replace. */
521         IXML_Node *nodeptr,
522         /*! [in] The child with which to replace \b oldChild. */
523         IXML_Node *newChild,        
524         /*! [in] The child to replace with \b newChild. */
525         IXML_Node *oldChild,        
526         /*! [out] Pointer to a \b Node to place the removed \b oldChild \b Node. */
527         IXML_Node **returnNode);
528
529
530 /*!
531  * \brief Removes a child from the list of children of a \b Node.
532  *
533  * \b returnNode will contain the \b oldChild \b Node, 
534  * appropriately removed from the tree (i.e. it will no longer have an 
535  * owner document).
536  *
537  * \return An integer representing one of the following:
538  *     \li \c IXML_SUCCESS: The operation completed successfully.
539  *     \li \c IXML_INVALID_PARAMETER: Either \b nodeptr or 
540  *           \b oldChild is \c NULL.
541  *     \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr or its 
542  *           parent is read-only.
543  *     \li \c IXML_NOT_FOUND_ERR: \b oldChild is not among the 
544  *           children of \b nodeptr.
545  */
546 EXPORT_SPEC int ixmlNode_removeChild(
547         /*! [in] The parent of the child to remove. */
548         IXML_Node *nodeptr,
549         /*! [in] The child \b Node to remove. */
550         IXML_Node *oldChild,
551         /*! [out] Pointer to a \b Node to place the removed \b oldChild \b Node. */
552         IXML_Node **returnNode);
553
554
555 /*!
556  * \brief Appends a child \b Node to the list of children of a \b Node.
557  *
558  * If \b newChild is already in the tree, it is removed first.
559  *
560  * \return An integer representing one of the following:
561  *      \li \c IXML_SUCCESS: The operation completed successfully.
562  *      \li \c IXML_INVALID_PARAMETER: Either \b nodeptr or 
563  *            \b newChild is \c NULL.
564  *      \li \c IXML_HIERARCHY_REQUEST_ERR: \b newChild is of a type 
565  *            that cannot be added as a child of \b nodeptr or 
566  *            \b newChild is an ancestor of \b nodeptr.
567  *      \li \c IXML_WRONG_DOCUMENT_ERR: \b newChild was created from 
568  *            a different document than \b nodeptr.
569  *      \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr is a 
570  *            read-only \b Node.
571  */
572 EXPORT_SPEC int ixmlNode_appendChild(
573         /*! [in] The \b Node in which to append the new child. */
574         IXML_Node *nodeptr,
575         /*! [in] The new child to append. */
576         IXML_Node * newChild);
577
578
579 /*!
580  * \brief Queries whether or not a \b Node has children.
581  *
582  * \return \c TRUE if the \b Node has one or more children otherwise \c FALSE.
583  */
584 EXPORT_SPEC BOOL ixmlNode_hasChildNodes(
585         /*! [in] The \b Node to query for children. */
586         IXML_Node *nodeptr);
587
588
589 /*!
590  * \brief Clones a \b Node.
591  *
592  * The new \b Node does not have a parent. The \b deep parameter controls
593  * whether the subtree of the \b Node is also cloned.
594  *
595  * For details on cloning specific types of \b Nodes, refer to the
596  * DOM2-Core recommendation.
597  *
598  * \return A clone of \b nodeptr or \c NULL.
599  */
600 EXPORT_SPEC IXML_Node *ixmlNode_cloneNode(
601         /*! [in] The \b Node to clone.  */
602         IXML_Node *nodeptr,
603         /*! [in] \c TRUE to clone the subtree also or \c FALSE to clone only
604          * \b nodeptr. */
605         BOOL deep);
606
607
608 /*!
609  * \brief Queries whether this \b Node has attributes.
610  *
611  * Note that only \b Element nodes have attributes.
612  *
613  * \return \c TRUE if the \b Node has attributes otherwise \c FALSE.
614  */
615 EXPORT_SPEC BOOL ixmlNode_hasAttributes(
616         /*! [in] The \b Node to query for attributes. */
617         IXML_Node *nodeptr);
618
619
620 /*!
621  * \brief Frees a \b Node and all \b Nodes in its subtree.
622  */
623 EXPORT_SPEC void ixmlNode_free(
624         /*! [in] The \b Node tree to free. */
625         IXML_Node *nodeptr);
626
627 /* @} Interface Node */
628
629
630
631 /*!
632  * \name Interface Attr
633  *
634  * The \b Attr interface represents an attribute of an \b Element. The document
635  * type definition (DTD) or schema usually dictate the allowable attributes and
636  * values for a particular element.
637  *
638  * For more information, refer to the <em>Interface Attr</em> section in the
639  * DOM2-Core.
640  *
641  * @{
642  */
643
644
645 /*!
646  * \brief Frees an \b Attr node.
647  */
648 EXPORT_SPEC void ixmlAttr_free(
649         /*! The \b Attr node to free. */
650         IXML_Attr *attrNode);
651
652
653 /* @} Interface Attr */
654
655
656
657 /*!
658  * \name Interface CDATASection
659  *
660  * The \b CDATASection is used to escape blocks of text containing
661  * characters that would otherwise be regarded as markup. CDATA sections
662  * cannot be nested. Their primary purpose is for including material such
663  * XML fragments, without needing to escape all the delimiters.
664  *
665  * For more information, refer to the <em>Interface CDATASection</em> section
666  * in the DOM2-Core.
667  *
668  * @{
669  */
670
671
672 /*!
673  * \brief Initializes a \b CDATASection node.
674  */
675 EXPORT_SPEC void ixmlCDATASection_init(
676         /*! [in] The <b>CDATA Section Node</b> to iniatialize. */
677         IXML_CDATASection *nodeptr);
678
679
680 /*!
681  * \brief Frees a \b CDATASection node.
682  */
683 EXPORT_SPEC void ixmlCDATASection_free(
684         /*! The \b CDATASection node to free. */
685         IXML_CDATASection *nodeptr);
686
687
688 /* @} Interface CDATASection */
689
690
691
692 /*!
693  * \name Interface Document
694  *
695  * The \b Document interface represents the entire XML document. In essence, it
696  * is the root of the document tree and provides the primary interface to the
697  * elements of the document.
698  *
699  * For more information, refer to the <em>Interface Document</em> section in
700  * the DOM2Core.
701  *
702  * @{
703  */
704
705
706 /*!
707  * \brief Initializes a \b Document node.
708  */
709 EXPORT_SPEC void ixmlDocument_init(
710         /*! [in] The \b Document node to initialize.  */
711         IXML_Document *nodeptr);
712
713
714 /*!
715  * \brief Creates a new empty \b Document node.
716  *
717  * The \b ixmlDocument_createDocumentEx API differs from the
718  * \b ixmlDocument_createDocument API in that it returns an error code
719  * describing the reason for the failure rather than just \c NULL.
720  *
721  * \return An integer representing one of the following:
722  *      \li \c IXML_SUCCESS: The operation completed successfully.
723  *      \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
724  *            to complete this operation.
725  */
726 EXPORT_SPEC int ixmlDocument_createDocumentEx(
727         /*! [out] Pointer to a \b Document where the new object will be stored. */
728         IXML_Document **doc);
729
730
731 /*!
732  * \brief Creates a new empty \b Document node.
733  *
734  * \return A pointer to the new \b Document object with the nodeName set to
735  *      "#document" or \c NULL on failure.
736  */
737 EXPORT_SPEC IXML_Document *ixmlDocument_createDocument();
738
739
740 /*!
741  * \brief Creates a new \b Element node with the given tag name.
742  *
743  * The new \b Element node has a \c nodeName of \b tagName and the
744  * \c localName, \c prefix, and \c namespaceURI set to \c NULL.  To create an
745  * \b Element with a namespace, see \b ixmlDocument_createElementNS.
746  *
747  * The \b ixmlDocument_createElementEx API differs from the \b
748  * ixmlDocument_createElement API in that it returns an error code
749  * describing the reason for failure rather than just \c NULL.
750  *
751  * \return An integer representing one of the following:
752  *     \li \c IXML_SUCCESS: The operation completed successfully.
753  *     \li \c IXML_INVALID_PARAMETER: Either \b doc or 
754  *           \b tagName is \c NULL.
755  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
756  *           to complete this operation.
757  */
758 EXPORT_SPEC int ixmlDocument_createElementEx(
759         /*! [in] The owner \b Document of the new node. */
760         IXML_Document *doc,
761         /*! [in] The tag name of the new \b Element node. */
762         const DOMString tagName,  
763         /*! [out] Pointer to an \b Element where the new object will be stored. */
764         IXML_Element **rtElement);
765
766
767 /*!
768  * \brief Creates a new \b Element node with the given tag name.
769  *
770  * The new \b Element node has a \c nodeName of \b tagName and the
771  * \c localName, \c prefix, and \c namespaceURI set to \c NULL. To create an
772  * \b Element with a namespace, see \b ixmlDocument_createElementNS.
773  *
774  *  \return A pointer to the new \b Element object with  the node name set to
775  *  tagName, and localName, prefix and namespaceURI set to \c NULL, or \c NULL
776  *  on failure.
777  */
778 EXPORT_SPEC IXML_Element *ixmlDocument_createElement(
779         /*! [in] The owner \b Document of the new node. */
780         IXML_Document *doc,
781         /*! [in] The tag name of the new \b Element node (case-sensitive). */
782         const DOMString tagName);
783
784
785 /*!
786  * \brief Creates a new \b Text node with the given data.
787  * 
788  * The \b ixmlDocument_createTextNodeEx() API differs from the
789  * \b ixmlDocument_createTextNode API in that it returns an error code
790  * describing the reason for failure rather than just \c NULL.
791  *
792  * \return An integer representing one of the following:
793  *     \li \c IXML_SUCCESS: The operation completed successfully.
794  *     \li \c IXML_INVALID_PARAMETER: Either \b doc or \b data 
795  *           is \c NULL.
796  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
797  *           to complete this operation.
798  */
799 EXPORT_SPEC int ixmlDocument_createTextNodeEx(
800         /*! [in] The owner \b Document of the new node. */
801         IXML_Document *doc,
802         /*! [in] The data to associate with the new \b Text node.
803          * It is stored in nodeValue field.*/
804         const DOMString data,      
805         /*! [out] A pointer to a \b Node where the new object will be stored. */
806         IXML_Node **textNode);
807
808
809 /*!
810  * \brief Creates a new \b Text node with the given data.
811  *
812  * \return A pointer to the new \b Node or \c NULL on failure.
813  */
814 EXPORT_SPEC IXML_Node *ixmlDocument_createTextNode(
815         /*! [in] The owner \b Document of the new node. */
816         IXML_Document *doc,
817         /*! [in] The data to associate with the new \b Text node. It is stored in
818          * the nodeValue field. */
819         const DOMString data);
820
821
822 /*!
823  * \brief Creates a new \b CDATASection node with given data.
824  *
825  * The \b ixmlDocument_createCDATASectionEx API differs from the \b
826  * ixmlDocument_createCDATASection API in that it returns an error code
827  * describing the reason for failure rather than just \c NULL.
828  *
829  * \return An integer representing one of the following:
830  *     \li \c IXML_SUCCESS: The operation completed successfully.
831  *     \li \c IXML_INVALID_PARAMETER: Either \b doc or \b data 
832  *           is \c NULL.
833  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
834  *           to complete this operation.
835  */
836 EXPORT_SPEC int ixmlDocument_createCDATASectionEx(
837         /*! [in] The owner \b Document of the new node. */
838         IXML_Document *doc,
839         /*! [in] The data to associate with the new \b CDATASection node. */
840         const DOMString data,      
841         /*! [out] A pointer to a \b Node where the new object will be stored. */ 
842         IXML_CDATASection** cdNode);
843
844
845 /*!
846  * \brief Creates a new \b CDATASection node with given data.
847  *
848  * \return A pointer to the new \b CDATASection or \c NULL on failure.
849  */
850 EXPORT_SPEC IXML_CDATASection *ixmlDocument_createCDATASection(
851         /*! [in] The owner \b Document of the new node. */
852         IXML_Document *doc,
853         /*! [in] The data to associate with the new \b CDATASection node. */
854         const DOMString data);
855
856
857 /*!
858  * \brief Creates a new \b Attr node with the given name.  
859  *
860  * \return A pointer to the new \b Attr object with the nodeName attribute
861  * set to the given name, and the localName, prefix and namespaceURI set
862  * to NULL or \c NULL on failure.
863  *
864  * The value of the attribute is the empty string.
865  */
866 EXPORT_SPEC IXML_Attr *ixmlDocument_createAttribute(
867         /*! [in] The owner \b Document of the new node. */
868         IXML_Document *doc,  
869         /*! [in] The name of the new attribute. */
870         const char *name);
871
872
873 /*!
874  * \brief Creates a new \b Attr node with the given name.  
875  *
876  * The \b ixmlDocument_createAttributeEx API differs from the \b
877  * ixmlDocument_createAttribute API in that it returns an error code
878  * describing the reason for failure rather than just \c NULL.
879  *
880  * \return An integer representing one of the following:
881  *     \li \c IXML_SUCCESS: The operation completed successfully.
882  *     \li \c IXML_INVALID_PARAMETER: Either \b doc or \b name 
883  *           is \c NULL.
884  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
885  *           to complete this operation.
886  */
887 EXPORT_SPEC int ixmlDocument_createAttributeEx(
888         /*! [in] The owner \b Document of the new node. */
889         IXML_Document *doc,
890         /*! [in] The name of the new attribute. */
891         const char *name,      
892         /*! [out] A pointer to a \b Attr where the new object will be stored. */
893         IXML_Attr **attrNode);
894
895
896 /*!
897  * \brief Returns a \b NodeList of all \b Elements that match the given
898  * tag name in the order in which they were encountered in a preorder
899  * traversal of the \b Document tree.  
900  *
901  * \return A pointer to a \b NodeList containing the matching items or \c NULL
902  * on an error.
903  */
904 EXPORT_SPEC IXML_NodeList *ixmlDocument_getElementsByTagName(
905         /*! [in] The \b Document to search. */
906         IXML_Document *doc,
907         /*! [in] The tag name to find. The special value "*" matches all tags.*/
908         const DOMString tagName);
909
910
911 /*
912  * introduced in DOM level 2
913  */
914
915
916 /*!
917  * \brief Creates a new \b Element node in the given qualified name and
918  * namespace URI.
919  *
920  * The \b ixmlDocument_createElementNSEx API differs from the \b
921  * ixmlDocument_createElementNS API in that it returns an error code
922  * describing the reason for failure rather than just \c NULL.
923  *
924  * \return An integer representing one of the following:
925  *     \li \c IXML_SUCCESS: The operation completed successfully.
926  *     \li \c IXML_INVALID_PARAMETER: Either \b doc, 
927  *           \b namespaceURI, or \b qualifiedName is \c NULL.
928  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
929  *           to complete this operation.
930  */
931 EXPORT_SPEC int ixmlDocument_createElementNSEx(
932         /*! [in] The owner \b Document of the new node. */
933         IXML_Document *doc,
934         /*! [in] The namespace URI for the new \b Element. */
935         const DOMString namespaceURI,
936         /*! [in] The qualified name of the new \b Element. */
937         const DOMString qualifiedName,
938         /*! [out] A pointer to an \b Element where the new object will be stored. */
939         IXML_Element **rtElement);
940
941
942 /*!
943  * \brief Creates a new \b Element node in the given qualified name and
944  * namespace URI.
945  *
946  * \return A pointer to the new \b Element object with tagName qualifiedName,
947  * prefix and localName extraced from qualfiedName, nodeName of qualfiedName,
948  * namespaceURI of namespaceURI or \c NULL on failure.
949  */
950 EXPORT_SPEC IXML_Element *ixmlDocument_createElementNS(
951         /*! [in] The owner \b Document of the new node. */
952         IXML_Document *doc,
953         /*! [in] The namespace URI for the new \b Element. */
954         const DOMString namespaceURI,  
955         /*! [in] The qualified name of the new \b Element. */
956         const DOMString qualifiedName);
957
958
959 /*!
960  * \brief Creates a new \b Attr node with the given qualified name and
961  * namespace URI.
962  *
963  * The \b ixmlDocument_createAttributeNSEx API differs from the \b
964  * ixmlDocument_createAttributeNS API in that it returns an error code
965  * describing the reason for failure rather than just \c NULL.
966  *
967  * \return An integer representing one of the following:
968  *     \li \c IXML_SUCCESS: The operation completed successfully.
969  *     \li \c IXML_INVALID_PARAMETER: Either \b doc, 
970  *           \b namespaceURI, or \b qualifiedName is \c NULL.
971  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
972  *           to complete this operation.
973  */
974 EXPORT_SPEC int ixmlDocument_createAttributeNSEx(
975         /*! [in] The owner \b Document of the new \b Attr. */
976         IXML_Document *doc,
977         /*! [in] The namespace URI for the attribute. */
978         const DOMString namespaceURI, 
979         /*! [in] The qualified name of the attribute. */
980         const DOMString qualifiedName, 
981         /*! [out] A pointer to an \b Attr where the new object will be stored. */
982         IXML_Attr **attrNode);
983
984
985 /*!
986  * \brief Creates a new \b Attribute node with the given qualified name and
987  * namespace URI.
988  *
989  * \return A pointer to the new \b Attr node with the given namespaceURI and
990  *      qualifiedName. The prefix and localname are extracted from
991  *      the qualifiedName. The node value is empty. Or \c NULL on failure.
992  */
993 EXPORT_SPEC IXML_Attr *ixmlDocument_createAttributeNS(
994         /*! [in] The owner \b Document of the new \b Attribute. */
995         IXML_Document *doc,
996         /*! [in] The namespace URI for the attribute. */
997         const DOMString namespaceURI, 
998         /*! [in] The qualified name of the attribute. */
999         const DOMString qualifiedName);   
1000
1001
1002 /*!
1003  * \brief Returns a \b NodeList of \b Elements that match the given
1004  * local name and namespace URI in the order they are encountered
1005  * in a preorder traversal of the \b Document tree.
1006  *
1007  * Either \b namespaceURI or \b localName can be the special <tt>"*"</tt>
1008  * character, which matches any namespace or any local name respectively.
1009  *
1010  * \return A pointer to a \b NodeList containing the matching items or \c NULL
1011  * on an error.
1012  */
1013 EXPORT_SPEC IXML_NodeList *ixmlDocument_getElementsByTagNameNS(
1014         /*! [in] The \b Document to search. */
1015         IXML_Document *doc,
1016         /*! [in] The namespace of the elements to find or <tt>"*"</tt> to match any
1017          * namespace. */
1018         const DOMString namespaceURI, 
1019         /*! [in] The local name of the elements to find or <tt>"*"</tt> to match any
1020          * local name. */
1021         const DOMString localName);
1022
1023
1024 /*!
1025  * \brief Returns the \b Element whose \c ID matches that given id.
1026  *
1027  * \return A pointer to the matching \b Element or \c NULL on an error.
1028  */
1029 EXPORT_SPEC IXML_Element *ixmlDocument_getElementById(
1030         /*! [in] The owner \b Document of the \b Element. */
1031         IXML_Document *doc,
1032         /*! [in] The name of the \b Element.*/
1033         const DOMString tagName);
1034
1035
1036 /*!
1037  * \brief Frees a \b Document object and all \b Nodes associated with it.
1038  *
1039  * Any \b Nodes extracted via any other interface function, e.g. 
1040  * \b ixmlDocument_GetElementById, become invalid after this call unless
1041  * explicitly cloned.
1042  */
1043 EXPORT_SPEC void ixmlDocument_free(
1044         /*! [in] The \b Document to free. */
1045         IXML_Document *doc);
1046
1047
1048 /*!
1049  * \brief Imports a \b Node from another \b Document into this \b Document.
1050  *
1051  * The returned new \b Node does not a have parent node (parentNode is null):
1052  * it is a clone of the original \b Node with the \c ownerDocument set to
1053  * \b doc. The source node is not altered or removed from the original 
1054  * document.
1055  *
1056  * For all nodes, importing a node creates a node object owned by the
1057  * importing document, with attribute values identical to the source
1058  * node's nodeName and nodeType, plus the attributes related to namespaces
1059  * (prefix, localName, and namespaceURI).
1060  *
1061  * As in the cloneNode operation on a node, the source node is not altered.
1062  * 
1063  * The \b deep parameter controls whether all the children of the \b Node are
1064  * imported.
1065  *
1066  * Refer to the DOM2-Core recommendation for details on importing specific
1067  * node types.
1068  *
1069  * \return An integer representing one of the following:
1070  *     \li \c IXML_SUCCESS: The operation completed successfully.
1071  *     \li \c IXML_INVALID_PARAMETER: Either \b doc or 
1072  *           \b importNode is not a valid pointer.
1073  *     \li \c IXML_NOT_SUPPORTED_ERR: \b importNode is a 
1074  *           \b Document, which cannot be imported.
1075  *     \li \c IXML_FAILED: The import operation failed because the 
1076  *           \b Node to be imported could not be cloned.
1077  */
1078 EXPORT_SPEC int ixmlDocument_importNode(
1079         /*! [in] The \b Document into which to import. */
1080         IXML_Document *doc,
1081         /*! [in] The \b Node to import. */
1082         IXML_Node * importNode,  
1083         /*! [in] \c TRUE to import all children of \b importNode or \c FALSE to
1084          * import only the root node. */
1085         BOOL deep,         
1086         /*! [out] A pointer to a new \b Node owned by \b doc. */
1087         IXML_Node **rtNode);
1088
1089
1090 /* @} Interface Document */
1091
1092
1093
1094
1095 /*!
1096  * \name Interface Element
1097  *
1098  * The \b Element interface represents an element in an XML document.
1099  * Only \b Elements are allowed to have attributes, which are stored in the
1100  * \c attributes member of a \b Node.  The \b Element interface
1101  * extends the \b Node interface and adds more operations to manipulate
1102  * attributes.
1103  *
1104  * @{
1105  */
1106
1107
1108 /*!
1109  * \brief Initializes a \b IXML_Element node.
1110  */
1111 EXPORT_SPEC void ixmlElement_init(
1112         /*! [in] The \b Element to initialize.*/
1113         IXML_Element *element);
1114
1115
1116 /*!
1117  * \brief Returns the name of the tag as a constant string.
1118  *
1119  * \return The name of the \b Element.
1120  */
1121 EXPORT_SPEC const DOMString ixmlElement_getTagName(
1122         /*! [in] The \b Element from which to retrieve the name. */
1123         IXML_Element *element);
1124
1125
1126 /*!
1127  * \brief Retrieves an attribute of an \b Element by name.  
1128  *
1129  * \return The value of the attribute, or \b NULL if that attribute
1130 *       does not have a specified value.
1131  */
1132 EXPORT_SPEC const DOMString ixmlElement_getAttribute(
1133         /*! [in] The \b Element from which to retrieve the attribute. */
1134         IXML_Element* element,  
1135         /*! [in] The name of the attribute to retrieve. */
1136         const DOMString name);
1137
1138
1139 /*!
1140  * \brief Adds a new attribute to an \b Element.
1141  *
1142  * If an attribute with the same name already exists in the element, the
1143  * attribute value will be updated with the new value parameter. Otherwise,
1144  * a new attribute is inserted into the element.
1145  *
1146  * \return An integer representing of the following:
1147  *     \li \c IXML_SUCCESS: The operation completed successfully.
1148  *     \li \c IXML_INVALID_PARAMETER: Either \b element, 
1149  *           \b name, or \b value is \c NULL.
1150  *     \li \c IXML_INVALID_CHARACTER_ERR: \b name contains an 
1151  *           illegal character.
1152  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
1153  *           to complete the operation.
1154  */
1155 EXPORT_SPEC int ixmlElement_setAttribute(
1156         /*! [in] The \b Element on which to set the attribute. */
1157         IXML_Element *element,
1158         /*! [in] The name of the attribute. */
1159         const DOMString name,    
1160         /*! [in] The value of the attribute. Note that this is a non-parsed string
1161          * and any markup must be escaped. */
1162         const DOMString value);
1163
1164
1165 /*!
1166  * \brief Removes an attribute value by name. The attribute node is not removed.
1167  *
1168  * \return An integer representing one of the following:
1169  *     \li \c IXML_SUCCESS: The operation completed successfully.
1170  *     \li \c IXML_INVALID_PARAMETER: Either \b element or 
1171  *           \b name is \c NULL.
1172  */
1173 EXPORT_SPEC int ixmlElement_removeAttribute(
1174         /*! [in] The \b Element from which to remove the attribute. */
1175         IXML_Element *element,
1176         /*! [in] The name of the attribute to remove.  */
1177         const DOMString name);              
1178
1179
1180 /*!
1181  * \brief Retrieves an attribute node by name.
1182  * See \b ixmlElement_getAttributeNodeNS to retrieve an attribute node using
1183  * a qualified name or namespace URI.
1184  *
1185  * \return A pointer to the attribute matching \b name or \c NULL on if there
1186  *      is no such attribute.
1187  */
1188 EXPORT_SPEC IXML_Attr *ixmlElement_getAttributeNode(
1189         /*! [in] The \b Element from which to get the attribute node.  */
1190         IXML_Element *element,
1191         /*! [in] The name of the attribute node to find. */
1192         const DOMString name);
1193
1194
1195 /*!
1196  * \brief Adds a new attribute node to an \b Element.
1197  *
1198  * If an attribute already exists with \b newAttr as a name, it will be
1199  * replaced with the new one and the old one will be returned in \b rtAttr.
1200  *
1201  * \return If successfull, the replaced attribute node is returned in rtAttr,
1202  * otherwise, \b NULL is returned in this pointer. The function return value
1203  * is an integer representing one of the following:
1204  *     \li \c IXML_SUCCESS: The operation completed successfully.
1205  *     \li \c IXML_INVALID_PARAMETER: Either \b element or 
1206  *           \b newAttr is \c NULL.
1207  *     \li \c IXML_WRONG_DOCUMENT_ERR: \b newAttr does not belong 
1208  *           to the same one as \b element.
1209  *     \li \c IXML_INUSE_ATTRIBUTE_ERR: \b newAttr is already 
1210  *           an attribute of another \b Element.
1211  */
1212 EXPORT_SPEC int ixmlElement_setAttributeNode(
1213         /*! [in] The \b Element in which to add the new attribute. */
1214         IXML_Element *element,
1215         /*! [in] The new \b Attr to add. */
1216         IXML_Attr* newAttr,     
1217         /*! [out] A pointer to an \b Attr where the old \b Attr will be stored.
1218          * This will have a \c NULL if no prior node existed. */
1219         IXML_Attr** rtAttr);
1220
1221
1222 /*!
1223  * \brief Removes the specified attribute node from an \b Element.  
1224  *
1225  * \return An integer representing one of the following:
1226  *     \li \c IXML_SUCCESS: The operation completed successfully.
1227  *     \li \c IXML_INVALID_PARAMETER: Either \b element or 
1228  *           \b oldAttr is \c NULL.
1229  *     \li \c IXML_NOT_FOUND_ERR: \b oldAttr is not among the list 
1230  *           attributes of \b element.
1231  */
1232 EXPORT_SPEC int ixmlElement_removeAttributeNode(
1233         /*! [in] The \b Element from which to remove the attribute. */
1234         IXML_Element *element,
1235         /*! [in] The attribute to remove from the \b Element. */
1236         IXML_Attr* oldAttr,     
1237         /*! [out] A pointer to an attribute in which to place the removed attribute. */
1238         IXML_Attr** rtAttr);
1239
1240
1241 /*!
1242  * \brief Returns a \b NodeList of all \em descendant \b Elements with
1243  * a given tag name, in the order in which they are encountered in a
1244  * pre-order traversal of this \b Element tree.
1245  *
1246  * \return A \b NodeList of the matching \b Elements or \c NULL on an error.
1247  */
1248 EXPORT_SPEC IXML_NodeList *ixmlElement_getElementsByTagName(
1249         /*! [in] The \b Element from which to start the search. */
1250         IXML_Element *element,
1251         /*! [in] The name of the tag for which to search. */
1252         const DOMString tagName);
1253
1254
1255 /*
1256  * Introduced in DOM 2
1257  */
1258
1259
1260 /*!
1261  * \brief Retrieves an attribute value using the local name and namespace URI.
1262  *
1263  * \return A \b DOMString representing the value of the matching attribute, or
1264  * \b NULL if that attribute does not have the specified value.
1265  */
1266 EXPORT_SPEC const DOMString ixmlElement_getAttributeNS(
1267         /*! [in] The \b Element from which to get the attribute value. */
1268         IXML_Element *element,
1269         /*! [in] The namespace URI of the attribute. */
1270         const DOMString namespaceURI, 
1271         /*! [in] The local name of the attribute. */
1272         const DOMString localname);
1273
1274
1275 /*!
1276  * \brief Adds a new attribute to an \b Element using the local name and 
1277  * namespace URI.
1278  *
1279  * If another attribute matches the same local name and namespace, the prefix
1280  * is changed to be the prefix part of the \c qualifiedName and the value is
1281  * changed to \b value.
1282  *
1283  * \return An integer representing one of the following:
1284  *     \li \c IXML_SUCCESS: The operation completed successfully.
1285  *     \li \c IXML_INVALID_PARAMETER: Either \b element, 
1286  *           \b namespaceURI, \b qualifiedName, or \b value is 
1287  *           \c NULL.
1288  *     \li \c IXML_INVALID_CHARACTER_ERR: \b qualifiedName contains 
1289  *           an invalid character.
1290  *     \li \c IXML_NAMESPACE_ERR: Either the \b qualifiedName or 
1291  *           \b namespaceURI is malformed.  Refer to the DOM2-Core for 
1292  *           possible reasons.
1293  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exist 
1294  *           to complete the operation.
1295  *     \li \c IXML_FAILED: The operation could not be completed.
1296  */
1297 EXPORT_SPEC int ixmlElement_setAttributeNS(
1298         /*! [in] The \b Element on which to set the attribute. */
1299         IXML_Element *element,
1300         /*! [in] The namespace URI of the new attribute. */
1301         const DOMString namespaceURI,   
1302         /*! [in] The qualified name of the attribute. */
1303         const DOMString qualifiedName,  
1304         /*! [in] The new value for the attribute. */
1305         const DOMString value);
1306
1307
1308 /*!
1309  * \brief Removes an attribute using the namespace URI and local name.
1310  *
1311  * The replacing attribute has the same namespace URI and local name, as well
1312  * as the original prefix.
1313  * 
1314  * \return An integer representing one of the following:
1315  *     \li \c IXML_SUCCESS: The operation completed successfully.
1316  *     \li \c IXML_INVALID_PARAMETER: Either \b element, 
1317  *           \b namespaceURI, or \b localName is \c NULL.
1318  */
1319 EXPORT_SPEC int ixmlElement_removeAttributeNS(
1320         /*! [in] The \b Element from which to remove the the attribute. */
1321         IXML_Element *element,
1322         /*! [in] The namespace URI of the attribute. */
1323         const DOMString namespaceURI,  
1324         /*! [in] The local name of the attribute.*/
1325         const DOMString localName);
1326
1327
1328 /*!
1329  * \brief Retrieves an \b Attr node by local name and namespace URI.
1330  *
1331  * \return A pointer to an \b Attribute node  with the specified attribute
1332  *      local name and namespace URI or \c NULL if there is no such attribute.
1333  */
1334 EXPORT_SPEC IXML_Attr *ixmlElement_getAttributeNodeNS(
1335         /*! [in] The \b Element from which to get the attribute. */
1336         IXML_Element *element,
1337         /*! [in] The namespace URI of the attribute. */
1338         const DOMString namespaceURI,  
1339         /*! [in] The local name of the attribute. */
1340         const DOMString localName);
1341
1342
1343 /*!
1344  * \brief Adds a new attribute node to the element node specified.
1345  *
1346  * If an attribute with the same local name and namespace URI already exists in
1347  * the \b Element, the existing attribute node is replaced with \b newAttr and
1348  * the old returned in \b rcAttr.
1349  *
1350  * \return The output parameter rcAttr receives the replaced attribute node if
1351  * the newAttr attribute replaces an existing attribute with the same local name
1352  * and namespace, otherwise rcAttr receives \b NULL.
1353  *
1354  * The function return value is an integer representing one of the following:
1355  *     \li \c IXML_SUCCESS: The operation completed successfully.
1356  *     \li \c IXML_INVALID_PARAMETER: Either \b element or 
1357  *           \b newAttr is \c NULL.
1358  *     \li \c IXML_WRONG_DOCUMENT_ERR: \b newAttr does not belong 
1359  *           to the same document as \b element.
1360  *     \li \c IXML_INUSE_ATTRIBUTE_ERR: \b newAttr already is an 
1361  *           attribute of another \b Element.
1362  */
1363 EXPORT_SPEC int ixmlElement_setAttributeNodeNS(
1364         /*! [in] The \b Element in which to add the attribute node. */
1365         IXML_Element *element,
1366         /*! [in] The new \b Attr to add. */
1367         IXML_Attr *newAttr,     
1368         /*! [out] A pointer to the replaced \b Attr, if it exists. */
1369         IXML_Attr **rcAttr);
1370
1371
1372 /*!
1373  * \brief Returns a \b NodeList of all \em descendant \b Elements with a
1374  * given local name and namespace in the order in which they are encountered in
1375  * the pre-order traversal of the \b Element tree.
1376  *
1377  * \return A \b NodeList of matching \b Elements or \c NULL on an error.
1378  */
1379 EXPORT_SPEC IXML_NodeList *ixmlElement_getElementsByTagNameNS(
1380         /*! [in] The \b Element from which to start the search. */
1381         IXML_Element *element,
1382         /*! [in] The namespace URI of the \b Elements to find.  The special value
1383          * "*" matches all namespaces. */
1384         const DOMString namespaceURI,
1385         /*! [in] The local name of the \b Elements to find. The special value "*"
1386          * matches all local names. */
1387         const DOMString localName);
1388
1389
1390 /*!
1391  * \brief Queries whether the \b Element has an attribute with the given name
1392  * or a default value.
1393  *
1394  * \return \c TRUE if the \b Element has an attribute with this name or has a
1395  * default value for that attribute, otherwise \c FALSE.
1396  */
1397 EXPORT_SPEC BOOL ixmlElement_hasAttribute(
1398         /*! [in] The \b Element on which to check for an attribute. */
1399         IXML_Element *element,
1400         /*! [in] The name of the attribute for which to check. */
1401         const DOMString name);
1402
1403
1404 /*!
1405  * \brief Queries whether the \b Element has an attribute with the given
1406  * local name and namespace URI or has a default value for that attribute.
1407  *
1408  * \return \c TRUE if the \b Element has an attribute with the given namespace
1409  * and local name or has a default value for that attribute, otherwise \c FALSE.
1410  */
1411 EXPORT_SPEC BOOL ixmlElement_hasAttributeNS(
1412         /*! [in] The \b Element on which to check for the attribute. */
1413         IXML_Element *element,
1414         /*! [in] The namespace URI of the attribute. */
1415         const DOMString namespaceURI, 
1416         /*! [in] The local name of the attribute. */
1417         const DOMString localName);
1418
1419
1420 /*!
1421  * \brief Frees the given \b Element and any subtree of the \b Element.
1422  */
1423 EXPORT_SPEC void ixmlElement_free(
1424         /*! [in] The \b Element to free. */
1425         IXML_Element *element);
1426
1427
1428 /* @} Interface Element */
1429
1430
1431
1432 /*!
1433  * \name Interface NamedNodeMap
1434  *
1435  * A \b NamedNodeMap object represents a list of objects that can be
1436  * accessed by name.  A \b NamedNodeMap maintains the objects in 
1437  * no particular order.  The \b Node interface uses a \b NamedNodeMap
1438  * to maintain the attributes of a node.
1439  *
1440  * @{
1441  */
1442
1443
1444 /*!
1445  * \brief Returns the number of items contained in this \b NamedNodeMap.
1446  *
1447  * \return The number of nodes in this map.
1448  */
1449 EXPORT_SPEC unsigned long ixmlNamedNodeMap_getLength(
1450         /*! [in] The \b NamedNodeMap from which to retrieve the size. */
1451         IXML_NamedNodeMap *nnMap);
1452
1453
1454 /*!
1455  * \brief Retrieves a \b Node from the \b NamedNodeMap by name.
1456  *
1457  * \return A Node with the specified nodeName, or \b NULL if it
1458  *      does not identify any node in this map.
1459  */
1460 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_getNamedItem(
1461         /*! [in] The \b NamedNodeMap to search. */
1462         IXML_NamedNodeMap *nnMap,
1463         /*! [in] The name of the \b Node to find. */
1464         const DOMString name);
1465
1466
1467 /*!
1468  * \brief Adds a new \b Node to the \b NamedNodeMap using the \b Node name
1469  * attribute.
1470  *
1471  * \return The old \b Node if the new \b Node replaces it or \c NULL if the
1472  * \b Node was not in the \b NamedNodeMap before.
1473  */
1474 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_setNamedItem(
1475         /*! The \b NamedNodeMap in which to add the new \b Node. */
1476         IXML_NamedNodeMap *nnMap,
1477         /*! The new \b Node to add to the \b NamedNodeMap. */
1478         IXML_Node *arg);
1479
1480
1481 /*!
1482  * \brief Removes a \b Node from a \b NamedNodeMap specified by name.
1483  *
1484  * \return A pointer to the \b Node, if found, or \c NULL if it wasn't.
1485  */
1486 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_removeNamedItem(
1487         /*! The \b NamedNodeMap from which to remove the item. */
1488         IXML_NamedNodeMap *nnMap,
1489         /*! The name of the item to remove. */
1490         const DOMString name);
1491
1492
1493 /*!
1494  * \brief Retrieves the indexth item in the map. If index is greater than or
1495  * equal to the number of nodes in this map, this returns \b NULL.
1496  *
1497  * \return The node at the indexth position in the map, or \b NULL if that is
1498  *      not a valid index.
1499  */
1500 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_item(
1501         /*! [in] The \b NamedNodeMap from which to remove the \b Node. */
1502         IXML_NamedNodeMap *nnMap,
1503         /*! [in] The index into the map to remove. */
1504         unsigned long index);
1505
1506
1507 /*
1508  * Introduced in DOM level 2
1509  */
1510
1511
1512 /*!
1513  * \brief Retrieves a \b Node from a \b NamedNodeMap specified by namespace
1514  * URI and local name.
1515  *
1516  * \return A pointer to the \b Node, if found, or \c NULL if it wasn't
1517  */
1518 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_getNamedItemNS(
1519         /*! The \b NamedNodeMap from which to remove the \b Node. */
1520         IXML_NamedNodeMap *nnMap,
1521         /*! The namespace URI of the \b Node to remove. */
1522         const DOMString *namespaceURI,
1523         /*! The local name of the \b Node to remove. */
1524         const DOMString localName);
1525
1526
1527 /*!
1528  * \brief Adds a new \b Node to the \b NamedNodeMap using the \b Node 
1529  * local name and namespace URI attributes.
1530  *
1531  * \return The old \b Node if the new \b Node replaces it or \c NULL if the
1532  * \b Node was not in the \b NamedNodeMap before.
1533  */
1534 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_setNamedItemNS(
1535         /*! The \b NamedNodeMap in which to add the \b Node. */
1536         IXML_NamedNodeMap *nnMap,
1537         /*! The \b Node to add to the map. */
1538         IXML_Node *arg);
1539
1540
1541 /*!
1542  * \brief Removes a \b Node from a \b NamedNodeMap specified by 
1543  * namespace URI and local name.
1544  *
1545  * \return A pointer to the \b Node, if found, or \c NULL if it wasn't.
1546  */
1547 EXPORT_SPEC IXML_Node *ixmlNamedNodeMap_removeNamedItemNS(
1548         /*! The \b NamedNodeMap from which to remove the \b Node. */
1549         IXML_NamedNodeMap *nnMap,
1550         /*! The namespace URI of the \b Node to remove. */
1551         const DOMString namespaceURI, 
1552         /*! The local name of the \b Node to remove. */
1553         const DOMString localName);
1554
1555
1556 /*! \brief Frees a \b NamedNodeMap.
1557  *
1558  * The \b Nodes inside the map are not freed, just the \b NamedNodeMap object.
1559  */
1560 EXPORT_SPEC void ixmlNamedNodeMap_free(
1561         /*! [in] The \b NamedNodeMap to free. */
1562         IXML_NamedNodeMap *nnMap);
1563
1564
1565 /* @} Interface NodeMap */
1566
1567
1568
1569 /*!
1570  * \name Interface NodeList
1571  *
1572  * The \b NodeList interface abstracts an ordered collection of
1573  * nodes.  Note that changes to the underlying nodes will change
1574  * the nodes contained in a \b NodeList.  The DOM2-Core refers to
1575  * this as being \em live.
1576  *
1577  * @{
1578  */
1579
1580
1581 /*!
1582  * \brief Retrieves a \b Node from a \b NodeList specified by a 
1583  * numerical index.
1584  *
1585  * \return A pointer to a \b Node or \c NULL if there was an error.
1586  */
1587 EXPORT_SPEC IXML_Node *ixmlNodeList_item(
1588         /*! [in] The \b NodeList from which to retrieve the \b Node. */
1589         IXML_NodeList *nList,
1590         /*! [in] The index into the \b NodeList to retrieve. */
1591         unsigned long index);
1592
1593
1594 /*!
1595  * \brief Returns the number of \b Nodes in a \b NodeList.
1596  *
1597  * \return The number of \b Nodes in the \b NodeList.
1598  */
1599 EXPORT_SPEC unsigned long ixmlNodeList_length(
1600         /*! [in] The \b NodeList for which to retrieve the number of \b Nodes. */
1601         IXML_NodeList *nList);
1602
1603
1604 /*!
1605  * \brief Frees a \b NodeList object.
1606  *
1607  * Since the underlying \b Nodes are references, they are not freed using this
1608  * operation. This only frees the \b NodeList object.
1609  */
1610 EXPORT_SPEC void ixmlNodeList_free(
1611         /*! [in] The \b NodeList to free.  */
1612         IXML_NodeList *nList);
1613
1614
1615 /* @} Interface NodeList */
1616
1617
1618
1619 /*!
1620  * \name IXML API
1621  *
1622  * The IXML API contains utility functions that are not part of the standard
1623  * DOM interfaces. They include functions to create a DOM structure from a
1624  * file or buffer, create an XML file from a DOM structure, and manipulate
1625  * DOMString objects.
1626  *
1627  * @{
1628  */
1629
1630
1631 /*!
1632  * \brief Renders a \b Node and all sub-elements into an XML document
1633  * representation.
1634  *
1635  * The caller is required to free the \b DOMString
1636  * returned from this function using \b ixmlFreeDOMString when it
1637  * is no longer required.
1638  *
1639  * Note that this function can be used for any \b Node-derived
1640  * interface.  The difference between \b ixmlPrintDocument and
1641  * \b ixmlPrintNode is \b ixmlPrintDocument includes the XML prolog
1642  * while \b ixmlPrintNode only produces XML elements. An XML
1643  * document is not well formed unless it includes the prolog
1644  * and at least one element.
1645  *
1646  * This function  introduces lots of white space to print the
1647  * \b DOMString in readable  format.
1648  *
1649  * \return A \b DOMString with the XML document representation 
1650  *                     of the DOM tree or \c NULL on an error.
1651  */
1652 EXPORT_SPEC DOMString ixmlPrintDocument(
1653         /*! [in] The document node to print. */
1654         IXML_Document *doc);
1655
1656
1657 /*!
1658  * \brief Renders a \b Node and all sub-elements into an XML text
1659  * representation.
1660  *
1661  * The caller is required to free the \b DOMString
1662  * returned from this function using \b ixmlFreeDOMString when it
1663  * is no longer required.
1664  *
1665  * Note that this function can be used for any \b Node-derived
1666  * interface.  A similar \b ixmlPrintDocument function is defined
1667  * to avoid casting when printing whole documents. This function
1668  * introduces lots of white space to print the \b DOMString in readable
1669  * format.
1670  *
1671  * \return A \b DOMString with the XML text representation of the DOM tree or
1672  * \c NULL on an error.
1673  */
1674 EXPORT_SPEC DOMString ixmlPrintNode(
1675         /*! [in] The root of the \b Node tree to render to XML text. */
1676         IXML_Node *doc
1677 );
1678
1679
1680 /*!
1681  * \brief Renders a \b Node and all sub-elements into an XML document
1682  * representation.
1683  *
1684  * The caller is required to free the \b DOMString
1685  * returned from this function using \b ixmlFreeDOMString when it
1686  * is no longer required.
1687  *
1688  * Note that this function can be used for any \b Node-derived
1689  * interface.  The difference between \b ixmlDocumenttoString and
1690  * \b ixmlNodetoString is \b ixmlDocumenttoString includes the XML
1691  * prolog while \b ixmlNodetoString only produces XML elements. An XML
1692  * document is not well formed unless it includes the prolog
1693  * and at least one element.
1694  *
1695  * \return A \b DOMString with the XML text representation of the DOM tree or
1696  * \c NULL on an error.
1697  */
1698 EXPORT_SPEC DOMString ixmlDocumenttoString(
1699         /*! [in] The root of the \b Node tree to render to XML text. */
1700         IXML_Document *doc);
1701
1702
1703 /*!
1704  * \brief Renders a \b Node and all sub-elements into an XML text
1705  * representation.  The caller is required to free the \b DOMString
1706  * returned from this function using \b ixmlFreeDOMString when it
1707  * is no longer required.
1708  *
1709  * Note that this function can be used for any \b Node-derived
1710  * interface.  The difference between \b ixmlNodetoString and
1711  * \b ixmlDocumenttoString is \b ixmlNodetoString does not include
1712  * the XML prolog, it only produces XML elements.
1713  *
1714  * \return A \b DOMString with the XML text representation of the DOM tree or
1715  * \c NULL on an error.
1716  */
1717 EXPORT_SPEC DOMString ixmlNodetoString(
1718         /*! [in] The root of the \b Node tree to render to XML text. */
1719         IXML_Node *doc);
1720
1721
1722 /*!
1723  * \brief Makes the XML parser more tolerant to malformed text.
1724  */
1725 EXPORT_SPEC void ixmlRelaxParser(
1726         /*! [in] If \b errorChar is 0 (default), the parser is strict about XML 
1727          * encoding : invalid UTF-8 sequences or "&" entities are rejected, and 
1728          * the parsing aborts.
1729          *
1730          * If \b errorChar is not 0, the parser is relaxed: invalid UTF-8 
1731          * characters are replaced by the \b errorChar, and invalid "&" entities 
1732          * are left untranslated. The parsing is then allowed to continue.
1733          */
1734         char errorChar);
1735
1736
1737 /*!
1738  * \brief Parses an XML text buffer converting it into an IXML DOM representation.
1739  *
1740  * \return A \b Document if the buffer correctly parses or \c NULL on an error. 
1741  */
1742 EXPORT_SPEC IXML_Document *ixmlParseBuffer(
1743         /*! [in] The buffer that contains the XML text to convert to a \b Document. */
1744         const char *buffer);
1745
1746
1747 /*!
1748  * \brief Parses an XML text buffer converting it into an IXML DOM representation.
1749  *
1750  * The \b ixmlParseBufferEx API differs from the \b ixmlParseBuffer
1751  * API in that it returns an error code representing the actual failure
1752  * rather than just \c NULL.
1753  *
1754  * \return An integer representing one of the following:
1755  *     \li \c IXML_SUCCESS: The operation completed successfully.
1756  *     \li \c IXML_INVALID_PARAMETER: The \b buffer is not a valid 
1757  *           pointer.
1758  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
1759  *           to complete this operation.
1760  */
1761 EXPORT_SPEC int ixmlParseBufferEx(
1762         /*! [in] The buffer that contains the XML text to convert to a \b Document. */
1763         const char *buffer,
1764         /*! [out] A point to store the \b Document if file correctly parses or \b NULL on an error. */
1765         IXML_Document** doc);
1766
1767
1768 /*!
1769  * \brief Parses an XML text file converting it into an IXML DOM representation.
1770  *
1771  * \return A \b Document if the file correctly parses or \c NULL on an error.
1772  */
1773 EXPORT_SPEC IXML_Document *ixmlLoadDocument(
1774         /*! [in] The filename of the XML text to convert to a \b Document. */
1775         const char* xmlFile);
1776
1777
1778 /*!
1779  * \brief Parses an XML text file converting it into an IXML DOM representation.
1780  *
1781  * The \b ixmlLoadDocumentEx API differs from the \b ixmlLoadDocument
1782  * API in that it returns a an error code representing the actual failure
1783  * rather than just \c NULL.
1784  *
1785  * \return An integer representing one of the following:
1786  *     \li \c IXML_SUCCESS: The operation completed successfully.
1787  *     \li \c IXML_INVALID_PARAMETER: The \b xmlFile is not a valid 
1788  *           pointer.
1789  *     \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists 
1790  *           to complete this operation.
1791  */
1792 EXPORT_SPEC int ixmlLoadDocumentEx(
1793         /*! [in] The filename of the XML text to convert to a \b Document. */
1794         const char *xmlFile,
1795         /*! [out] A pointer to the \b Document if file correctly parses or \b NULL
1796          * on an error. */
1797         IXML_Document **doc);
1798
1799
1800 /*!
1801  * \brief Clones an existing \b DOMString.
1802  *
1803  * \return A new \b DOMString that is a duplicate of the original or \c NULL
1804  * if the operation could not be completed.
1805  */
1806 EXPORT_SPEC DOMString ixmlCloneDOMString(
1807         /*! [in] The source \b DOMString to clone. */
1808         const DOMString src);
1809
1810
1811 /*!
1812  * \brief Frees a \b DOMString.
1813  */
1814 EXPORT_SPEC void ixmlFreeDOMString(
1815         /*! [in] The \b DOMString to free. */
1816         DOMString buf);
1817
1818
1819 /* @} IXML API */
1820
1821
1822 #ifdef __cplusplus
1823 }
1824 #endif
1825
1826
1827 /* @} XMLAPI XML API */
1828
1829
1830 #endif  /* IXML_H */
1831