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