ixml.h

Upnp开发包文件

   *  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.
   */

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}
   */

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.
   */

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}.
   */

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.
   */

DOMString   
ixmlElement_getAttribute(IXML_Element* element,  
		           /** The {\bf Element} from which to retrieve the 
			       attribute. */
                         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}
   */

int         
ixmlElement_setAttribute(IXML_Element* element,  
		           /** The {\bf Element} on which to set the 
			       attribute. */
                         DOMString name,    
			   /** The name of the attribute. */
                         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}
   */

int         
ixmlElement_removeAttribute(IXML_Element* element,  
		              /** The {\bf Element} from which to remove the 
			          attribute. */
                            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.
   */

IXML_Attr*       
ixmlElement_getAttributeNode(IXML_Element* element,  
		               /** The {\bf Element} from which to get the 
				   attribute node.  */
                             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}
   */

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}
   */

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.
   */

IXML_NodeList*   
ixmlElement_getElementsByTagName(IXML_Element* element,  
		                   /** The {\bf Element} from which to start 
				       the search. */
                                 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.
   */

DOMString   
ixmlElement_getAttributeNS(IXML_Element* element,       
		             /** The {\bf Element} from which to get the 
			         attribute value. */
                           DOMString namespaceURI, 
			     /** The namespace URI of the attribute. */
                           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}
   */

int         
ixmlElement_setAttributeNS(IXML_Element* element,         
		             /** The {\bf Element} on which to set the 
			         attribute. */
                           DOMString namespaceURI,   
		             /** The namespace URI of the new attribute. */
                           DOMString qualifiedName,  
			     /** The qualified name of the attribute. */
                           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}
   */

int         
ixmlElement_removeAttributeNS(IXML_Element* element,        
		                /** The {\bf Element} from which to remove the 
				    the attribute. */
                              DOMString namespaceURI,  
			        /** The namespace URI of the attribute. */
                              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.
   */

IXML_Attr*       
ixmlElement_getAttributeNodeNS(IXML_Element* element,        
		                 /** The {\bf Element} from which to get the 
				     attribute. */
                               DOMString namespaceURI,  
			         /** The namespace URI of the attribute. */
                               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}
   */

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.
   */

IXML_NodeList*   
ixmlElement_getElementsByTagNameNS(IXML_Element* element,        
		                     /** The {\bf Element} from which to start 
				         the search. */