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