/******************************************************************************* * * Copyright (c) 2000-2003 Intel Corporation * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * * Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * Neither name of Intel Corporation nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * ******************************************************************************/ #ifndef _IXML_H_ #define _IXML_H_ #include #include #include #ifdef WIN32 #ifndef UPNP_STATIC_LIB #ifdef LIBUPNP_EXPORTS /* set up declspec for dll export to make functions visible to library users */ #define EXPORT_SPEC __declspec(dllexport) #else #define EXPORT_SPEC __declspec(dllimport) #endif #else #define EXPORT_SPEC #endif #else #define EXPORT_SPEC #endif typedef int BOOL; #define DOMString char * #ifndef TRUE #define TRUE 1 #endif #ifndef FALSE #define FALSE 0 #endif #ifndef IN #define IN #endif #ifndef OUT #define OUT #endif #ifndef INOUT #define INOUT #endif /**@name DOM Interfaces * The Document Object Model consists of a set of objects and interfaces * for accessing and manipulating documents. IXML does not implement all * the interfaces documented in the DOM2-Core recommendation but defines * a subset of the most useful interfaces. A description of the supported * interfaces and methods is presented in this section. * * For a complete discussion on the object model, the object hierarchy, * etc., refer to section 1.1 of the DOM2-Core recommendation. */ /*! @{ */ /*================================================================ * * DOM node type * * *=================================================================*/ typedef enum { eINVALID_NODE = 0, eELEMENT_NODE = 1, eATTRIBUTE_NODE = 2, eTEXT_NODE = 3, eCDATA_SECTION_NODE = 4, eENTITY_REFERENCE_NODE = 5, eENTITY_NODE = 6, ePROCESSING_INSTRUCTION_NODE = 7, eCOMMENT_NODE = 8, eDOCUMENT_NODE = 9, eDOCUMENT_TYPE_NODE = 10, eDOCUMENT_FRAGMENT_NODE = 11, eNOTATION_NODE = 12, } IXML_NODE_TYPE; /*================================================================ * * error code * * *=================================================================*/ typedef enum { /* see DOM spec */ IXML_INDEX_SIZE_ERR = 1, IXML_DOMSTRING_SIZE_ERR = 2, IXML_HIERARCHY_REQUEST_ERR = 3, IXML_WRONG_DOCUMENT_ERR = 4, IXML_INVALID_CHARACTER_ERR = 5, IXML_NO_DATA_ALLOWED_ERR = 6, IXML_NO_MODIFICATION_ALLOWED_ERR = 7, IXML_NOT_FOUND_ERR = 8, IXML_NOT_SUPPORTED_ERR = 9, IXML_INUSE_ATTRIBUTE_ERR = 10, IXML_INVALID_STATE_ERR = 11, IXML_SYNTAX_ERR = 12, IXML_INVALID_MODIFICATION_ERR = 13, IXML_NAMESPACE_ERR = 14, IXML_INVALID_ACCESS_ERR = 15, IXML_SUCCESS = 0, IXML_NO_SUCH_FILE = 101, IXML_INSUFFICIENT_MEMORY = 102, IXML_FILE_DONE = 104, IXML_INVALID_PARAMETER = 105, IXML_FAILED = 106, IXML_INVALID_ITEM_NUMBER = 107, } IXML_ERRORCODE; #define DOCUMENTNODENAME "#document" #define TEXTNODENAME "#text" #define CDATANODENAME "#cdata-section" /*================================================================ * * DOM data structures * * *=================================================================*/ typedef struct _IXML_Document *Docptr; typedef struct _IXML_Node *Nodeptr; typedef struct _IXML_Node { DOMString nodeName; DOMString nodeValue; IXML_NODE_TYPE nodeType; DOMString namespaceURI; DOMString prefix; DOMString localName; BOOL readOnly; Nodeptr parentNode; Nodeptr firstChild; Nodeptr prevSibling; Nodeptr nextSibling; Nodeptr firstAttr; Docptr ownerDocument; } IXML_Node; typedef struct _IXML_Document { IXML_Node n; } IXML_Document; typedef struct _IXML_CDATASection { IXML_Node n; } IXML_CDATASection; typedef struct _IXML_Element { IXML_Node n; DOMString tagName; } IXML_Element; typedef struct _IXML_ATTR { IXML_Node n; BOOL specified; IXML_Element *ownerElement; } IXML_Attr; typedef struct _IXML_Text { IXML_Node n; } IXML_Text; typedef struct _IXML_NodeList { IXML_Node *nodeItem; struct _IXML_NodeList *next; } IXML_NodeList; typedef struct _IXML_NamedNodeMap { IXML_Node *nodeItem; struct _IXML_NamedNodeMap *next; } IXML_NamedNodeMap; #ifdef __cplusplus extern "C" { #endif /*================================================================ * * NODE interfaces * * *=================================================================*/ /**@name Interface {\it Node} * The {\bf Node} interface forms the primary datatype for all other DOM * objects. Every other interface is derived from this interface, inheriting * its functionality. For more information, refer to DOM2-Core page 34. */ /*! @{ */ /** Returns the name of the {\bf Node}, depending on what type of * {\bf Node} it is, in a read-only string. Refer to the table in the * DOM2-Core for a description of the node names for various interfaces. * * @return [const DOMString] A constant {\bf DOMString} of the node name. */ EXPORT_SPEC const DOMString ixmlNode_getNodeName(IXML_Node *nodeptr /** Pointer to the node to retrieve the name. */ ); /** Returns the value of the {\bf Node} as a string. Note that this string * is not a copy and modifying it will modify the value of the {\bf Node}. * * @return [DOMString] A {\bf DOMString} of the {\bf Node} value. */ EXPORT_SPEC const DOMString ixmlNode_getNodeValue(IXML_Node *nodeptr /** Pointer to the {\bf Node} to retrieve the value. */ ); /** Assigns a new value to a {\bf Node}. The {\bf newNodeValue} string is * duplicated and stored in the {\bf Node} so that the original does not * have to persist past this call. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: The {\bf Node*} is not a valid * pointer. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlNode_setNodeValue(IXML_Node *nodeptr, /** The {\bf Node} to which to assign a new value. */ const char *newNodeValue /** The new value of the {\bf Node}. */ ); /** Retrieves the type of a {\bf Node}. The defined {\bf Node} constants * are: * \begin{itemize} * \item {\tt eATTRIBUTE_NODE} * \item {\tt eCDATA_SECTION_NODE} * \item {\tt eCOMMENT_NODE} * \item {\tt eDOCUMENT_FRAGMENT_NODE} * \item {\tt eDOCUMENT_NODE} * \item {\tt eDOCUMENT_TYPE_NODE} * \item {\tt eELEMENT_NODE} * \item {\tt eENTITY_NODE} * \item {\tt eENTITY_REFERENCE_NODE} * \item {\tt eNOTATION_NODE} * \item {\tt ePROCESSING_INSTRUCTION_NODE} * \item {\tt eTEXT_NODE} * \end{itemize} * * @return [const unsigned short] An integer representing the type of the * {\bf Node}. */ EXPORT_SPEC unsigned short ixmlNode_getNodeType(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the type. */ ); /** Retrieves the parent {\bf Node} for a {\bf Node}. * * @return [Node*] A pointer to the parent {\bf Node} or {\tt NULL} if the * {\bf Node} has no parent. */ EXPORT_SPEC IXML_Node* ixmlNode_getParentNode(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the parent. */ ); /** Retrieves the list of children of a {\bf Node} in a {\bf NodeList} * structure. If a {\bf Node} has no children, {\bf ixmlNode_getChildNodes} * returns a {\bf NodeList} structure that contains no {\bf Node}s. * * @return [NodeList*] A {\bf NodeList} of the children of the {\bf Node}. */ EXPORT_SPEC IXML_NodeList* ixmlNode_getChildNodes(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the children. */ ); /** Retrieves the first child {\bf Node} of a {\bf Node}. * * @return [Node*] A pointer to the first child {\bf Node} or {\tt NULL} * if the {\bf Node} does not have any children. */ EXPORT_SPEC IXML_Node* ixmlNode_getFirstChild(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the first child. */ ); /** Retrieves the last child {\bf Node} of a {\bf Node}. * * @return [Node*] A pointer to the last child {\bf Node} or {\tt NULL} if * the {\bf Node} does not have any children. */ EXPORT_SPEC IXML_Node* ixmlNode_getLastChild(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the last child. */ ); /** Retrieves the sibling {\bf Node} immediately preceding this {\bf Node}. * * @return [Node*] A pointer to the previous sibling {\bf Node} or * {\tt NULL} if no such {\bf Node} exists. */ EXPORT_SPEC IXML_Node* ixmlNode_getPreviousSibling(IXML_Node *nodeptr /** The {\bf Node} for which to retrieve the previous sibling. */ ); /** Retrieves the sibling {\bf Node} immediately following this {\bf Node}. * * @return [Node*] A pointer to the next sibling {\bf Node} or {\tt NULL} * if no such {\bf Node} exists. */ EXPORT_SPEC IXML_Node* ixmlNode_getNextSibling(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the next sibling. */ ); /** Retrieves the attributes of a {\bf Node}, if it is an {\bf Element} node, * in a {\bf NamedNodeMap} structure. * * @return [NamedNodeMap*] A {\bf NamedNodeMap} of the attributes or * {\tt NULL}. */ EXPORT_SPEC IXML_NamedNodeMap* ixmlNode_getAttributes(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the attributes. */ ); /** Retrieves the document object associated with this {\bf Node}. This * owner document {\bf Node} allows other {\bf Node}s to be created in the * context of this document. Note that {\bf Document} nodes do not have * an owner document. * * @return [Document*] A pointer to the owning {\bf Document} or * {\tt NULL}, if the {\bf Node} does not have an owner. */ EXPORT_SPEC IXML_Document* ixmlNode_getOwnerDocument(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the owner document. */ ); /** Retrieves the namespace URI for a {\bf Node} as a {\bf DOMString}. Only * {\bf Node}s of type {\tt eELEMENT_NODE} or {\tt eATTRIBUTE_NODE} can * have a namespace URI. {\bf Node}s created through the {\bf Document} * interface will only contain a namespace if created using * {\bf ixmlDocument_createElementNS}. * * @return [const DOMString] A {\bf DOMString} representing the URI of the * namespace or {\tt NULL}. */ EXPORT_SPEC const DOMString ixmlNode_getNamespaceURI(IXML_Node *nodeptr /** The {\bf Node} for which to retrieve the namespace. */ ); /** Retrieves the namespace prefix, if present. The prefix is the name * used as an alias for the namespace URI for this element. Only * {\bf Node}s of type {\tt eELEMENT_NODE} or {\tt eATTRIBUTE_NODE} can have * a prefix. {\bf Node}s created through the {\bf Document} interface will * only contain a prefix if created using {\bf ixmlDocument_createElementNS}. * * @return [DOMString] A {\bf DOMString} representing the namespace prefix * or {\tt NULL}. */ EXPORT_SPEC const DOMString ixmlNode_getPrefix(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the prefix. */ ); /** Retrieves the local name of a {\bf Node}, if present. The local name is * the tag name without the namespace prefix. Only {\bf Node}s of type * {\tt eELEMENT_NODE} or {\tt eATTRIBUTE_NODE} can have a local name. * {\Bf Node}s created through the {\bf Document} interface will only * contain a local name if created using {\bf ixmlDocument_createElementNS}. * * @return [const DOMString] A {\bf DOMString} representing the local name * of the {\bf Element} or {\tt NULL}. */ EXPORT_SPEC const DOMString ixmlNode_getLocalName(IXML_Node *nodeptr /** The {\bf Node} from which to retrieve the local name. */ ); /** Inserts a new child {\bf Node} before the existing child {\bf Node}. * {\bf refChild} can be {\tt NULL}, which inserts {\bf newChild} at the * end of the list of children. Note that the {\bf Node} (or {\bf Node}s) * in {\bf newChild} must already be owned by the owner document (or have no * owner at all) of {\bf nodeptr} for insertion. If not, the {\bf Node} * (or {\bf Node}s) must be imported into the document using * {\bf ixmlDocument_importNode}. If {\bf newChild} is already in the tree, * it is removed first. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf nodeptr} or * {\bf newChild} is {\tt NULL}. * \item {\tt IXML_HIERARCHY_REQUEST_ERR}: The type of the {\bf Node} * does not allow children of the type of {\bf newChild}. * \item {\tt IXML_WRONG_DOCUMENT_ERR}: {\bf newChild} has an owner * document that does not match the owner of {\bf nodeptr}. * \item {\tt IXML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} is * read-only or the parent of the {\bf Node} being inserted is * read-only. * \item {\tt IXML_NOT_FOUND_ERR}: {\bf refChild} is not a child of * {\bf nodeptr}. * \end{itemize} */ EXPORT_SPEC int ixmlNode_insertBefore(IXML_Node *nodeptr, /** The parent of the {\bf Node} before which to insert the new child. */ IXML_Node* newChild, /** The {\bf Node} to insert into the tree. */ IXML_Node* refChild /** The reference child where the new {\bf Node} should be inserted. The new {\bf Node} will appear directly before the reference child. */ ); /** Replaces an existing child {\bf Node} with a new child {\bf Node} in * the list of children of a {\bf Node}. If {\bf newChild} is already in * the tree, it will first be removed. {\bf returnNode} will contain the * {\bf oldChild} {\bf Node}, appropriately removed from the tree (i.e. it * will no longer have an owner document). * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMTER: Either {\bf nodeptr}, {\bf * newChild}, or {\bf oldChild} is {\tt NULL}. * \item {\tt IXML_HIERARCHY_REQUEST_ERR}: The {\bf newChild} is not * a type of {\bf Node} that can be inserted into this tree or * {\bf newChild} is an ancestor of {\bf nodePtr}. * \item {\tt IXML_WRONG_DOCUMENT_ERR}: {\bf newChild} was created from * a different document than {\bf nodeptr}. * \item {\tt IXML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} or * its parent is read-only. * \item {\tt IXML_NOT_FOUND_ERR}: {\bf oldChild} is not a child of * {\bf nodeptr}. * \end{itemize} */ EXPORT_SPEC int ixmlNode_replaceChild(IXML_Node *nodeptr, /** The parent of the {\bf Node} which contains the child to replace. */ IXML_Node* newChild, /** The child with which to replace {\bf oldChild}. */ IXML_Node* oldChild, /** The child to replace with {\bf newChild}. */ IXML_Node** returnNode /** Pointer to a {\bf Node} to place the removed {\bf oldChild} {\bf Node}. */ ); /** Removes a child from the list of children of a {\bf Node}. * {\bf returnNode} will contain the {\bf oldChild} {\bf Node}, * appropriately removed from the tree (i.e. it will no longer have an * owner document). * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf nodeptr} or * {\bf oldChild} is {\tt NULL}. * \item {\tt IXML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} or its * parent is read-only. * \item {\tt IXML_NOT_FOUND_ERR}: {\bf oldChild} is not among the * children of {\bf nodeptr}. * \end{itemize} */ EXPORT_SPEC int ixmlNode_removeChild(IXML_Node *nodeptr, /** The parent of the child to remove. */ IXML_Node* oldChild, /** The child {\bf Node} to remove. */ IXML_Node **returnNode /** Pointer to a {\bf Node} to place the removed {\bf oldChild} {\bf Node}. */ ); /** Appends a child {\bf Node} to the list of children of a {\bf Node}. If * {\bf newChild} is already in the tree, it is removed first. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf nodeptr} or * {\bf newChild} is {\tt NULL}. * \item {\tt IXML_HIERARCHY_REQUEST_ERR}: {\bf newChild} is of a type * that cannot be added as a child of {\bf nodeptr} or * {\bf newChild} is an ancestor of {\bf nodeptr}. * \item {\tt IXML_WRONG_DOCUMENT_ERR}: {\bf newChild} was created from * a different document than {\bf nodeptr}. * \item {\tt IXML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} is a * read-only {\bf Node}. */ EXPORT_SPEC int ixmlNode_appendChild(IXML_Node *nodeptr, /** The {\bf Node} in which to append the new child. */ IXML_Node* newChild /** The new child to append. */ ); /** Queries whether or not a {\bf Node} has children. * * @return [BOOL] {\tt TRUE} if the {\bf Node} has one or more children * otherwise {\tt FALSE}. */ EXPORT_SPEC BOOL ixmlNode_hasChildNodes(IXML_Node *nodeptr /** The {\bf Node} to query for children. */ ); /** Clones a {\bf Node}. The new {\bf Node} does not have a parent. The * {\bf deep} parameter controls whether the subtree of the {\bf Node} is * also cloned. For details on cloning specific types of {\bf Node}s, * refer to the DOM2-Core recommendation. * * @return [Node*] A clone of {\bf nodeptr} or {\tt NULL}. */ EXPORT_SPEC IXML_Node* ixmlNode_cloneNode(IXML_Node *nodeptr, /** The {\bf Node} to clone. */ BOOL deep /** {\tt TRUE} to clone the subtree also or {\tt FALSE} to clone only {\bf nodeptr}. */ ); /** Queries whether this {\bf Node} has attributes. Note that only * {\bf Element} nodes have attributes. * * @return [BOOL] {\tt TRUE} if the {\bf Node} has attributes otherwise * {\tt FALSE}. */ EXPORT_SPEC BOOL ixmlNode_hasAttributes(IXML_Node *nodeptr /** The {\bf Node} to query for attributes. */ ); /** Frees a {\bf Node} and all {\bf Node}s in its subtree. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlNode_free(IXML_Node *nodeptr /** The {\bf Node} to free. */ ); /*! @} */ /*================================================================ * * Attribute interfaces * * *=================================================================*/ /**@name Interface {\it Attr} * The {\bf Attr} interface represents an attribute of an {\bf Element}. * The document type definition (DTD) or schema usually dictate the * allowable attributes and values for a particular element. For more * information, refer to the {\it Interface Attr} section in the DOM2-Core. */ /*! @{ */ /** Frees an {\bf Attr} node. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlAttr_free(IXML_Attr *attrNode /** The {\bf Attr} node to free. */ ); /*! @} */ /*================================================================ * * CDATASection interfaces * * *=================================================================*/ /**@name Interface {\it CDATASection} * The {\bf CDATASection} is used to escape blocks of text containing * characters that would otherwise be regarded as markup. CDATA sections * cannot be nested. Their primary purpose is for including material such * XML fragments, without needing to escape all the delimiters. For more * information, refer to the {\it Interface CDATASection} section in the * DOM2-Core. */ /*! @{ */ /** Initializes a {\bf CDATASection} node. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlCDATASection_init(IXML_CDATASection *nodeptr /** The {\bf CDATASection} node to initialize. */ ); /** Frees a {\bf CDATASection} node. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlCDATASection_free(IXML_CDATASection *nodeptr /** The {\bf CDATASection} node to free. */ ); /*! @} */ /*================================================================ * * Document interfaces * * *=================================================================*/ /**@name Interface {\it Document} * The {\bf Document} interface represents the entire XML document. * In essence, it is the root of the document tree and provides the * primary interface to the elements of the document. For more information, * refer to the {\it Interface Document} section in the DOM2Core. */ /*! @{ */ /** Initializes a {\bf Document} node. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlDocument_init(IXML_Document *nodeptr /** The {\bf Document} node to initialize. */ ); /** Creates a new empty {\bf Document} node. The * {\bf ixmlDocument_createDocumentEx} API differs from the {\bf * ixmlDocument_createDocument} API in that it returns an error code * describing the reason for the failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createDocumentEx(IXML_Document** doc /** Pointer to a {\bf Document} where the new object will be stored. */ ); /** Creates a new empty {\bf Document} node. * * @return [Document*] A pointer to the new {\bf Document} or {\tt NULL} on * failure. */ EXPORT_SPEC IXML_Document* ixmlDocument_createDocument(); /** Creates a new {\bf Element} node with the given tag name. The new * {\bf Element} node has a {\tt nodeName} of {\bf tagName} and * the {\tt localName}, {\tt prefix}, and {\tt namespaceURI} set * to {\tt NULL}. To create an {\bf Element} with a namespace, * see {\bf ixmlDocument_createElementNS}. * * The {\bf ixmlDocument_createElementEx} API differs from the {\bf * ixmlDocument_createElement} API in that it returns an error code * describing the reason for failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc} or * {\bf tagName} is {\tt NULL}. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createElementEx(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString tagName, /** The tag name of the new {\bf Element} node. */ IXML_Element **rtElement /** Pointer to an {\bf Element} where the new object will be stored. */ ); /** Creates a new {\bf Element} node with the given tag name. The new * {\bf Element} node has a {\tt nodeName} of {\bf tagName} and * the {\tt localName}, {\tt prefix}, and {\tt namespaceURI} set * to {\tt NULL}. To create an {\bf Element} with a namespace, * see {\bf ixmlDocument_createElementNS}. * * @return [Document*] A pointer to the new {\bf Element} or {\tt NULL} on * failure. */ EXPORT_SPEC IXML_Element* ixmlDocument_createElement(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString tagName /** The tag name of the new {\bf Element} node. */ ); /** Creates a new {\bf Text} node with the given data. * The {\bf ixmlDocument_createTextNodeEx} API differs from the {\bf * ixmlDocument_createTextNode} API in that it returns an error code * describing the reason for failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc} or {\bf data} * is {\tt NULL}. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createTextNodeEx(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString data, /** The data to associate with the new {\bf Text} node. */ IXML_Node** textNode /** A pointer to a {\bf Node} where the new object will be stored. */ ); /** Creates a new {\bf Text} node with the given data. * * @return [Node*] A pointer to the new {\bf Node} or {\tt NULL} on failure. */ EXPORT_SPEC IXML_Node* ixmlDocument_createTextNode(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString data /** The data to associate with the new {\bf Text} node. */ ); /** Creates a new {\bf CDATASection} node with given data. * * The {\bf ixmlDocument_createCDATASectionEx} API differs from the {\bf * ixmlDocument_createCDATASection} API in that it returns an error code * describing the reason for failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc} or {\bd data} * is {\tt NULL}. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createCDATASectionEx(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString data, /** The data to associate with the new {\bf CDATASection} node. */ IXML_CDATASection** cdNode /** A pointer to a {\bf Node} where the new object will be stored. */ ); /** Creates a new {\bf CDATASection} node with given data. * * @return [CDATASection*] A pointer to the new {\bf CDATASection} or * {\tt NULL} on failure. */ EXPORT_SPEC IXML_CDATASection* ixmlDocument_createCDATASection(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString data /** The data to associate with the new {\bf CDATASection} node. */ ); /** Creates a new {\bf Attr} node with the given name. * * @return [Attr*] A pointer to the new {\bf Attr} or {\tt NULL} on failure. */ EXPORT_SPEC IXML_Attr* ixmlDocument_createAttribute(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const char *name /** The name of the new attribute. */ ); /** Creates a new {\bf Attr} node with the given name. * * The {\bf ixmlDocument_createAttributeEx} API differs from the {\bf * ixmlDocument_createAttribute} API in that it returns an error code * describing the reason for failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc} or {\bf name} * is {\tt NULL}. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createAttributeEx(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const char *name, /** The name of the new attribute. */ IXML_Attr** attrNode /** A pointer to a {\bf Attr} where the new object will be stored. */ ); /** Returns a {\bf NodeList} of all {\bf Elements} that match the given * tag name in the order in which they were encountered in a preorder * traversal of the {\bf Document} tree. * * @return [NodeList*] A pointer to a {\bf NodeList} containing the * matching items or {\tt NULL} on an error. */ EXPORT_SPEC IXML_NodeList* ixmlDocument_getElementsByTagName(IXML_Document *doc, /** The {\bf Document} to search. */ const DOMString tagName /** The tag name to find. */ ); /* introduced in DOM level 2 */ /** Creates a new {\bf Element} node in the given qualified name and * namespace URI. * * The {\bf ixmlDocument_createElementNSEx} API differs from the {\bf * ixmlDocument_createElementNS} API in that it returns an error code * describing the reason for failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc}, * {\bf namespaceURI}, or {\bf qualifiedName} is {\tt NULL}. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createElementNSEx(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString namespaceURI, /** The namespace URI for the new {\bf Element}. */ const DOMString qualifiedName, /** The qualified name of the new {\bf Element}. */ IXML_Element** rtElement /** A pointer to an {\bf Element} where the new object will be stored. */ ); /** Creates a new {\bf Element} node in the given qualified name and * namespace URI. * * @return [Element*] A pointer to the new {\bf Element} or {\tt NULL} on * failure. */ EXPORT_SPEC IXML_Element* ixmlDocument_createElementNS(IXML_Document *doc, /** The owner {\bf Document} of the new node. */ const DOMString namespaceURI, /** The namespace URI for the new {\bf Element}. */ const DOMString qualifiedName /** The qualified name of the new {\bf Element}. */ ); /** Creates a new {\bf Attr} node with the given qualified name and * namespace URI. * * The {\bf ixmlDocument_createAttributeNSEx} API differs from the {\bf * ixmlDocument_createAttributeNS} API in that it returns an error code * describing the reason for failure rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc}, * {\bf namespaceURI}, or {\bf qualifiedName} is {\tt NULL}. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_createAttributeNSEx(IXML_Document *doc, /** The owner {\bf Document} of the new {\bf Attr}. */ const DOMString namespaceURI, /** The namespace URI for the attribute. */ const DOMString qualifiedName, /** The qualified name of the attribute. */ IXML_Attr** attrNode /** A pointer to an {\bf Attr} where the new object will be stored. */ ); /** Creates a new {\bf Attr} node with the given qualified name and * namespace URI. * * @return [Attr*] A pointer to the new {\bf Attr} or {\tt NULL} on failure. */ EXPORT_SPEC IXML_Attr* ixmlDocument_createAttributeNS(IXML_Document *doc, /** The owner {\bf Document} of the new {\bf Attr}. */ const DOMString namespaceURI, /** The namespace URI for the attribute. */ const DOMString qualifiedName /** The qualified name of the attribute. */ ); /** Returns a {\bf NodeList} of {\bf Elements} that match the given * local name and namespace URI in the order they are encountered * in a preorder traversal of the {\bf Document} tree. Either * {\bf namespaceURI} or {\bf localName} can be the special {\tt "*"} * character, which matches any namespace or any local name respectively. * * @return [NodeList*] A pointer to a {\bf NodeList} containing the * matching items or {\tt NULL} on an error. */ EXPORT_SPEC IXML_NodeList* ixmlDocument_getElementsByTagNameNS(IXML_Document* doc, /** The {\bf Document} to search. */ const DOMString namespaceURI, /** The namespace of the elements to find or {\tt "*"} to match any namespace. */ const DOMString localName /** The local name of the elements to find or {\tt "*"} to match any local name. */ ); /** Returns the {\bf Element} whose {\tt ID} matches that given id. * * @return [Element*] A pointer to the matching {\bf Element} or * {\tt NULL} on an error. */ EXPORT_SPEC IXML_Element* ixmlDocument_getElementById(IXML_Document* doc, /** The owner {\bf Document} of the {\bf Element}. */ const DOMString tagName /** The name of the {\bf Element}.*/ ); /** Frees a {\bf Document} object and all {\bf Node}s associated with it. * Any {\bf Node}s extracted via any other interface function, e.g. * {\bf ixmlDocument_GetElementById}, become invalid after this call unless * explicitly cloned. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlDocument_free(IXML_Document* doc /** The {\bf Document} to free. */ ); /** Imports a {\bf Node} from another {\bf Document} into this * {\bf Document}. The new {\bf Node} does not a have parent node: it is a * clone of the original {\bf Node} with the {\tt ownerDocument} set to * {\bf doc}. The {\bf deep} parameter controls whether all the children * of the {\bf Node} are imported. Refer to the DOM2-Core recommendation * for details on importing specific node types. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf doc} or * {\bf importNode} is not a valid pointer. * \item {\tt IXML_NOT_SUPPORTED_ERR}: {\bf importNode} is a * {\bf Document}, which cannot be imported. * \item {\tt IXML_FAILED}: The import operation failed because the * {\bf Node} to be imported could not be cloned. * \end{itemize} */ EXPORT_SPEC int ixmlDocument_importNode(IXML_Document* doc, /** The {\bf Document} into which to import. */ IXML_Node* importNode, /** The {\bf Node} to import. */ BOOL deep, /** {\tt TRUE} to import all children of {\bf importNode} or {\tt FALSE} to import only the root node. */ IXML_Node** rtNode /** A pointer to a new {\bf Node} owned by {\bf doc}. */ ); /*! @} */ /*================================================================ * * Element interfaces * * *=================================================================*/ /**@name Interface {\it Element} * The {\bf Element} interface represents an element in an XML document. * Only {\bf Element}s are allowed to have attributes, which are stored in the * {\tt attributes} member of a {\bf Node}. The {\bf Element} interface * extends the {\bf Node} interface and adds more operations to manipulate * attributes. */ /*! @{ */ /** Initializes a {\bf IXML_Element} node. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlElement_init(IXML_Element *element /** The {\bf Element} to initialize.*/ ); /** Returns the name of the tag as a constant string. * * @return [const DOMString] A {\bf DOMString} representing the name of the * {\bf Element}. */ EXPORT_SPEC const DOMString ixmlElement_getTagName(IXML_Element* element /** The {\bf Element} from which to retrieve the name. */ ); /** Retrieves an attribute of an {\bf Element} by name. * * @return [DOMString] A {\bf DOMString} representing the value of the * attribute. */ EXPORT_SPEC const DOMString ixmlElement_getAttribute(IXML_Element* element, /** The {\bf Element} from which to retrieve the attribute. */ const DOMString name /** The name of the attribute to retrieve. */ ); /** Adds a new attribute to an {\bf Element}. If an attribute with the same * name already exists, the attribute value will be updated with the * new value in {\bf value}. * * @return [int] An integer representing of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element}, * {\bf name}, or {\bf value} is {\tt NULL}. * \item {\tt IXML_INVALID_CHARACTER_ERR}: {\bf name} contains an * illegal character. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete the operation. * \end{itemize} */ EXPORT_SPEC int ixmlElement_setAttribute(IXML_Element* element, /** The {\bf Element} on which to set the attribute. */ const DOMString name, /** The name of the attribute. */ const DOMString value /** The value of the attribute. Note that this is a non-parsed string and any markup must be escaped. */ ); /** Removes an attribute by name. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element} or * {\bf name} is {\tt NULL}. * \end{itemize} */ EXPORT_SPEC int ixmlElement_removeAttribute(IXML_Element* element, /** The {\bf Element} from which to remove the attribute. */ const DOMString name /** The name of the attribute to remove. */ ); /** Retrieves an attribute node by name. See * {\bf ixmlElement_getAttributeNodeNS} to retrieve an attribute node using * a qualified name or namespace URI. * * @return [Attr*] A pointer to the attribute matching {\bf name} or * {\tt NULL} on an error. */ EXPORT_SPEC IXML_Attr* ixmlElement_getAttributeNode(IXML_Element* element, /** The {\bf Element} from which to get the attribute node. */ const DOMString name /** The name of the attribute node to find. */ ); /** Adds a new attribute node to an {\bf Element}. If an attribute already * exists with {\bf newAttr} as a name, it will be replaced with the * new one and the old one will be returned in {\bf rtAttr}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element} or * {\bf newAttr} is {\tt NULL}. * \item {\tt IXML_WRONG_DOCUMENT_ERR}: {\bf newAttr} does not belong * to the same one as {\bf element}. * \item {\tt IXML_INUSE_ATTRIBUTE_ERR}: {\bf newAttr} is already * an attribute of another {\bf Element}. * \end{itemize} */ EXPORT_SPEC int ixmlElement_setAttributeNode(IXML_Element* element, /** The {\bf Element} in which to add the new attribute. */ IXML_Attr* newAttr, /** The new {\bf Attr} to add. */ IXML_Attr** rtAttr /** A pointer to an {\bf Attr} where the old {\bf Attr} will be stored. This will have a {\tt NULL} if no prior node existed. */ ); /** Removes the specified attribute node from an {\bf Element}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element} or * {\bf oldAttr} is {\tt NULL}. * \item {\tt IXML_NOT_FOUND_ERR}: {\bf oldAttr} is not among the list * attributes of {\bf element}. * \end{itemize} */ EXPORT_SPEC int ixmlElement_removeAttributeNode(IXML_Element* element, /** The {\bf Element} from which to remove the attribute. */ IXML_Attr* oldAttr, /** The attribute to remove from the {\bf Element}. */ IXML_Attr** rtAttr /** A pointer to an attribute in which to place the removed attribute. */ ); /** Returns a {\bf NodeList} of all {\it descendant} {\bf Elements} with * a given tag name, in the order in which they are encountered in a * pre-order traversal of this {\bf Element} tree. * * @return [NodeList*] A {\bf NodeList} of the matching {\bf Element}s or * {\tt NULL} on an error. */ EXPORT_SPEC IXML_NodeList* ixmlElement_getElementsByTagName(IXML_Element* element, /** The {\bf Element} from which to start the search. */ const DOMString tagName /** The name of the tag for which to search. */ ); /* introduced in DOM 2 */ /** Retrieves an attribute value using the local name and namespace URI. * * @return [DOMString] A {\bf DOMString} representing the value of the * matching attribute. */ EXPORT_SPEC const DOMString ixmlElement_getAttributeNS(IXML_Element* element, /** The {\bf Element} from which to get the attribute value. */ const DOMString namespaceURI, /** The namespace URI of the attribute. */ const DOMString localname /** The local name of the attribute. */ ); /** Adds a new attribute to an {\bf Element} using the local name and * namespace URI. If another attribute matches the same local name and * namespace, the prefix is changed to be the prefix part of the * {\tt qualifiedName} and the value is changed to {\bf value}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element}, * {\bf namespaceURI}, {\bf qualifiedName}, or {\bf value} is * {\tt NULL}. * \item {\tt IXML_INVALID_CHARACTER_ERR}: {\bf qualifiedName} contains * an invalid character. * \item {\tt IXML_NAMESPACE_ERR}: Either the {\bf qualifiedName} or * {\bf namespaceURI} is malformed. Refer to the DOM2-Core for * possible reasons. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exist * to complete the operation. * \item {\tt IXML_FAILED}: The operation could not be completed. * \end{itemize} */ EXPORT_SPEC int ixmlElement_setAttributeNS(IXML_Element* element, /** The {\bf Element} on which to set the attribute. */ const DOMString namespaceURI, /** The namespace URI of the new attribute. */ const DOMString qualifiedName, /** The qualified name of the attribute. */ const DOMString value /** The new value for the attribute. */ ); /** Removes an attribute using the namespace URI and local name. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element}, * {\bf namespaceURI}, or {\bf localName} is {\tt NULL}. * \end{itemize} */ EXPORT_SPEC int ixmlElement_removeAttributeNS(IXML_Element* element, /** The {\bf Element} from which to remove the the attribute. */ const DOMString namespaceURI, /** The namespace URI of the attribute. */ const DOMString localName /** The local name of the attribute.*/ ); /** Retrieves an {\bf Attr} node by local name and namespace URI. * * @return [Attr*] A pointer to an {\bf Attr} or {\tt NULL} on an error. */ EXPORT_SPEC IXML_Attr* ixmlElement_getAttributeNodeNS(IXML_Element* element, /** The {\bf Element} from which to get the attribute. */ const DOMString namespaceURI, /** The namespace URI of the attribute. */ const DOMString localName /** The local name of the attribute. */ ); /** Adds a new attribute node. If an attribute with the same local name * and namespace URI already exists in the {\bf Element}, the existing * attribute node is replaced with {\bf newAttr} and the old returned in * {\bf rcAttr}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: Either {\bf element} or * {\bf newAttr} is {\tt NULL}. * \item {\tt IXML_WRONG_DOCUMENT_ERR}: {\bf newAttr} does not belong * to the same document as {\bf element}. * \item {\tt IXML_INUSE_ATTRIBUTE_ERR}: {\bf newAttr} already is an * attribute of another {\bf Element}. * \end{itemize} */ EXPORT_SPEC int ixmlElement_setAttributeNodeNS(IXML_Element* element, /** The {\bf Element} in which to add the attribute node. */ IXML_Attr* newAttr, /** The new {\bf Attr} to add. */ IXML_Attr** rcAttr /** A pointer to the replaced {\bf Attr}, if it exists. */ ); /** Returns a {\bf NodeList} of all {\it descendant} {\bf Elements} with a * given tag name, in the order in which they are encountered in the * pre-order traversal of the {\bf Element} tree. * * @return [NodeList*] A {\bf NodeList} of matching {\bf Element}s or * {\tt NULL} on an error. */ EXPORT_SPEC IXML_NodeList* ixmlElement_getElementsByTagNameNS(IXML_Element* element, /** The {\bf Element} from which to start the search. */ const DOMString namespaceURI, /** The namespace URI of the {\bf Element}s to find. */ const DOMString localName /** The local name of the {\bf Element}s to find. */ ); /** Queries whether the {\bf Element} has an attribute with the given name * or a default value. * * @return [BOOL] {\tt TRUE} if the {\bf Element} has an attribute with * this name or has a default value for that attribute, * otherwise {\tt FALSE}. */ EXPORT_SPEC BOOL ixmlElement_hasAttribute(IXML_Element* element, /** The {\bf Element} on which to check for an attribute. */ const DOMString name /** The name of the attribute for which to check. */ ); /** Queries whether the {\bf Element} has an attribute with the given * local name and namespace URI or has a default value for that attribute. * * @return [BOOL] {\tt TRUE} if the {\bf Element} has an attribute with * the given namespace and local name or has a default * value for that attribute, otherwise {\tt FALSE}. */ EXPORT_SPEC BOOL ixmlElement_hasAttributeNS(IXML_Element* element, /** The {\bf Element} on which to check for the attribute. */ const DOMString namespaceURI, /** The namespace URI of the attribute. */ const DOMString localName /** The local name of the attribute. */ ); /** Frees the given {\bf Element} and any subtree of the {\bf Element}. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlElement_free(IXML_Element* element /** The {\bf Element} to free. */ ); /*! @} */ /*================================================================ * * NamedNodeMap interfaces * * *=================================================================*/ /**@name Interface {\it NamedNodeMap} * A {\bf NamedNodeMap} object represents a list of objects that can be * accessed by name. A {\bf NamedNodeMap} maintains the objects in * no particular order. The {\bf Node} interface uses a {\bf NamedNodeMap} * to maintain the attributes of a node. */ /*! @{ */ /** Returns the number of items contained in this {\bf NamedNodeMap}. * * @return [unsigned long] The number of nodes in this map. */ EXPORT_SPEC unsigned long ixmlNamedNodeMap_getLength(IXML_NamedNodeMap *nnMap /** The {\bf NamedNodeMap} from which to retrieve the size. */ ); /** Retrieves a {\bf Node} from the {\bf NamedNodeMap} by name. * * @return [Node*] A {\bf Node} or {\tt NULL} if there is an error. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_getNamedItem(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} to search. */ const DOMString name /** The name of the {\bf Node} to find. */ ); /** Adds a new {\bf Node} to the {\bf NamedNodeMap} using the {\bf Node} * name attribute. * * @return [Node*] The old {\bf Node} if the new {\bf Node} replaces it or * {\tt NULL} if the {\bf Node} was not in the * {\bf NamedNodeMap} before. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_setNamedItem(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} in which to add the new {\bf Node}. */ IXML_Node *arg /** The new {\bf Node} to add to the {\bf NamedNodeMap}. */ ); /** Removes a {\bf Node} from a {\bf NamedNodeMap} specified by name. * * @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if * it wasn't. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_removeNamedItem(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} from which to remove the item. */ const DOMString name /** The name of the item to remove. */ ); /** Retrieves a {\bf Node} from a {\bf NamedNodeMap} specified by a * numerical index. * * @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if * it wasn't. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_item(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} from which to remove the {\bf Node}. */ unsigned long index /** The index into the map to remove. */ ); /* introduced in DOM level 2 */ /** Retrieves a {\bf Node} from a {\bf NamedNodeMap} specified by * namespace URI and local name. * * @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if * it wasn't */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_getNamedItemNS(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} from which to remove the {\bf Node}. */ const DOMString *namespaceURI, /** The namespace URI of the {\bf Node} to remove. */ const DOMString localName /** The local name of the {\bf Node} to remove. */ ); /** Adds a new {\bf Node} to the {\bf NamedNodeMap} using the {\bf Node} * local name and namespace URI attributes. * * @return [Node*] The old {\bf Node} if the new {\bf Node} replaces it or * {\tt NULL} if the {\bf Node} was not in the * {\bf NamedNodeMap} before. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_setNamedItemNS(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} in which to add the {\bf Node}. */ IXML_Node *arg /** The {\bf Node} to add to the map. */ ); /** Removes a {\bf Node} from a {\bf NamedNodeMap} specified by * namespace URI and local name. * * @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if * it wasn't. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_removeNamedItemNS(IXML_NamedNodeMap *nnMap, /** The {\bf NamedNodeMap} from which to remove the {\bf Node}. */ const DOMString namespaceURI, /** The namespace URI of the {\bf Node} to remove. */ const DOMString localName /** The local name of the {\bf Node} to remove. */ ); /** Frees a {\bf NamedNodeMap}. The {\bf Node}s inside the map are not * freed, just the {\bf NamedNodeMap} object. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlNamedNodeMap_free(IXML_NamedNodeMap *nnMap /** The {\bf NamedNodeMap to free}. */ ); /*! @} */ /*================================================================ * * NodeList interfaces * * *=================================================================*/ /**@name Interface {\it NodeList} * The {\bf NodeList} interface abstracts an ordered collection of * nodes. Note that changes to the underlying nodes will change * the nodes contained in a {\bf NodeList}. The DOM2-Core refers to * this as being {\it live}. */ /*! @{ */ /** Retrieves a {\bf Node} from a {\bf NodeList} specified by a * numerical index. * * @return [Node*] A pointer to a {\bf Node} or {\tt NULL} if there was an * error. */ EXPORT_SPEC IXML_Node* ixmlNodeList_item(IXML_NodeList *nList, /** The {\bf NodeList} from which to retrieve the {\bf Node}. */ unsigned long index /** The index into the {\bf NodeList} to retrieve. */ ); /** Returns the number of {\bf Nodes} in a {\bf NodeList}. * * @return [unsigned long] The number of {\bf Nodes} in the {\bf NodeList}. */ EXPORT_SPEC unsigned long ixmlNodeList_length(IXML_NodeList *nList /** The {\bf NodeList} for which to retrieve the number of {\bf Nodes}. */ ); /** Frees a {\bf NodeList} object. Since the underlying {\bf Nodes} are * references, they are not freed using this operating. This only * frees the {\bf NodeList} object. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlNodeList_free(IXML_NodeList *nList /** The {\bf NodeList} to free. */ ); /*! @} */ /* Interface NodeList */ /*! @} */ /* DOM Interfaces */ /**@name IXML API * The IXML API contains utility functions that are not part of the standard * DOM interfaces. They include functions to create a DOM structure from a * file or buffer, create an XML file from a DOM structure, and manipulate * DOMString objects. */ /*! @{ */ /*================================================================ * * ixml interfaces * * *=================================================================*/ /** Renders a {\bf Node} and all sub-elements into an XML document * representation. The caller is required to free the {\bf DOMString} * returned from this function using {\bf ixmlFreeDOMString} when it * is no longer required. * * Note that this function can be used for any {\bf Node}-derived * interface. The difference between {\bf ixmlPrintDocument} and * {\bf ixmlPrintNode} is {\bf ixmlPrintDocument} includes the XML prolog * while {\bf ixmlPrintNode} only produces XML elements. An XML * document is not well formed unless it includes the prolog * and at least one element. * * This function introduces lots of white space to print the * {\bf DOMString} in readable format. * * @return [DOMString] A {\bf DOMString} with the XML document representation * of the DOM tree or {\tt NULL} on an error. */ EXPORT_SPEC DOMString ixmlPrintDocument(IXML_Document *doc); /** Renders a {\bf Node} and all sub-elements into an XML text * representation. The caller is required to free the {\bf DOMString} * returned from this function using {\bf ixmlFreeDOMString} when it * is no longer required. * * Note that this function can be used for any {\bf Node}-derived * interface. A similar {\bf ixmlPrintDocument} function is defined * to avoid casting when printing whole documents. This function * introduces lots of white space to print the {\bf DOMString} in readable * format. * * @return [DOMString] A {\bf DOMString} with the XML text representation * of the DOM tree or {\tt NULL} on an error. */ EXPORT_SPEC DOMString ixmlPrintNode(IXML_Node *doc /** The root of the {\bf Node} tree to render to XML text. */ ); /** Renders a {\bf Node} and all sub-elements into an XML document * representation. The caller is required to free the {\bf DOMString} * returned from this function using {\bf ixmlFreeDOMString} when it * is no longer required. * * Note that this function can be used for any {\bf Node}-derived * interface. The difference between {\bf ixmlDocumenttoString} and * {\bf ixmlNodetoString} is {\bf ixmlDocumenttoString} includes the XML * prolog while {\bf ixmlNodetoString} only produces XML elements. An XML * document is not well formed unless it includes the prolog * and at least one element. * * @return [DOMString] A {\bf DOMString} with the XML text representation * of the DOM tree or {\tt NULL} on an error. */ EXPORT_SPEC DOMString ixmlDocumenttoString(IXML_Document *doc); /** Renders a {\bf Node} and all sub-elements into an XML text * representation. The caller is required to free the {\bf DOMString} * returned from this function using {\bf ixmlFreeDOMString} when it * is no longer required. * * Note that this function can be used for any {\bf Node}-derived * interface. The difference between {\bf ixmlNodetoString} and * {\bf ixmlDocumenttoString} is {\bf ixmlNodetoString} does not include * the XML prolog, it only produces XML elements. * * @return [DOMString] A {\bf DOMString} with the XML text representation * of the DOM tree or {\tt NULL} on an error. */ EXPORT_SPEC DOMString ixmlNodetoString(IXML_Node *doc /** The root of the {\bf Node} tree to render to XML text. */ ); /** Makes the XML parser more tolerant to malformed text. * * If {\bf errorChar} is 0 (default), the parser is strict about XML * encoding : invalid UTF-8 sequences or "&" entities are rejected, and * the parsing aborts. * If {\bf errorChar} is not 0, the parser is relaxed : invalid UTF-8 * characters are replaced by the {\bf errorChar}, and invalid "&" entities * are left untranslated. The parsing is then allowed to continue. */ EXPORT_SPEC void ixmlRelaxParser(char errorChar); /** Parses an XML text buffer converting it into an IXML DOM representation. * * @return [Document*] A {\bf Document} if the buffer correctly parses or * {\tt NULL} on an error. */ EXPORT_SPEC IXML_Document* ixmlParseBuffer(const char *buffer /** The buffer that contains the XML text to convert to a {\bf Document}. */ ); /** Parses an XML text buffer converting it into an IXML DOM representation. * * The {\bf ixmlParseBufferEx} API differs from the {\bf ixmlParseBuffer} * API in that it returns an error code representing the actual failure * rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: The {\bf buffer} is not a valid * pointer. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlParseBufferEx(const char *buffer, /** The buffer that contains the XML text to convert to a {\bf Document}. */ IXML_Document** doc /** A point to store the {\bf Document} if file correctly parses or {\bf NULL} on an error. */ ); /** Parses an XML text file converting it into an IXML DOM representation. * * @return [Document*] A {\bf Document} if the file correctly parses or * {\tt NULL} on an error. */ EXPORT_SPEC IXML_Document* ixmlLoadDocument(const char* xmlFile /** The filename of the XML text to convert to a {\bf Document}. */ ); /** Parses an XML text file converting it into an IXML DOM representation. * * The {\bf ixmlLoadDocumentEx} API differs from the {\bf ixmlLoadDocument} * API in that it returns a an error code representing the actual failure * rather than just {\tt NULL}. * * @return [int] An integer representing one of the following: * \begin{itemize} * \item {\tt IXML_SUCCESS}: The operation completed successfully. * \item {\tt IXML_INVALID_PARAMETER}: The {\bf xmlFile} is not a valid * pointer. * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists * to complete this operation. * \end{itemize} */ EXPORT_SPEC int ixmlLoadDocumentEx(const char* xmlFile, /** The filename of the XML text to convert to a {\bf Document}. */ IXML_Document** doc /** A pointer to the {\bf Document} if file correctly parses or {\bf NULL} on an error. */ ); /** Clones an existing {\bf DOMString}. * * @return [DOMString] A new {\bf DOMString} that is a duplicate of the * original or {\tt NULL} if the operation could not * be completed. */ EXPORT_SPEC DOMString ixmlCloneDOMString(const DOMString src /** The source {\bf DOMString} to clone. */ ); /** Frees a {\bf DOMString}. * * @return [void] This function does not return a value. */ EXPORT_SPEC void ixmlFreeDOMString(DOMString buf /** The {\bf DOMString} to free. */ ); #ifdef __cplusplus } #endif /*! @} */ /* IXML API */ #endif /* _IXML_H_ */