diff --git a/Doxyfile b/Doxyfile index c78da76..8f10df3 100644 --- a/Doxyfile +++ b/Doxyfile @@ -462,7 +462,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = ./upnp ./ixml ./threadutil +INPUT = upnp ixml threadutil # This tag can be used to specify the character encoding of the source files that # doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default diff --git a/ixml/inc/ixml.h b/ixml/inc/ixml.h index c7a549e..7e85712 100644 --- a/ixml/inc/ixml.h +++ b/ixml/inc/ixml.h @@ -1,4 +1,4 @@ -/******************************************************************************* +/*!***************************************************************************** * * Copyright (c) 2000-2003 Intel Corporation * All rights reserved. @@ -29,8 +29,15 @@ * ******************************************************************************/ -#ifndef _IXML_H_ -#define _IXML_H_ +#ifndef IXML_H +#define IXML_H + + +/*! \file */ + + +/*! \defgroup XMLApi The XML API */ +/*@{*/ #include @@ -79,7 +86,8 @@ typedef int BOOL; #define INOUT #endif -/**@name DOM Interfaces + +/*! \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 @@ -89,15 +97,13 @@ typedef int BOOL; * 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 -* -* -*=================================================================*/ +/******************************************************************************* + * + * DOM node type + * + ******************************************************************************/ typedef enum { eINVALID_NODE = 0, @@ -116,14 +122,15 @@ typedef enum } IXML_NODE_TYPE; -/*================================================================ -* -* error code -* -* -*=================================================================*/ +/******************************************************************************* + * + * Error Codes + * + ******************************************************************************/ typedef enum { /* see DOM spec */ + IXML_SUCCESS = 0, + IXML_INDEX_SIZE_ERR = 1, IXML_DOMSTRING_SIZE_ERR = 2, IXML_HIERARCHY_REQUEST_ERR = 3, @@ -140,14 +147,12 @@ typedef enum 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; @@ -155,12 +160,12 @@ typedef enum #define TEXTNODENAME "#text" #define CDATANODENAME "#cdata-section" -/*================================================================ -* -* DOM data structures -* -* -*=================================================================*/ +/******************************************************************************* + * + * DOM data structures + * + ******************************************************************************/ + typedef struct _IXML_Document *Docptr; typedef struct _IXML_Node *Nodeptr; @@ -225,418 +230,384 @@ typedef struct _IXML_NamedNodeMap struct _IXML_NamedNodeMap *next; } IXML_NamedNodeMap; +/*@}*/ /* DOM Interfaces */ + + #ifdef __cplusplus extern "C" { #endif -/*================================================================ -* -* NODE interfaces -* -* -*=================================================================*/ +/******************************************************************************* + * + * 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. +/*! \name Interface Node + * The \b 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. */ +/*@{*/ -/*! @{ */ +/*! \brief Returns the name of the \b Node, depending on what type of +* \b 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 A constant \b DOMString of the node name. +*/ +EXPORT_SPEC const DOMString ixmlNode_getNodeName( + /*! Pointer to the node to retrieve the name. */ + IXML_Node *nodeptr); - /** 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. + +/*! \brief Returns the value of the \b Node as a string. Note that this string + * is not a copy and modifying it will modify the value of the \b Node. + * + * \return A \b DOMString of the \b Node value. + */ +EXPORT_SPEC const DOMString ixmlNode_getNodeValue( + /*! Pointer to the \b Node to retrieve the value. */ + IXML_Node *nodeptr); + + +/*! \brief Assigns a new value to a \b Node. + * + * The \b newNodeValue string is duplicated and stored in the \b Node so that + * the original does not have to persist past this call. + * + * \return An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: The Node * is not a valid pointer. + * \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists to + * complete this operation. + */ +EXPORT_SPEC int ixmlNode_setNodeValue( + /*! The \b Node to which to assign a new value. */ + IXML_Node *nodeptr, + /*! The new value of the \b Node. */ + const char *newNodeValue); + + +/*! \brief Retrieves the type of a \b Node. + * + * The defined \b Node constants are: + * \li \c eATTRIBUTE_NODE + * \li \c eCDATA_SECTION_NODE + * \li \c eCOMMENT_NODE + * \li \c eDOCUMENT_FRAGMENT_NODE + * \li \c eDOCUMENT_NODE + * \li \c eDOCUMENT_TYPE_NODE + * \li \c eELEMENT_NODE + * \li \c eENTITY_NODE + * \li \c eENTITY_REFERENCE_NODE + * \li \c eNOTATION_NODE + * \li \c ePROCESSING_INSTRUCTION_NODE + * \li \c eTEXT_NODE + * + * \return An integer representing the type of the \b Node. + */ +EXPORT_SPEC unsigned short ixmlNode_getNodeType( + /*! The \b Node from which to retrieve the type. */ + IXML_Node *nodeptr); + + +/*! \brief Retrieves the parent \b Node for a \b Node. + * + * \return A pointer to the parent \b Node or \c NULL if the \b Node has no + * parent. + */ +EXPORT_SPEC IXML_Node *ixmlNode_getParentNode( + /*! The \b Node from which to retrieve the parent. */ + IXML_Node *nodeptr); + + +/*! \brief Retrieves the list of children of a \b Node in a \b NodeList + * structure. + * + * If a \b Node has no children, \b ixmlNode_getChildNodes + * returns a \b NodeList structure that contains no \b Nodes. + * + * \return A \b NodeList of the children of the \b Node. + */ +EXPORT_SPEC IXML_NodeList * +ixmlNode_getChildNodes( + /*! The \b Node from which to retrieve the children. */ + IXML_Node *nodeptr); + + +/*! \brief Retrieves the first child \b Node of a \b Node. + * + * \return A pointer to the first child \b Node or \c NULL if the \b Node does + * not have any children. + */ +EXPORT_SPEC IXML_Node *ixmlNode_getFirstChild( + /*! The \b Node from which to retrieve the first child. */ + IXML_Node *nodeptr); + + +/*! \brief Retrieves the last child \b Node of a \b Node. + * + * \return A pointer to the last child \b Node or \c NULL if the \b Node does + * not have any children. + */ +EXPORT_SPEC IXML_Node *ixmlNode_getLastChild( + /*! The \b Node from which to retrieve the last child. */ + IXML_Node *nodeptr); + + +/*! \brief Retrieves the sibling \b Node immediately preceding this \b Node. + * + * \return A pointer to the previous sibling \b Node or \c NULL if no such + * \b Node exists. + */ +EXPORT_SPEC IXML_Node *ixmlNode_getPreviousSibling( + /*! The \b Node for which to retrieve the previous sibling. */ + IXML_Node *nodeptr); + + +/*! \brief Retrieves the sibling \b Node immediately following this \b Node. + * + * \return A pointer to the next sibling \b Node or \c NULL if no such + * \b Node exists. + */ +EXPORT_SPEC IXML_Node *ixmlNode_getNextSibling( + /*! The \b Node from which to retrieve the next sibling. */ + IXML_Node *nodeptr); + + + /*! \brief Retrieves the attributes of a \b Node, if it is an \b Element node, + * in a \b NamedNodeMap structure. * - * @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}. + * \return A \b NamedNodeMap of the attributes or \c NULL. */ EXPORT_SPEC IXML_NamedNodeMap* ixmlNode_getAttributes(IXML_Node *nodeptr - /** The {\bf Node} from which to retrieve the + /*! The \b 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 + /*! \brief Retrieves the document object associated with this \b Node. This + * owner document \b Node allows other \b Nodes to be created in the + * context of this document. Note that \b 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. + * \return [Document*] A pointer to the owning \b Document or + * \c NULL, if the \b Node does not have an owner. */ EXPORT_SPEC IXML_Document* ixmlNode_getOwnerDocument(IXML_Node *nodeptr - /** The {\bf Node} from which to retrieve the + /*! The \b 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} + /*! \brief Retrieves the namespace URI for a \b Node as a \b DOMString. Only + * \b Nodes of type \c eELEMENT_NODE or \c eATTRIBUTE_NODE can + * have a namespace URI. \b Nodes created through the \b Document * interface will only contain a namespace if created using - * {\bf ixmlDocument_createElementNS}. + * \b ixmlDocument_createElementNS. * - * @return [const DOMString] A {\bf DOMString} representing the URI of the - * namespace or {\tt NULL}. + * \return A \b DOMString representing the URI of the namespace or \c NULL. */ EXPORT_SPEC const DOMString ixmlNode_getNamespaceURI(IXML_Node *nodeptr - /** The {\bf Node} for which to retrieve the + /*! The \b Node for which to retrieve the namespace. */ ); - /** Retrieves the namespace prefix, if present. The prefix is the name + /*! \brief 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}. + * \b Nodes of type \c eELEMENT_NODE or \c eATTRIBUTE_NODE can have + * a prefix. \b Nodes created through the \b Document interface will + * only contain a prefix if created using \b ixmlDocument_createElementNS. * - * @return [DOMString] A {\bf DOMString} representing the namespace prefix - * or {\tt NULL}. + * \return A \b DOMString representing the namespace prefix or \c NULL. */ EXPORT_SPEC const DOMString ixmlNode_getPrefix(IXML_Node *nodeptr - /** The {\bf Node} from which to retrieve the prefix. */ + /*! The \b 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}. + /*! \brief Retrieves the local name of a \b Node, if present. The local name is + * the tag name without the namespace prefix. Only \b Nodes of type + * \c eELEMENT_NODE or \c eATTRIBUTE_NODE can have a local name. + * \b Nodes created through the \b Document interface will only + * contain a local name if created using \b ixmlDocument_createElementNS. * - * @return [const DOMString] A {\bf DOMString} representing the local name - * of the {\bf Element} or {\tt NULL}. + * \return [const DOMString] A \b DOMString representing the local name + * of the \b Element or \c NULL. */ EXPORT_SPEC const DOMString ixmlNode_getLocalName(IXML_Node *nodeptr - /** The {\bf Node} from which to retrieve the local + /*! The \b 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, + /*! \brief Inserts a new child \b Node before the existing child \b Node. + * \b refChild can be \c NULL, which inserts \b newChild at the + * end of the list of children. Note that the \b Node (or \b Nodes) + * in \b newChild must already be owned by the owner document (or have no + * owner at all) of \b nodeptr for insertion. If not, the \b Node + * (or \b Nodes) must be imported into the document using + * \b ixmlDocument_importNode. If \b 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b nodeptr or + * \b newChild is \c NULL. + * \li \c IXML_HIERARCHY_REQUEST_ERR: The type of the \b Node + * does not allow children of the type of \b newChild. + * \li \c IXML_WRONG_DOCUMENT_ERR: \b newChild has an owner + * document that does not match the owner of \b nodeptr. + * \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr is + * read-only or the parent of the \b Node being inserted is * read-only. - * \item {\tt IXML_NOT_FOUND_ERR}: {\bf refChild} is not a child of - * {\bf nodeptr}. - * \end{itemize} + * \li \c IXML_NOT_FOUND_ERR: \b refChild is not a child of + * \b nodeptr. */ EXPORT_SPEC int ixmlNode_insertBefore(IXML_Node *nodeptr, - /** The parent of the {\bf Node} before which to + /*! The parent of the \b Node before which to insert the new child. */ IXML_Node* newChild, - /** The {\bf Node} to insert into the tree. */ + /*! The \b 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 + /*! The reference child where the new \b Node + should be inserted. The new \b 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 + /*! \brief Replaces an existing child \b Node with a new child \b Node in + * the list of children of a \b Node. If \b newChild is already in + * the tree, it will first be removed. \b returnNode will contain the + * \b oldChild \b 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMTER: Either \b nodeptr, \b newChild, + * or \b oldChild is \c NULL. + * \li \c IXML_HIERARCHY_REQUEST_ERR: The \b newChild is not + * a type of \b Node that can be inserted into this tree or + * \b newChild is an ancestor of \b nodePtr. + * \li \c IXML_WRONG_DOCUMENT_ERR: \b newChild was created from + * a different document than \b nodeptr. + * \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr or * its parent is read-only. - * \item {\tt IXML_NOT_FOUND_ERR}: {\bf oldChild} is not a child of - * {\bf nodeptr}. - * \end{itemize} + * \li \c IXML_NOT_FOUND_ERR: \b oldChild is not a child of + * \b nodeptr. */ EXPORT_SPEC int ixmlNode_replaceChild(IXML_Node *nodeptr, - /** The parent of the {\bf Node} which contains the + /*! The parent of the \b Node which contains the child to replace. */ IXML_Node* newChild, - /** The child with which to replace {\bf oldChild}. */ + /*! The child with which to replace \b oldChild. */ IXML_Node* oldChild, - /** The child to replace with {\bf newChild}. */ + /*! The child to replace with \b newChild. */ IXML_Node** returnNode - /** Pointer to a {\bf Node} to place the removed {\bf - oldChild} {\bf Node}. */ + /*! Pointer to a \b Node to place the removed \b oldChild \b Node. */ ); - /** Removes a child from the list of children of a {\bf Node}. - * {\bf returnNode} will contain the {\bf oldChild} {\bf Node}, + /*! \brief Removes a child from the list of children of a \b Node. + * \b returnNode will contain the \b oldChild \b 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b nodeptr or + * \b oldChild is \c NULL. + * \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b 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} + * \li \c IXML_NOT_FOUND_ERR: \b oldChild is not among the + * children of \b nodeptr. */ EXPORT_SPEC int ixmlNode_removeChild(IXML_Node *nodeptr, - /** The parent of the child to remove. */ + /*! The parent of the child to remove. */ IXML_Node* oldChild, - /** The child {\bf Node} to remove. */ + /*! The child \b Node to remove. */ IXML_Node **returnNode - /** Pointer to a {\bf Node} to place the removed {\bf - oldChild} {\bf Node}. */ + /*! Pointer to a \b Node to place the removed \b oldChild \b 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}. - */ + /*! \brief Appends a child \b Node to the list of children of a \b Node. If + * \b newChild is already in the tree, it is removed first. + * + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b nodeptr or + * \b newChild is \c NULL. + * \li \c IXML_HIERARCHY_REQUEST_ERR: \b newChild is of a type + * that cannot be added as a child of \b nodeptr or + * \b newChild is an ancestor of \b nodeptr. + * \li \c IXML_WRONG_DOCUMENT_ERR: \b newChild was created from + * a different document than \b nodeptr. + * \li \c IXML_NO_MODIFICATION_ALLOWED_ERR: \b nodeptr is a + * read-only \b Node. + */ EXPORT_SPEC int ixmlNode_appendChild(IXML_Node *nodeptr, - /** The {\bf Node} in which to append the new child. */ + /*! The \b Node in which to append the new child. */ IXML_Node* newChild - /** The new child to append. */ + /*! 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}. - */ + /*! \brief Queries whether or not a \b Node has children. + * + * \return \c TRUE if the \b Node has one or more children otherwise \c FALSE. + */ EXPORT_SPEC BOOL ixmlNode_hasChildNodes(IXML_Node *nodeptr - /** The {\bf Node} to query for children. */ + /*! The \b 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}. - */ - +/*! \brief Clones a \b Node. The new \b Node does not have a parent. The + * \b deep parameter controls whether the subtree of the \b Node is + * also cloned. For details on cloning specific types of \b Nodes, + * refer to the DOM2-Core recommendation. + * + * \return A clone of \b nodeptr or \c NULL. + */ EXPORT_SPEC IXML_Node* ixmlNode_cloneNode(IXML_Node *nodeptr, - /** The {\bf Node} to clone. */ + /*! The \b Node to clone. */ BOOL deep - /** {\tt TRUE} to clone the subtree also or {\tt FALSE} - to clone only {\bf nodeptr}. */ + /*! \c TRUE to clone the subtree also or \c FALSE + to clone only \b 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}. - */ +/*! \brief Queries whether this \b Node has attributes. Note that only + * \b Element nodes have attributes. + * + * \return \c TRUE if the \b Node has attributes otherwise \c FALSE. + */ EXPORT_SPEC BOOL -ixmlNode_hasAttributes(IXML_Node *nodeptr - /** The {\bf Node} to query for attributes. */ - ); +ixmlNode_hasAttributes( + /*! The \b Node to query for attributes. */ + IXML_Node *nodeptr); - /** 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. */ - ); +/*! \brief Frees a \b Node and all \b Nodes in its subtree. + */ +EXPORT_SPEC void ixmlNode_free( + /*! The \b Node to free. */ + IXML_Node *nodeptr); -/*! @} */ +/*@}*/ /* Node Interface */ /*================================================================ * @@ -645,26 +616,26 @@ ixmlNode_free(IXML_Node *nodeptr * *=================================================================*/ -/**@name Interface {\it Attr} - * The {\bf Attr} interface represents an attribute of an {\bf Element}. +/*! \name Interface Attr + * The \b Attr interface represents an attribute of an \b 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. + * information, refer to the Interface Attr section in the DOM2-Core. */ -/*! @{ */ +/*@{*/ - /** Frees an {\bf Attr} node. + /*! Frees an \b Attr node. * - * @return [void] This function does not return a value. + * \return [void] This function does not return a value. */ EXPORT_SPEC void ixmlAttr_free(IXML_Attr *attrNode - /** The {\bf Attr} node to free. */ + /*! The \b Attr node to free. */ ); -/*! @} */ +/*@}*/ /* Interface Attr */ /*================================================================ @@ -674,39 +645,40 @@ ixmlAttr_free(IXML_Attr *attrNode * *=================================================================*/ -/**@name Interface {\it CDATASection} - * The {\bf CDATASection} is used to escape blocks of text containing +/*! \name Interface CDATASection + * The \b 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 + * information, refer to the Interface CDATASection section in the * DOM2-Core. */ -/*! @{ */ +/*@{*/ - /** Initializes a {\bf CDATASection} node. + /*! Initializes a \b CDATASection node. * - * @return [void] This function does not return a value. + * \return [void] This function does not return a value. */ EXPORT_SPEC void ixmlCDATASection_init(IXML_CDATASection *nodeptr - /** The {\bf CDATASection} node to initialize. */ + /*! The \b CDATASection node to initialize. */ ); - /** Frees a {\bf CDATASection} node. + /*! Frees a \b CDATASection node. * - * @return [void] This function does not return a value. + * \return [void] This function does not return a value. */ EXPORT_SPEC void ixmlCDATASection_free(IXML_CDATASection *nodeptr - /** The {\bf CDATASection} node to free. */ + /*! The \b CDATASection node to free. */ ); -/*! @} */ +/*@}*/ /* Interface CDATASection */ + /*================================================================ * @@ -715,422 +687,377 @@ ixmlCDATASection_free(IXML_CDATASection *nodeptr * *=================================================================*/ -/**@name Interface {\it Document} - * The {\bf Document} interface represents the entire XML document. +/*! \name Interface Document + * The \b 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. + * primary interface to the elements of the document. For more information, + * refer to the Interface Document section in the DOM2Core. */ -/*! @{ */ +/*@{*/ - /** Initializes a {\bf Document} node. + /*! Initializes a \b Document node. * - * @return [void] This function does not return a value. + * \return [void] This function does not return a value. */ EXPORT_SPEC void ixmlDocument_init(IXML_Document *nodeptr - /** The {\bf Document} node to initialize. */ + /*! The \b 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}. + /*! Creates a new empty \b Document node. The + * \b ixmlDocument_createDocumentEx API differs from the + * \b ixmlDocument_createDocument API in that it returns an error code + * describing the reason for the failure rather than just \c 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c 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 + /*! Pointer to a \b Document where the new object will be stored. */ ); - /** Creates a new empty {\bf Document} node. + /*! Creates a new empty \b Document node. * - * @return [Document*] A pointer to the new {\bf Document} or {\tt NULL} on + * \return [Document*] A pointer to the new \b Document or \c 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}. + /*! Creates a new \b Element node with the given tag name. The new + * \b Element node has a \c nodeName of \b tagName and + * the \c localName, \c prefix, and \c namespaceURI set + * to \c NULL. To create an \b Element with a namespace, + * see \b 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}. + * The \b ixmlDocument_createElementEx API differs from the \b + * ixmlDocument_createElement API in that it returns an error code + * describing the reason for failure rather than just \c 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc or + * \b tagName is \c NULL. + * \li \c 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. */ + /*! The owner \b Document of the new node. */ const DOMString tagName, - /** The tag name of the new {\bf Element} + /*! The tag name of the new \b Element node. */ IXML_Element **rtElement - /** Pointer to an {\bf Element} where the new + /*! Pointer to an \b 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}. + /*! Creates a new \b Element node with the given tag name. The new + * \b Element node has a \c nodeName of \b tagName and + * the \c localName, \c prefix, and \c namespaceURI set + * to \c NULL. To create an \b Element with a namespace, + * see \b ixmlDocument_createElementNS. * - * @return [Document*] A pointer to the new {\bf Element} or {\tt NULL} on + * \return [Document*] A pointer to the new \b Element or \c NULL on * failure. */ EXPORT_SPEC IXML_Element* ixmlDocument_createElement(IXML_Document *doc, - /** The owner {\bf Document} of the new node. */ + /*! The owner \b Document of the new node. */ const DOMString tagName - /** The tag name of the new {\bf Element} node. */ + /*! The tag name of the new \b 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}. + /*! Creates a new \b Text node with the given data. + * The \b ixmlDocument_createTextNodeEx API differs from the + * \b ixmlDocument_createTextNode API in that it returns an error code + * describing the reason for failure rather than just \c 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc or \b data + * is \c NULL. + * \li \c 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. */ + /*! The owner \b Document of the new node. */ const DOMString data, - /** The data to associate with the new {\bf - Text} node. */ + /*! The data to associate with the new \b Text node. */ IXML_Node** textNode - /** A pointer to a {\bf Node} where the new + /*! A pointer to a \b Node where the new object will be stored. */ ); - /** Creates a new {\bf Text} node with the given data. + /*! Creates a new \b Text node with the given data. * - * @return [Node*] A pointer to the new {\bf Node} or {\tt NULL} on failure. + * \return [Node*] A pointer to the new \b Node or \c NULL on failure. */ EXPORT_SPEC IXML_Node* ixmlDocument_createTextNode(IXML_Document *doc, - /** The owner {\bf Document} of the new node. */ + /*! The owner \b Document of the new node. */ const DOMString data - /** The data to associate with the new {\bf Text} + /*! The data to associate with the new \b Text node. */ ); - /** Creates a new {\bf CDATASection} node with given data. + /*! Creates a new \b 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}. + * The \b ixmlDocument_createCDATASectionEx API differs from the \b + * ixmlDocument_createCDATASection API in that it returns an error code + * describing the reason for failure rather than just \c 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc or \b data + * is \c NULL. + * \li \c 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 + /*! The owner \b Document of the new node. */ const DOMString data, - /** The data to associate with the new - {\bf CDATASection} node. */ + /*! The data to associate with the new + \b CDATASection node. */ IXML_CDATASection** cdNode - /** A pointer to a {\bf Node} where the + /*! A pointer to a \b Node where the new object will be stored. */ ); - /** Creates a new {\bf CDATASection} node with given data. + /*! Creates a new \b CDATASection node with given data. * - * @return [CDATASection*] A pointer to the new {\bf CDATASection} or - * {\tt NULL} on failure. + * \return A pointer to the new \b CDATASection or \c NULL on failure. */ - EXPORT_SPEC IXML_CDATASection* ixmlDocument_createCDATASection(IXML_Document *doc, - /** The owner {\bf Document} of the new - node. */ + /*! The owner \b Document of the new node. */ const DOMString data - /** The data to associate with the new {\bf - CDATASection} node. */ + /*! The data to associate with the new \b 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. - */ + /*! Creates a new \b Attr node with the given name. + * + * \return [Attr*] A pointer to the new \b Attr or \c NULL on failure. + */ EXPORT_SPEC IXML_Attr* ixmlDocument_createAttribute(IXML_Document *doc, - /** The owner {\bf Document} of the new node. */ + /*! The owner \b Document of the new node. */ const char *name - /** The name of the new attribute. */ + /*! The name of the new attribute. */ ); - /** Creates a new {\bf Attr} node with the given name. + /*! Creates a new \b 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}. + * The \b ixmlDocument_createAttributeEx API differs from the \b + * ixmlDocument_createAttribute API in that it returns an error code + * describing the reason for failure rather than just \c 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 + * \return An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc or \b name + * is \c NULL. + * \li \c 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. */ + /*! The owner \b Document of the new node. */ const char *name, - /** The name of the new attribute. */ + /*! The name of the new attribute. */ IXML_Attr** attrNode - /** A pointer to a {\bf Attr} where the new - object will be stored. */ + /*! A pointer to a \b Attr where the new object will be stored. */ ); - /** Returns a {\bf NodeList} of all {\bf Elements} that match the given + /*! Returns a \b NodeList of all \b Elements that match the given * tag name in the order in which they were encountered in a preorder - * traversal of the {\bf Document} tree. + * traversal of the \b Document tree. * - * @return [NodeList*] A pointer to a {\bf NodeList} containing the - * matching items or {\tt NULL} on an error. + * \return A pointer to a \b NodeList containing the matching items or \c NULL on an error. */ EXPORT_SPEC IXML_NodeList* ixmlDocument_getElementsByTagName(IXML_Document *doc, - /** The {\bf Document} to search. */ + /*! The \b Document to search. */ const DOMString tagName - /** The tag name to find. */ + /*! The tag name to find. */ ); /* introduced in DOM level 2 */ - /** Creates a new {\bf Element} node in the given qualified name and + /*! Creates a new \b 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}. + * The \b ixmlDocument_createElementNSEx API differs from the \b + * ixmlDocument_createElementNS API in that it returns an error code + * describing the reason for failure rather than just \c 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc, + * \b namespaceURI, or \b qualifiedName is \c NULL. + * \li \c 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. */ + /*! The owner \b Document of the new node. */ const DOMString namespaceURI, - /** The namespace URI for the new {\bf - Element}. */ + /*! The namespace URI for the new \b Element. */ const DOMString qualifiedName, - /** The qualified name of the new {\bf - Element}. */ + /*! The qualified name of the new \b Element. */ IXML_Element** rtElement - /** A pointer to an {\bf Element} where the - new object will be stored. */ + /*! A pointer to an \b Element where the new object will be stored. */ ); - /** Creates a new {\bf Element} node in the given qualified name and + /*! Creates a new \b Element node in the given qualified name and * namespace URI. * - * @return [Element*] A pointer to the new {\bf Element} or {\tt NULL} on + * \return [Element*] A pointer to the new \b Element or \c NULL on * failure. */ EXPORT_SPEC IXML_Element* ixmlDocument_createElementNS(IXML_Document *doc, - /** The owner {\bf Document} of the new node. */ + /*! The owner \b Document of the new node. */ const DOMString namespaceURI, - /** The namespace URI for the new {\bf - Element}. */ + /*! The namespace URI for the new \b Element. */ const DOMString qualifiedName - /** The qualified name of the new {\bf - Element}. */ + /*! The qualified name of the new \b Element. */ ); - /** Creates a new {\bf Attr} node with the given qualified name and + /*! Creates a new \b 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}. + * The \b ixmlDocument_createAttributeNSEx API differs from the \b + * ixmlDocument_createAttributeNS API in that it returns an error code + * describing the reason for failure rather than just \c 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc, + * \b namespaceURI, or \b qualifiedName is \c NULL. + * \li \c 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}. */ + /*! The owner \b Document of the new + \b Attr. */ const DOMString namespaceURI, - /** The namespace URI for the attribute. */ + /*! The namespace URI for the attribute. */ const DOMString qualifiedName, - /** The qualified name of the attribute. */ + /*! The qualified name of the attribute. */ IXML_Attr** attrNode - /** A pointer to an {\bf Attr} where the - new object will be stored. */ + /*! A pointer to an \b Attr where the new object will be stored. */ ); - /** Creates a new {\bf Attr} node with the given qualified name and + /*! Creates a new \b Attr node with the given qualified name and * namespace URI. * - * @return [Attr*] A pointer to the new {\bf Attr} or {\tt NULL} on failure. + * \return [Attr*] A pointer to the new \b Attr or \c NULL on failure. */ - EXPORT_SPEC IXML_Attr* ixmlDocument_createAttributeNS(IXML_Document *doc, - /** The owner {\bf Document} of the new - {\bf Attr}. */ + /*! The owner \b Document of the new \b Attr. */ const DOMString namespaceURI, - /** The namespace URI for the attribute. */ + /*! The namespace URI for the attribute. */ const DOMString qualifiedName - /** The qualified name of the attribute. */ + /*! The qualified name of the attribute. */ ); - /** Returns a {\bf NodeList} of {\bf Elements} that match the given + + /*! Returns a \b NodeList of \b 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 "*"} + * in a preorder traversal of the \b Document tree. Either + * \b namespaceURI or \b localName can be the special "*" * 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. + * \return A pointer to a \b NodeList containing the matching items or \c NULL on an error. */ - EXPORT_SPEC IXML_NodeList* ixmlDocument_getElementsByTagNameNS(IXML_Document* doc, - /** The {\bf Document} to search. */ + /*! The \b Document to search. */ const DOMString namespaceURI, - /** The namespace of the elements to - find or {\tt "*"} to match any - namespace. */ + /*! The namespace of the elements to find or "*" to match any namespace. */ const DOMString localName - /** The local name of the elements to - find or {\tt "*"} to match any local - name. */ + /*! The local name of the elements to find or "*" 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. - */ + /*! Returns the \b Element whose \c ID matches that given id. + * + * \return A pointer to the matching \b Element or \c NULL on an error. + */ EXPORT_SPEC IXML_Element* ixmlDocument_getElementById(IXML_Document* doc, - /** The owner {\bf Document} of the {\bf - Element}. */ + /*! The owner \b Document of the \b Element. */ const DOMString tagName - /** The name of the {\bf Element}.*/ + /*! The name of the \b 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 + /*! Frees a \b Document object and all \b Nodes associated with it. + * Any \b Nodes extracted via any other interface function, e.g. + * \b 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. */ + /*! The \b 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 + /*! Imports a \b Node from another \b Document into this + * \b Document. The new \b Node does not a have parent node: it is a + * clone of the original \b Node with the \c ownerDocument set to + * \b doc. The \b deep parameter controls whether all the children + * of the \b 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} + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b doc or + * \b importNode is not a valid pointer. + * \li \c IXML_NOT_SUPPORTED_ERR: \b importNode is a + * \b Document, which cannot be imported. + * \li \c IXML_FAILED: The import operation failed because the + * \b Node to be imported could not be cloned. */ EXPORT_SPEC int ixmlDocument_importNode(IXML_Document* doc, - /** The {\bf Document} into which to import. */ + /*! The \b Document into which to import. */ IXML_Node* importNode, - /** The {\bf Node} to import. */ + /*! The \b Node to import. */ BOOL deep, - /** {\tt TRUE} to import all children of {\bf - importNode} or {\tt FALSE} to import only the + /*! \c TRUE to import all children of \b importNode or \c FALSE to import only the root node. */ IXML_Node** rtNode - /** A pointer to a new {\bf Node} owned by {\bf - doc}. */ + /*! A pointer to a new \b Node owned by \b doc. */ ); -/*! @} */ +/*@}*/ /* Interface Document */ /*================================================================ * @@ -1139,363 +1066,319 @@ ixmlDocument_importNode(IXML_Document* doc, * *=================================================================*/ -/**@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 +/*! \name Interface Element + * The \b Element interface represents an element in an XML document. + * Only \b Elements are allowed to have attributes, which are stored in the + * \c attributes member of a \b Node. The \b Element interface + * extends the \b Node interface and adds more operations to manipulate * attributes. */ /*! @{ */ - /** Initializes a {\bf IXML_Element} node. + /*! Initializes a \b IXML_Element node. * - * @return [void] This function does not return a value. + * \return [void] This function does not return a value. */ EXPORT_SPEC void ixmlElement_init(IXML_Element *element - /** The {\bf Element} to initialize.*/ + /*! The \b Element to initialize.*/ ); - /** Returns the name of the tag as a constant string. + /*! Returns the name of the tag as a constant string. * - * @return [const DOMString] A {\bf DOMString} representing the name of the - * {\bf Element}. + * \return [const DOMString] A \b DOMString representing the name of the \b Element. */ EXPORT_SPEC const DOMString ixmlElement_getTagName(IXML_Element* element - /** The {\bf Element} from which to retrieve the - name. */ + /*! The \b Element from which to retrieve the name. */ ); - /** Retrieves an attribute of an {\bf Element} by name. + /*! Retrieves an attribute of an \b Element by name. * - * @return [DOMString] A {\bf DOMString} representing the value of the - * attribute. + * \return A \b 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. */ + /*! The \b Element from which to retrieve the attribute. */ const DOMString name - /** The name of the attribute to retrieve. */ + /*! The name of the attribute to retrieve. */ ); - /** Adds a new attribute to an {\bf Element}. If an attribute with the same + /*! Adds a new attribute to an \b Element. If an attribute with the same * name already exists, the attribute value will be updated with the - * new value in {\bf value}. + * new value in \b 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 + * \return [int] An integer representing of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element, + * \b name, or \b value is \c NULL. + * \li \c IXML_INVALID_CHARACTER_ERR: \b name contains an * illegal character. - * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exists + * \li \c 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. */ + /*! The \b Element on which to set the attribute. */ const DOMString name, - /** The name of the attribute. */ + /*! 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. */ + /*! The value of the attribute. Note that this is + a non-parsed string and any markup must be escaped. */ ); - /** Removes an attribute by name. + /*! 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} + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element or + * \b name is \c NULL. */ EXPORT_SPEC int ixmlElement_removeAttribute(IXML_Element* element, - /** The {\bf Element} from which to remove the + /*! The \b Element from which to remove the attribute. */ const DOMString name - /** The name of the attribute to remove. */ + /*! The name of the attribute to remove. */ ); - /** Retrieves an attribute node by name. See - * {\bf ixmlElement_getAttributeNodeNS} to retrieve an attribute node using + /*! Retrieves an attribute node by name. See + * \b 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. + * \return A pointer to the attribute matching \b name or \c NULL on an error. */ EXPORT_SPEC IXML_Attr* ixmlElement_getAttributeNode(IXML_Element* element, - /** The {\bf Element} from which to get the - attribute node. */ + /*! The \b Element from which to get the attribute node. */ const DOMString name - /** The name of the attribute node to find. */ + /*! 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}. + /*! Adds a new attribute node to an \b Element. If an attribute already + * exists with \b newAttr as a name, it will be replaced with the + * new one and the old one will be returned in \b 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} + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element or + * \b newAttr is \c NULL. + * \li \c IXML_WRONG_DOCUMENT_ERR: \b newAttr does not belong + * to the same one as \b element. + * \li \c IXML_INUSE_ATTRIBUTE_ERR: \b newAttr is already + * an attribute of another \b Element. */ EXPORT_SPEC int ixmlElement_setAttributeNode(IXML_Element* element, - /** The {\bf Element} in which to add the new - attribute. */ + /*! The \b Element in which to add the new attribute. */ IXML_Attr* newAttr, - /** The new {\bf Attr} to add. */ + /*! The new \b 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. */ + /*! A pointer to an \b Attr where the old + \b Attr will be stored. This will have + a \c NULL if no prior node existed. */ ); - /** Removes the specified attribute node from an {\bf Element}. + /*! Removes the specified attribute node from an \b 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} + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element or + * \b oldAttr is \c NULL. + * \li \c IXML_NOT_FOUND_ERR: \b oldAttr is not among the list + * attributes of \b element. */ EXPORT_SPEC int ixmlElement_removeAttributeNode(IXML_Element* element, - /** The {\bf Element} from which to remove + /*! The \b Element from which to remove the attribute. */ IXML_Attr* oldAttr, - /** The attribute to remove from the {\bf - Element}. */ + /*! The attribute to remove from the \b Element. */ IXML_Attr** rtAttr - /** A pointer to an attribute in which to + /*! A pointer to an attribute in which to place the removed attribute. */ ); - /** Returns a {\bf NodeList} of all {\it descendant} {\bf Elements} with + /*! Returns a \b NodeList of all \em descendant \b Elements with * a given tag name, in the order in which they are encountered in a - * pre-order traversal of this {\bf Element} tree. + * pre-order traversal of this \b Element tree. * - * @return [NodeList*] A {\bf NodeList} of the matching {\bf Element}s or - * {\tt NULL} on an error. + * \return [NodeList*] A \b NodeList of the matching \b Elements or + * \c NULL on an error. */ EXPORT_SPEC IXML_NodeList* ixmlElement_getElementsByTagName(IXML_Element* element, - /** The {\bf Element} from which to start - the search. */ + /*! The \b Element from which to start the search. */ const DOMString tagName - /** The name of the tag for which to - search. */ + /*! The name of the tag for which to search. */ ); /* introduced in DOM 2 */ - /** Retrieves an attribute value using the local name and namespace URI. + /*! Retrieves an attribute value using the local name and namespace URI. * - * @return [DOMString] A {\bf DOMString} representing the value of the + * \return [DOMString] A \b 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. */ + /*! The \b Element from which to get the attribute value. */ const DOMString namespaceURI, - /** The namespace URI of the attribute. */ + /*! The namespace URI of the attribute. */ const DOMString localname - /** The local name of the attribute. */ + /*! The local name of the attribute. */ ); - /** Adds a new attribute to an {\bf Element} using the local name and + /*! Adds a new attribute to an \b 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}. + * \c qualifiedName and the value is changed to \b 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 + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element, + * \b namespaceURI, \b qualifiedName, or \b value is + * \c NULL. + * \li \c IXML_INVALID_CHARACTER_ERR: \b 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 + * \li \c IXML_NAMESPACE_ERR: Either the \b qualifiedName or + * \b namespaceURI is malformed. Refer to the DOM2-Core for * possible reasons. - * \item {\tt IXML_INSUFFICIENT_MEMORY}: Not enough free memory exist + * \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exist * to complete the operation. - * \item {\tt IXML_FAILED}: The operation could not be completed. - * \end{itemize} + * \li \c IXML_FAILED: The operation could not be completed. */ EXPORT_SPEC int ixmlElement_setAttributeNS(IXML_Element* element, - /** The {\bf Element} on which to set the - attribute. */ + /*! The \b Element on which to set the attribute. */ const DOMString namespaceURI, - /** The namespace URI of the new attribute. */ + /*! The namespace URI of the new attribute. */ const DOMString qualifiedName, - /** The qualified name of the attribute. */ + /*! The qualified name of the attribute. */ const DOMString value - /** The new value for the attribute. */ + /*! The new value for the attribute. */ ); - /** Removes an attribute using the namespace URI and local name. + /*! 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} + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element, + * \b namespaceURI, or \b localName is \c NULL. */ EXPORT_SPEC int ixmlElement_removeAttributeNS(IXML_Element* element, - /** The {\bf Element} from which to remove the - the attribute. */ + /*! The \b Element from which to remove the the attribute. */ const DOMString namespaceURI, - /** The namespace URI of the attribute. */ + /*! The namespace URI of the attribute. */ const DOMString localName - /** The local name of the attribute.*/ + /*! The local name of the attribute.*/ ); - /** Retrieves an {\bf Attr} node by local name and namespace URI. + /*! Retrieves an \b Attr node by local name and namespace URI. * - * @return [Attr*] A pointer to an {\bf Attr} or {\tt NULL} on an error. + * \return [Attr*] A pointer to an \b Attr or \c NULL on an error. */ EXPORT_SPEC IXML_Attr* ixmlElement_getAttributeNodeNS(IXML_Element* element, - /** The {\bf Element} from which to get the - attribute. */ + /*! The \b Element from which to get the attribute. */ const DOMString namespaceURI, - /** The namespace URI of the attribute. */ + /*! The namespace URI of the attribute. */ const DOMString localName - /** The local name of the attribute. */ + /*! 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}. + /*! Adds a new attribute node. If an attribute with the same local name + * and namespace URI already exists in the \b Element, the existing + * attribute node is replaced with \b newAttr and the old returned in + * \b 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} + * \return [int] An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: Either \b element or + * \b newAttr is \c NULL. + * \li \c IXML_WRONG_DOCUMENT_ERR: \b newAttr does not belong + * to the same document as \b element. + * \li \c IXML_INUSE_ATTRIBUTE_ERR: \b newAttr already is an + * attribute of another \b Element. */ - EXPORT_SPEC int ixmlElement_setAttributeNodeNS(IXML_Element* element, - /** The {\bf Element} in which to add the - attribute node. */ + /*! The \b Element in which to add the attribute node. */ IXML_Attr* newAttr, - /** The new {\bf Attr} to add. */ + /*! The new \b Attr to add. */ IXML_Attr** rcAttr - /** A pointer to the replaced {\bf Attr}, if - it exists. */ + /*! A pointer to the replaced \b 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. - */ + /*! Returns a \b NodeList of all \em descendant \b Elements with a + * given tag name, in the order in which they are encountered in the + * pre-order traversal of the \b Element tree. + * + * \return A \b NodeList of matching \b Elements or \c NULL on an error. + */ EXPORT_SPEC IXML_NodeList* ixmlElement_getElementsByTagNameNS(IXML_Element* element, - /** The {\bf Element} from which to start - the search. */ + /*! The \b Element from which to start the search. */ const DOMString namespaceURI, - /** The namespace URI of the {\bf - Element}s to find. */ + /*! The namespace URI of the \b Elements to find. */ const DOMString localName - /** The local name of the {\bf Element}s - to find. */ + /*! The local name of the \b Elements to find. */ ); - /** Queries whether the {\bf Element} has an attribute with the given name + /*! Queries whether the \b Element has an attribute with the given name * or a default value. * - * @return [BOOL] {\tt TRUE} if the {\bf Element} has an attribute with + * \return [BOOL] \c TRUE if the \b Element has an attribute with * this name or has a default value for that attribute, - * otherwise {\tt FALSE}. + * otherwise \c FALSE. */ -EXPORT_SPEC BOOL -ixmlElement_hasAttribute(IXML_Element* element, - /** The {\bf Element} on which to check for an - attribute. */ +EXPORT_SPEC BOOL ixmlElement_hasAttribute(IXML_Element* element, + /*! The \b Element on which to check for an attribute. */ const DOMString name - /** The name of the attribute for which to check. */ + /*! The name of the attribute for which to check. */ ); - /** Queries whether the {\bf Element} has an attribute with the given + /*! Queries whether the \b 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 + * \return [BOOL] \c TRUE if the \b Element has an attribute with * the given namespace and local name or has a default - * value for that attribute, otherwise {\tt FALSE}. + * value for that attribute, otherwise \c FALSE. */ EXPORT_SPEC BOOL ixmlElement_hasAttributeNS(IXML_Element* element, - /** The {\bf Element} on which to check for the - attribute. */ + /*! The \b Element on which to check for the attribute. */ const DOMString namespaceURI, - /** The namespace URI of the attribute. */ + /*! The namespace URI of the attribute. */ const DOMString localName - /** The local name of the attribute. */ + /*! 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. - */ +/*! \brief Frees the given \b Element and any subtree of the \b Element. + */ +EXPORT_SPEC void ixmlElement_free( + /*! The \b Element to free. */ + IXML_Element *element); -EXPORT_SPEC void -ixmlElement_free(IXML_Element* element - /** The {\bf Element} to free. */ - ); +/*@}*/ /* Interface Element */ -/*! @} */ /*================================================================ * @@ -1504,151 +1387,133 @@ ixmlElement_free(IXML_Element* element * *=================================================================*/ -/**@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} +/*! \name Interface NamedNodeMap + * A \b NamedNodeMap object represents a list of objects that can be + * accessed by name. A \b NamedNodeMap maintains the objects in + * no particular order. The \b Node interface uses a \b NamedNodeMap * to maintain the attributes of a node. */ -/*! @{ */ +/*@{*/ - /** Returns the number of items contained in this {\bf NamedNodeMap}. + /*! Returns the number of items contained in this \b NamedNodeMap. * - * @return [unsigned long] The number of nodes in this map. + * \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 \b NamedNodeMap from which to retrieve the size. */ ); - /** Retrieves a {\bf Node} from the {\bf NamedNodeMap} by name. + /*! Retrieves a \b Node from the \b NamedNodeMap by name. * - * @return [Node*] A {\bf Node} or {\tt NULL} if there is an error. + * \return [Node*] A \b Node or \c NULL if there is an error. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_getNamedItem(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} to search. */ + /*! The \b NamedNodeMap to search. */ const DOMString name - /** The name of the {\bf Node} to find. */ + /*! The name of the \b Node to find. */ ); - /** Adds a new {\bf Node} to the {\bf NamedNodeMap} using the {\bf Node} + /*! Adds a new \b Node to the \b NamedNodeMap using the \b 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. + * \return [Node*] The old \b Node if the new \b Node replaces it or + * \c NULL if the \b Node was not in the + * \b NamedNodeMap before. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_setNamedItem(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} in which to add the - new {\bf Node}. */ + /*! The \b NamedNodeMap in which to add the new \b Node. */ IXML_Node *arg - /** The new {\bf Node} to add to the {\bf - NamedNodeMap}. */ + /*! The new \b Node to add to the \b NamedNodeMap. */ ); - /** Removes a {\bf Node} from a {\bf NamedNodeMap} specified by name. + /*! Removes a \b Node from a \b NamedNodeMap specified by name. * - * @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if + * \return [Node*] A pointer to the \b Node, if found, or \c NULL if * it wasn't. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_removeNamedItem(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} from which to - remove the item. */ + /*! The \b NamedNodeMap from which to remove the item. */ const DOMString name - /** The name of the item to remove. */ + /*! The name of the item to remove. */ ); - /** Retrieves a {\bf Node} from a {\bf NamedNodeMap} specified by a + /*! Retrieves a \b Node from a \b NamedNodeMap specified by a * numerical index. * - * @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if - * it wasn't. + * \return A pointer to the \b Node, if found, or \c NULL if it wasn't. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_item(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} from which to remove the - {\bf Node}. */ + /*! The \b NamedNodeMap from which to remove the \b Node. */ unsigned long index - /** The index into the map to remove. */ + /*! The index into the map to remove. */ ); /* introduced in DOM level 2 */ - /** Retrieves a {\bf Node} from a {\bf NamedNodeMap} specified by + /*! Retrieves a \b Node from a \b 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 + * \return A pointer to the \b Node, if found, or \c NULL if it wasn't */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_getNamedItemNS(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} from which to - remove the {\bf Node}. */ + /*! The \b NamedNodeMap from which to remove the \b Node. */ const DOMString *namespaceURI, - /** The namespace URI of the {\bf Node} to - remove. */ + /*! The namespace URI of the \b Node to remove. */ const DOMString localName - /** The local name of the {\bf Node} to - remove. */ + /*! The local name of the \b Node to remove. */ ); - /** Adds a new {\bf Node} to the {\bf NamedNodeMap} using the {\bf Node} + /*! Adds a new \b Node to the \b NamedNodeMap using the \b 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. + * \return [Node*] The old \b Node if the new \b Node replaces it or + * \c NULL if the \b Node was not in the + * \b NamedNodeMap before. */ EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_setNamedItemNS(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} in which to add - the {\bf Node}. */ + /*! The \b NamedNodeMap in which to add the \b Node. */ IXML_Node *arg - /** The {\bf Node} to add to the map. */ + /*! The \b Node to add to the map. */ ); - /** Removes a {\bf Node} from a {\bf NamedNodeMap} specified by + /*! Removes a \b Node from a \b 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. + * \return A pointer to the \b Node, if found, or \c NULL if it wasn't. */ - EXPORT_SPEC IXML_Node* ixmlNamedNodeMap_removeNamedItemNS(IXML_NamedNodeMap *nnMap, - /** The {\bf NamedNodeMap} from which to - remove the {\bf Node}. */ + /*! The \b NamedNodeMap from which to remove the \b Node. */ const DOMString namespaceURI, - /** The namespace URI of the {\bf Node} - to remove. */ + /*! The namespace URI of the \b Node to remove. */ const DOMString localName - /** The local name of the {\bf Node} to - remove. */ + /*! The local name of the \b 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. - */ +/*! \brief Frees a \b NamedNodeMap. + * + * The \b Nodes inside the map are not freed, just the \b NamedNodeMap object. + */ +EXPORT_SPEC void ixmlNamedNodeMap_free( + /*! The \b NamedNodeMap to free. */ + IXML_NamedNodeMap *nnMap); -EXPORT_SPEC void -ixmlNamedNodeMap_free(IXML_NamedNodeMap *nnMap - /** The {\bf NamedNodeMap to free}. */ - ); - -/*! @} */ +/*@}*/ /* Interface NodeMap */ /*================================================================ * @@ -1657,265 +1522,250 @@ ixmlNamedNodeMap_free(IXML_NamedNodeMap *nnMap * *=================================================================*/ -/**@name Interface {\it NodeList} - * The {\bf NodeList} interface abstracts an ordered collection of +/*! \name Interface NodeList + * The \b 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}. + * the nodes contained in a \b NodeList. The DOM2-Core refers to + * this as being \em live. */ -/*! @{ */ +/*@{*/ - /** Retrieves a {\bf Node} from a {\bf NodeList} specified by a + /*! Retrieves a \b Node from a \b NodeList specified by a * numerical index. * - * @return [Node*] A pointer to a {\bf Node} or {\tt NULL} if there was an + * \return [Node*] A pointer to a \b Node or \c 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}. */ + /*! The \b NodeList from which to retrieve the \b Node. */ unsigned long index - /** The index into the {\bf NodeList} to retrieve. */ + /*! The index into the \b NodeList to retrieve. */ ); - /** Returns the number of {\bf Nodes} in a {\bf NodeList}. + /*! Returns the number of \b Nodes in a \b NodeList. * - * @return [unsigned long] The number of {\bf Nodes} in the {\bf NodeList}. + * \return [unsigned long] The number of \b Nodes in the \b NodeList. */ EXPORT_SPEC unsigned long ixmlNodeList_length(IXML_NodeList *nList - /** The {\bf NodeList} for which to retrieve the - number of {\bf Nodes}. */ + /*! The \b NodeList for which to retrieve the + number of \b Nodes. */ ); - /** Frees a {\bf NodeList} object. Since the underlying {\bf Nodes} are + /*! Frees a \b NodeList object. Since the underlying \b Nodes are * references, they are not freed using this operating. This only - * frees the {\bf NodeList} object. + * frees the \b NodeList object. * - * @return [void] This function does not return a value. + * \return [void] This function does not return a value. */ EXPORT_SPEC void ixmlNodeList_free(IXML_NodeList *nList - /** The {\bf NodeList} to free. */ + /*! The \b NodeList to free. */ ); -/*! @} */ /* Interface NodeList */ -/*! @} */ /* DOM Interfaces */ +/*@}*/ /* Interface NodeList */ -/**@name IXML API + +/******************************************************************************* + * + * ixml 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); +/*! \brief Renders a \b Node and all sub-elements into an XML document + * representation. + * + * The caller is required to free the \b DOMString + * returned from this function using \b ixmlFreeDOMString when it + * is no longer required. + * + * Note that this function can be used for any \b Node-derived + * interface. The difference between \b ixmlPrintDocument and + * \b ixmlPrintNode is \b ixmlPrintDocument includes the XML prolog + * while \b 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 + * \b DOMString in readable format. + * + * \return [DOMString] A \b DOMString with the XML document representation + * of the DOM tree or \c NULL on an error. + */ +EXPORT_SPEC DOMString ixmlPrintDocument(IXML_Document *doc); - /** 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. - */ +/*! \brief Renders a \b Node and all sub-elements into an XML text + * representation. + * + * The caller is required to free the \b DOMString + * returned from this function using \b ixmlFreeDOMString when it + * is no longer required. + * + * Note that this function can be used for any \b Node-derived + * interface. A similar \b ixmlPrintDocument function is defined + * to avoid casting when printing whole documents. This function + * introduces lots of white space to print the \b DOMString in readable + * format. + * + * \return [DOMString] A \b DOMString with the XML text representation + * of the DOM tree or \c NULL on an error. + */ +EXPORT_SPEC DOMString ixmlPrintNode( + /*! The root of the \b Node tree to render to XML text. */ + IXML_Node *doc +); + + +/*! \brief Renders a \b Node and all sub-elements into an XML document + * representation. + * + * The caller is required to free the \b DOMString + * returned from this function using \b ixmlFreeDOMString when it + * is no longer required. + * + * Note that this function can be used for any \b Node-derived + * interface. The difference between \b ixmlDocumenttoString and + * \b ixmlNodetoString is \b ixmlDocumenttoString includes the XML + * prolog while \b ixmlNodetoString only produces XML elements. An XML + * document is not well formed unless it includes the prolog + * and at least one element. + * + * \return A \b DOMString with the XML text representation of the DOM tree or + * \c NULL on an error. + */ +EXPORT_SPEC DOMString ixmlDocumenttoString( + /*! The root of the \b Node tree to render to XML text. */ + IXML_Document *doc); + + +/*! \brief Renders a \b Node and all sub-elements into an XML text + * representation. The caller is required to free the \b DOMString + * returned from this function using \b ixmlFreeDOMString when it + * is no longer required. + * + * Note that this function can be used for any \b Node-derived + * interface. The difference between \b ixmlNodetoString and + * \b ixmlDocumenttoString is \b ixmlNodetoString does not include + * the XML prolog, it only produces XML elements. + * + * \return A \b DOMString with the XML text representation of the DOM tree or + * \c NULL on an error. + */ +EXPORT_SPEC DOMString ixmlNodetoString( + /*! The root of the \b Node tree to render to XML text. */ + IXML_Node *doc); + + +/*! \brief Makes the XML parser more tolerant to malformed text. + */ +EXPORT_SPEC void ixmlRelaxParser( + /*! If \b errorChar is 0 (default), the parser is strict about XML + * encoding : invalid UTF-8 sequences or "&" entities are rejected, and + * the parsing aborts. + * If \b errorChar is not 0, the parser is relaxed: invalid UTF-8 + * characters are replaced by the \b errorChar, and invalid "&" entities + * are left untranslated. The parsing is then allowed to continue. + */ + char errorChar); + + +/*! \brief Parses an XML text buffer converting it into an IXML DOM representation. + * + * \return A \b Document if the buffer correctly parses or \c 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}. */ - ); +ixmlParseBuffer( + /*! The buffer that contains the XML text to convert to a \b Document. */ + const char *buffer); - /** 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} - */ +/*! \brief Parses an XML text buffer converting it into an IXML DOM representation. + * + * The \b ixmlParseBufferEx API differs from the \b ixmlParseBuffer + * API in that it returns an error code representing the actual failure + * rather than just \c NULL. + * + * \return An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: The \b buffer is not a valid + * pointer. + * \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists + * to complete this operation. + */ +EXPORT_SPEC int ixmlParseBufferEx( + /*! The buffer that contains the XML text to convert to a \b Document. */ + const char *buffer, + /*! A point to store the \b Document if file correctly parses or \b NULL on an error. */ + IXML_Document** doc); -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. - */ +/*! \brief Parses an XML text file converting it into an IXML DOM representation. + * + * \return A \b Document if the file correctly parses or \c NULL on an error. + */ +EXPORT_SPEC IXML_Document *ixmlLoadDocument( + /*! The filename of the XML text to convert to a \b Document. */ + const char* xmlFile); -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} - */ +/*! \brief Parses an XML text file converting it into an IXML DOM representation. + * + * The \b ixmlLoadDocumentEx API differs from the \b ixmlLoadDocument + * API in that it returns a an error code representing the actual failure + * rather than just \c NULL. + * + * \return An integer representing one of the following: + * \li \c IXML_SUCCESS: The operation completed successfully. + * \li \c IXML_INVALID_PARAMETER: The \b xmlFile is not a valid + * pointer. + * \li \c IXML_INSUFFICIENT_MEMORY: Not enough free memory exists + * to complete this operation. + */ +EXPORT_SPEC int ixmlLoadDocumentEx( + /*! The filename of the XML text to convert to a \b Document. */ + const char *xmlFile, + /*! A pointer to the \b Document if file correctly parses or \b NULL + * on an error. */ + IXML_Document **doc); -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. - */ +/*! \brief Clones an existing \b DOMString. + * + * \return A new \b DOMString that is a duplicate of the original or \c NULL + * if the operation could not be completed. + */ +EXPORT_SPEC DOMString ixmlCloneDOMString( + /*! The source \b DOMString to clone. */ + const DOMString src); -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. - */ +/*! \brief Frees a \b DOMString. + */ +EXPORT_SPEC void ixmlFreeDOMString( + /*! The \b DOMString to free. */ + DOMString buf); -EXPORT_SPEC void -ixmlFreeDOMString(DOMString buf - /** The {\bf DOMString} to free. */ - ); + +/*@}*/ /* IXML API */ #ifdef __cplusplus } #endif -/*! @} */ /* IXML API */ +/*@}*/ /* The XML API */ -#endif /* _IXML_H_ */ +#endif /* IXML_H */ diff --git a/upnp/inc/upnp.h b/upnp/inc/upnp.h index e7dddbd..c3cc424 100644 --- a/upnp/inc/upnp.h +++ b/upnp/inc/upnp.h @@ -821,17 +821,19 @@ EXPORT_SPEC char *UpnpGetServerIpAddress(); EXPORT_SPEC char *UpnpGetServerIp6Address(); -/*! \b UpnpRegisterRootDevice registers a device application with - * the SDK. A device application cannot make any other API - * calls until it registers using this function. Device applications - * can also register as control points (see \b UpnpRegisterClient - * to get a control point handle to perform control point - * functionality). +/*! \brief Registers a device application with the UPnP Library. * - * \b UpnpRegisterRootDevice is synchronous and does not generate - * any callbacks. Callbacks can occur as soon as this function returns. + * A device application cannot make any other API calls until it registers + * using this function. * - * \return [int] An integer representing one of the following: + * Device applications can also register as control points (see + * \b UpnpRegisterClient to get a control point handle to perform control + * point functionality). + * + * \b UpnpRegisterRootDevice is synchronous and does not generate any + * callbacks. Callbacks can occur as soon as this function returns. + * + * \return An integer representing one of the following: * \li \c UPNP_E_SUCCESS: The operation completed successfully. * \li \c UPNP_E_FINISH: The SDK is already terminated or is not * initialized. @@ -865,70 +867,71 @@ EXPORT_SPEC int UpnpRegisterRootDevice( /*! Pointer to a variable to store the new device handle. */ OUT UpnpDevice_Handle *Hnd); -/*! \b UpnpRegisterRootDevice2 is similar to \b UpnpRegisterRootDevice, - * except that it also allows the description document to be specified as a - * file or a memory buffer. The description can also be configured to have the - * correct IP and port address. +/*! \brief Similar to \b UpnpRegisterRootDevice, except that it also allows + * the description document to be specified as a file or a memory buffer. * - * NOTE: For the configuration to be functional, the internal web server - * MUST be present. In addition, the web server MUST be activated - * (using \b UpnpSetWebServerRootDir) before calling this function. - * The only condition where the web server can be absent is if the - * description document is specified as a URL and no configuration is - * required (i.e. config_baseURL = 0.) + * The description can also be configured to have the correct IP and port + * address. * - * \b UpnpRegisterRootDevice2 is synchronous and does not generate - * any callbacks. Callbacks can occur as soon as this function returns. + * NOTE: For the configuration to be functional, the internal web server + * MUST be present. In addition, the web server MUST be activated + * (using \b UpnpSetWebServerRootDir) before calling this function. + * The only condition where the web server can be absent is if the + * description document is specified as a URL and no configuration is + * required (i.e. config_baseURL = 0.) * - * Examples of using different types of description documents: - * \verbatim - 1) Description specified as a URL: - descriptionType == UPNPREG_URL_DESC - description is the URL - bufferLen = 0 (ignored) - 2) Description specified as a file: - descriptionType == UPNPREG_FILENAME_DESC - description is a filename - bufferLen = 0 (ignored) - 3) Description specified as a memory buffer: - descriptionType == UPNPREG_BUF_DESC - description is pointer to a memory buffer - bufferLen == length of memory buffer - \endverbatim + * This is synchronous and does not generate any callbacks. Callbacks can occur + * as soon as this function returns. * - * \return [int] An integer representing one of the following: - * \li \c UPNP_E_SUCCESS: The operation completed successfully. - * \li \c UPNP_E_FINISH: The SDK is already terminated or - * is not initialized. - * \li \c UPNP_E_INVALID_DESC: The description document is not - * a valid device description. - * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd - * is not a valid pointer or \b DescURL is \c NULL. - * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. - * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing - * to a socket. - * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading - * from a socket. - * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. - * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the - * socket. - * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently - * allocated. - * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to - * register this root device. - * \li \c UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the - * internal buffer. - * \li \c UPNP_E_FILE_NOT_FOUND: The description file could not - * be found. - * \li \c UPNP_E_FILE_READ_ERROR: An error occurred reading the - * description file. - * \li \c UPNP_E_INVALID_URL: The URL to the description document - * is invalid. - * \li \c UPNP_E_EXT_NOT_XML: The URL to the description document - * or file should have a .xml extension. - * \li \c UPNP_E_NO_WEB_SERVER: The internal web server has been - * compiled out; the SDK cannot configure itself from the - * description document. + * Examples of using different types of description documents: + * \verbatim + 1) Description specified as a URL: + descriptionType == UPNPREG_URL_DESC + description is the URL + bufferLen = 0 (ignored) + 2) Description specified as a file: + descriptionType == UPNPREG_FILENAME_DESC + description is a filename + bufferLen = 0 (ignored) + 3) Description specified as a memory buffer: + descriptionType == UPNPREG_BUF_DESC + description is pointer to a memory buffer + bufferLen == length of memory buffer + \endverbatim + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_FINISH: The SDK is already terminated or + * is not initialized. + * \li \c UPNP_E_INVALID_DESC: The description document is not + * a valid device description. + * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd + * is not a valid pointer or \b DescURL is \c NULL. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to + * register this root device. + * \li \c UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the + * internal buffer. + * \li \c UPNP_E_FILE_NOT_FOUND: The description file could not + * be found. + * \li \c UPNP_E_FILE_READ_ERROR: An error occurred reading the + * description file. + * \li \c UPNP_E_INVALID_URL: The URL to the description document + * is invalid. + * \li \c UPNP_E_EXT_NOT_XML: The URL to the description document + * or file should have a .xml extension. + * \li \c UPNP_E_NO_WEB_SERVER: The internal web server has been + * compiled out; the SDK cannot configure itself from the + * description document. */ EXPORT_SPEC int UpnpRegisterRootDevice2( /*! The type of the description document. */ @@ -951,38 +954,39 @@ EXPORT_SPEC int UpnpRegisterRootDevice2( OUT UpnpDevice_Handle* Hnd); -/*! \b UpnpRegisterRootDevice3 registers a device application for a - * specific address family with the SDK. A device application cannot - * make any other API calls until it registers using this function. - * Device applications can also register as control points (see - * \b UpnpRegisterClient to get a control point handle to perform - * control point functionality). +/*! \brief Registers a device application for a specific address family with + * the UPnP library. * - * \b UpnpRegisterRootDevice is synchronous and does not generate - * any callbacks. Callbacks can occur as soon as this function returns. + * A device application cannot make any other API calls until it registers + * using this function. Device applications can also register as control + * points (see \b UpnpRegisterClient to get a control point handle to perform + * control point functionality). * - * \return [int] An integer representing one of the following: - * \li \c UPNP_E_SUCCESS: The operation completed successfully. - * \li \c UPNP_E_FINISH: The SDK is already terminated or - * is not initialized. - * \li \c UPNP_E_INVALID_DESC: The description document was not - * a valid device description. - * \li \c UPNP_E_INVALID_URL: The URL for the description document - * is not valid. - * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd - * is not a valid pointer or \b DescURL is \c NULL. - * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. - * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing - * to a socket. - * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading - * from a socket. - * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. - * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the - * socket. - * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently - * allocated. - * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to - * register this root device. + * This is synchronous and does not generate any callbacks. Callbacks can occur + * as soon as this function returns. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_FINISH: The SDK is already terminated or + * is not initialized. + * \li \c UPNP_E_INVALID_DESC: The description document was not + * a valid device description. + * \li \c UPNP_E_INVALID_URL: The URL for the description document + * is not valid. + * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd + * is not a valid pointer or \b DescURL is \c NULL. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to + * register this root device. */ EXPORT_SPEC int UpnpRegisterRootDevice3( /*! Pointer to a string containing the description URL for this root @@ -1000,6 +1004,25 @@ EXPORT_SPEC int UpnpRegisterRootDevice3( IN const int AddressFamily); +/*! \brief Unregisters a root device registered with \b UpnpRegisterRootDevice or + * \b UpnpRegisterRootDevice2. + * + * After this call, the \b UpnpDevice_Handle is no longer valid. For all + * advertisements that have not yet expired, the SDK sends a device unavailable + * message automatically. + * + * This is a synchronous call and generates no callbacks. Once this call + * returns, the SDK will no longer generate callbacks to the application. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device handle. + */ +EXPORT_SPEC int UpnpUnRegisterRootDevice( + /*! The handle of the root device instance to unregister. */ + IN UpnpDevice_Handle); + + /*! \brief Registers a control point application with the UPnP Library. * * A control point application cannot make any other API calls until it @@ -1046,25 +1069,6 @@ EXPORT_SPEC int UpnpUnRegisterClient( IN UpnpClient_Handle Hnd); -/*! \brief Unregisters a root device registered with \b UpnpRegisterRootDevice or - * \b UpnpRegisterRootDevice2. After this call, the - * \b UpnpDevice_Handle is no longer valid. For all advertisements that - * have not yet expired, the SDK sends a device unavailable message - * automatically. - * - * \b UpnpUnRegisterRootDevice is a synchronous call and generates no - * callbacks. Once this call returns, the SDK will no longer - * generate callbacks to the application. - * - * \return [int] An integer representing one of the following: - * \li \c UPNP_E_SUCCESS: The operation completed successfully. - * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device handle. - */ -EXPORT_SPEC int UpnpUnRegisterRootDevice( - /*! The handle of the root device instance to unregister. */ - IN UpnpDevice_Handle); - - /*! \deprecated Use \b UpnpSetMaxContentLength instead. * Warning: the Handle argument provided here is not used, so the effect * of this function is global to the SDK (= same as diff --git a/upnp/inc/upnpdebug.h b/upnp/inc/upnpdebug.h index ccf1f51..2441c0f 100644 --- a/upnp/inc/upnpdebug.h +++ b/upnp/inc/upnpdebug.h @@ -50,15 +50,15 @@ extern "C" { #endif -/** @name Other debugging features - The UPnP SDK contains other features to aid in debugging. +/** \name Other debugging features + * + * The UPnP SDK contains other features to aid in debugging. */ +/*@{*/ -/*! @{ */ - -/** @name Upnp_LogLevel +/** \name Upnp_LogLevel * The user has the option to select 4 different types of debugging levels, - * see {\tt UpnpSetLogLevel}. + * see \c UpnpSetLogLevel. * The critical level will show only those messages * which can halt the normal processing of the library, like memory * allocation errors. The remaining three levels are just for debugging @@ -67,12 +67,10 @@ extern "C" { * Info Level displays the other important operational information * regarding the working of the library. If the user selects All, * then the library displays all the debugging information that it has. - * \begin{itemize} - * \item {\tt UPNP_CRITICAL [0]} - * \item {\tt UPNP_PACKET [1]} - * \item {\tt UPNP_INFO [2]} - * \item {\tt UPNP_ALL [3]} - * \end{itemize} + * \li \c UPNP_CRITICAL [0] + * \li \c UPNP_PACKET [1] + * \li \c UPNP_INFO [2] + * \li \c UPNP_ALL [3] */ typedef enum Upnp_Module { @@ -86,18 +84,18 @@ typedef enum Upnp_Module { HTTP } Dbg_Module; -/*! @{ */ +/*@{*/ typedef enum Upnp_LogLevel_e { UPNP_CRITICAL, UPNP_PACKET, UPNP_INFO, UPNP_ALL } Upnp_LogLevel; -/*! @} */ +/*@}*/ /** - * Default log level : see {\tt Upnp_LogLevel} + * Default log level : see \c Upnp_LogLevel */ #define UPNP_DEFAULT_LOG_LEVEL UPNP_ALL @@ -128,7 +126,7 @@ static UPNP_INLINE int UpnpInitLog() { return UPNP_E_SUCCESS; } * Parameters: Upnp_LogLevel log_level * * Description: - * This functions set the log level (see {\tt Upnp_LogLevel} + * This functions set the log level (see \c Upnp_LogLevel) * Returns: void ***************************************************************************/ #ifdef DEBUG @@ -308,7 +306,7 @@ static UPNP_INLINE void UpnpDisplayFileAndLine( * \param [in] fd file descriptor where the banner will be written * \param [in] lines: The buffer that will be written * \param [in] size: Size of the buffer - * \param [in] starLength: This parameter provides the width of the banner + * \param [in] starlength: This parameter provides the width of the banner */ #ifdef DEBUG void UpnpDisplayBanner( @@ -349,7 +347,7 @@ static UPNP_INLINE void PrintThreadPoolStats( #endif -/*! @} */ +/*@}*/ #ifdef __cplusplus } diff --git a/upnp/src/api/upnpapi.c b/upnp/src/api/upnpapi.c index a9002f3..fea4595 100644 --- a/upnp/src/api/upnpapi.c +++ b/upnp/src/api/upnpapi.c @@ -163,6 +163,17 @@ int UpnpSdkDeviceregisteredV6 = 0; Upnp_SID gUpnpSdkNLSuuid; +// FIXME Put this declaration in the proper header file +static int +GetDescDocumentAndURL( IN Upnp_DescType descriptionType, + IN char *description, + IN unsigned int bufferLen, + IN int config_baseURL, + IN int AddressFamily, + OUT IXML_Document ** xmlDoc, + OUT char descURL[LINE_SIZE] ); + + /******************************************************************************/ int UpnpInit(IN const char *HostIP, IN unsigned short DestPort) { @@ -368,7 +379,7 @@ unsigned short UpnpGetServerPort6() return LOCAL_PORT_V6; } -/*****************************************************************************/ +/******************************************************************************/ char *UpnpGetServerIpAddress() { if (UpnpSdkInit != 1) { @@ -378,7 +389,7 @@ char *UpnpGetServerIpAddress() return gIF_IPV4; } -/*****************************************************************************/ +/******************************************************************************/ char *UpnpGetServerIp6Address() { if( UpnpSdkInit != 1 ) { @@ -389,33 +400,13 @@ char *UpnpGetServerIp6Address() } +/******************************************************************************/ #ifdef INCLUDE_DEVICE_APIS -/**************************************************************************** - * Function: UpnpRegisterRootDevice - * - * Parameters: - * IN const char *DescUrl:Pointer to a string containing the - * description URL for this root device instance. - * IN Upnp_FunPtr Callback: Pointer to the callback function for - * receiving asynchronous events. - * IN const void *Cookie: Pointer to user data returned with the - * callback function when invoked. - * OUT UpnpDevice_Handle *Hnd: Pointer to a variable to store the - * new device handle. - * - * Description: - * This function registers a device application with - * the UPnP Library. A device application cannot make any other API - * calls until it registers using this function. - * - * Return Values: - * UPNP_E_SUCCESS on success, nonzero on failure. - *****************************************************************************/ -int -UpnpRegisterRootDevice( IN const char *DescUrl, - IN Upnp_FunPtr Fun, - IN const void *Cookie, - OUT UpnpDevice_Handle * Hnd ) +int UpnpRegisterRootDevice( + IN const char *DescUrl, + IN Upnp_FunPtr Fun, + IN const void *Cookie, + OUT UpnpDevice_Handle * Hnd ) { struct Handle_Info *HInfo; @@ -533,24 +524,261 @@ UpnpRegisterRootDevice( IN const char *DescUrl, #ifdef INCLUDE_DEVICE_APIS -/**************************************************************************** - * Function: UpnpUnRegisterRootDevice - * - * Parameters: - * IN UpnpDevice_Handle Hnd: The handle of the device instance - * to unregister - * Description: - * This function unregisters a root device registered with - * UpnpRegisterRootDevice} or UpnpRegisterRootDevice2. After this call, the - * UpnpDevice_Handle Hnd is no longer valid. For all advertisements that - * have not yet expired, the UPnP library sends a device unavailable message - * automatically. - * - * Return Values: - * UPNP_E_SUCCESS on success, nonzero on failure. - *****************************************************************************/ -int -UpnpUnRegisterRootDevice( IN UpnpDevice_Handle Hnd ) +/******************************************************************************/ +int UpnpRegisterRootDevice2( + IN Upnp_DescType descriptionType, + IN const char *description_const, + IN size_t bufferLen, // ignored unless descType == UPNPREG_BUF_DESC + IN int config_baseURL, + IN Upnp_FunPtr Fun, + IN const void *Cookie, + OUT UpnpDevice_Handle * Hnd ) +{ + struct Handle_Info *HInfo; + int retVal = 0; + char *description = ( char * )description_const; + if( UpnpSdkInit != 1 ) { + return UPNP_E_FINISH; + } + + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Inside UpnpRegisterRootDevice2\n" ); + + if( Hnd == NULL || Fun == NULL ) { + return UPNP_E_INVALID_PARAM; + } + + HandleLock(); + if( UpnpSdkDeviceRegisteredV4 == 1 ) { + HandleUnlock(); + return UPNP_E_ALREADY_REGISTERED; + } + + if( ( *Hnd = GetFreeHandle() ) == UPNP_E_OUTOF_HANDLE ) { + HandleUnlock(); + return UPNP_E_OUTOF_MEMORY; + } + + HInfo = ( struct Handle_Info * )malloc( sizeof( struct Handle_Info ) ); + if( HInfo == NULL ) { + HandleUnlock(); + return UPNP_E_OUTOF_MEMORY; + } + HandleTable[*Hnd] = HInfo; + + // prevent accidental removal of a non-existent alias + HInfo->aliasInstalled = 0; + + retVal = GetDescDocumentAndURL( + descriptionType, description, bufferLen, + config_baseURL, AF_INET, + &HInfo->DescDocument, HInfo->DescURL ); + + if( retVal != UPNP_E_SUCCESS ) { + FreeHandle( *Hnd ); + HandleUnlock(); + return retVal; + } + + HInfo->aliasInstalled = ( config_baseURL != 0 ); + HInfo->HType = HND_DEVICE; + + HInfo->Callback = Fun; + HInfo->Cookie = ( void * )Cookie; + HInfo->MaxAge = DEFAULT_MAXAGE; + HInfo->DeviceList = NULL; + HInfo->ServiceList = NULL; + + CLIENTONLY( ListInit( &HInfo->SsdpSearchList, NULL, NULL ); ) + CLIENTONLY( HInfo->ClientSubList = NULL; ) + HInfo->MaxSubscriptions = UPNP_INFINITE; + HInfo->MaxSubscriptionTimeOut = UPNP_INFINITE; + HInfo->DeviceAf = AF_INET; + + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice2: Valid Description\n" ); + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice2: DescURL : %s\n", + HInfo->DescURL ); + + HInfo->DeviceList = + ixmlDocument_getElementsByTagName( HInfo->DescDocument, "device" ); + + if( !HInfo->DeviceList ) { + CLIENTONLY( ListDestroy( &HInfo->SsdpSearchList, 0 ); ) + ixmlDocument_free( HInfo->DescDocument ); + FreeHandle( *Hnd ); + HandleUnlock(); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice2: No devices found for RootDevice\n" ); + return UPNP_E_INVALID_DESC; + } + + HInfo->ServiceList = ixmlDocument_getElementsByTagName( + HInfo->DescDocument, "serviceList" ); + if( !HInfo->ServiceList ) { + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice2: No services found for RootDevice\n" ); + } + + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice2: Gena Check\n" ); + //******************************* + // GENA SET UP + //******************************* + if( getServiceTable( ( IXML_Node * ) HInfo->DescDocument, + &HInfo->ServiceTable, HInfo->DescURL ) ) { + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice2: GENA Service Table\n" ); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Here are the known services: \n" ); + printServiceTable( &HInfo->ServiceTable, UPNP_INFO, API ); + } else { + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "\nUpnpRegisterRootDevice2: Empty service table\n" ); + } + + UpnpSdkDeviceRegisteredV4 = 1; + + HandleUnlock(); + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "Exiting RegisterRootDevice2 Successfully\n" ); + + return UPNP_E_SUCCESS; +} +#endif // INCLUDE_DEVICE_APIS + + +#ifdef INCLUDE_DEVICE_APIS +/******************************************************************************/ +int UpnpRegisterRootDevice3( + IN const char *DescUrl, + IN Upnp_FunPtr Fun, + IN const void *Cookie, + OUT UpnpDevice_Handle * Hnd, + IN const int AddressFamily ) +{ + struct Handle_Info *HInfo; + int retVal = 0; + + if( UpnpSdkInit != 1 ) { + return UPNP_E_FINISH; + } + + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Inside UpnpRegisterRootDevice\n" ); + + HandleLock(); + if( Hnd == NULL || Fun == NULL || + DescUrl == NULL || strlen( DescUrl ) == 0 || + (AddressFamily != AF_INET && AddressFamily != AF_INET6) ) { + HandleUnlock(); + return UPNP_E_INVALID_PARAM; + } + + if( ( AddressFamily == AF_INET && UpnpSdkDeviceRegisteredV4 == 1 ) || + ( AddressFamily == AF_INET6 && UpnpSdkDeviceregisteredV6 == 1 ) ) { + HandleUnlock(); + return UPNP_E_ALREADY_REGISTERED; + } + + if( ( *Hnd = GetFreeHandle() ) == UPNP_E_OUTOF_HANDLE ) { + HandleUnlock(); + return UPNP_E_OUTOF_MEMORY; + } + + HInfo = ( struct Handle_Info * )malloc( sizeof( struct Handle_Info ) ); + if( HInfo == NULL ) { + HandleUnlock(); + return UPNP_E_OUTOF_MEMORY; + } + HandleTable[*Hnd] = HInfo; + + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Root device URL is %s\n", DescUrl ); + + HInfo->aliasInstalled = 0; + HInfo->HType = HND_DEVICE; + strcpy( HInfo->DescURL, DescUrl ); + HInfo->Callback = Fun; + HInfo->Cookie = ( void * )Cookie; + HInfo->MaxAge = DEFAULT_MAXAGE; + HInfo->DeviceList = NULL; + HInfo->ServiceList = NULL; + HInfo->DescDocument = NULL; + CLIENTONLY( ListInit( &HInfo->SsdpSearchList, NULL, NULL ); ) + CLIENTONLY( HInfo->ClientSubList = NULL; ) + HInfo->MaxSubscriptions = UPNP_INFINITE; + HInfo->MaxSubscriptionTimeOut = UPNP_INFINITE; + HInfo->DeviceAf = AddressFamily; + + if( ( retVal = + UpnpDownloadXmlDoc( HInfo->DescURL, &( HInfo->DescDocument ) ) ) + != UPNP_E_SUCCESS ) { + CLIENTONLY( ListDestroy( &HInfo->SsdpSearchList, 0 ) ); + FreeHandle( *Hnd ); + HandleUnlock(); + return retVal; + } + + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice: Valid Description\n" ); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice: DescURL : %s\n", + HInfo->DescURL ); + + HInfo->DeviceList = + ixmlDocument_getElementsByTagName( HInfo->DescDocument, "device" ); + if( !HInfo->DeviceList ) { + CLIENTONLY( ListDestroy( &HInfo->SsdpSearchList, 0 ) ); + ixmlDocument_free( HInfo->DescDocument ); + FreeHandle( *Hnd ); + HandleUnlock(); + UpnpPrintf( UPNP_CRITICAL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice: No devices found for RootDevice\n" ); + return UPNP_E_INVALID_DESC; + } + + HInfo->ServiceList = ixmlDocument_getElementsByTagName( + HInfo->DescDocument, "serviceList" ); + if( !HInfo->ServiceList ) { + UpnpPrintf( UPNP_CRITICAL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice: No services found for RootDevice\n" ); + } + + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice: Gena Check\n" ); + //******************************* + // GENA SET UP + //******************************* + if( getServiceTable( ( IXML_Node * ) HInfo->DescDocument, + &HInfo->ServiceTable, HInfo->DescURL ) ) { + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "UpnpRegisterRootDevice: GENA Service Table \n" ); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Here are the known services: \n" ); + printServiceTable( &HInfo->ServiceTable, UPNP_INFO, API ); + } else { + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "\nUpnpRegisterRootDevice2: Empty service table\n" ); + } + + if( AddressFamily == AF_INET ) + UpnpSdkDeviceRegisteredV4 = 1; + else + UpnpSdkDeviceregisteredV6 = 1; + + HandleUnlock(); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Exiting RegisterRootDevice Successfully\n" ); + + return UPNP_E_SUCCESS; +} +#endif // INCLUDE_DEVICE_APIS + + +#ifdef INCLUDE_DEVICE_APIS +int UpnpUnRegisterRootDevice(IN UpnpDevice_Handle Hnd) { int retVal = 0; struct Handle_Info *HInfo = NULL; @@ -613,9 +841,121 @@ UpnpUnRegisterRootDevice( IN UpnpDevice_Handle Hnd ) return retVal; -} /****************** End of UpnpUnRegisterRootDevice *********************/ +} +#endif // INCLUDE_DEVICE_APIS + + +/*****************************************************************************/ +#ifdef INCLUDE_CLIENT_APIS +int UpnpRegisterClient( + IN Upnp_FunPtr Fun, + IN const void *Cookie, + OUT UpnpClient_Handle *Hnd) +{ + struct Handle_Info *HInfo; + + if( UpnpSdkInit != 1 ) { + return UPNP_E_FINISH; + } + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "Inside UpnpRegisterClient \n" ); + if( Fun == NULL || Hnd == NULL ) { + return UPNP_E_INVALID_PARAM; + } + + HandleLock(); + + if( UpnpSdkClientRegistered ) { + HandleUnlock(); + return UPNP_E_ALREADY_REGISTERED; + } + if( ( *Hnd = GetFreeHandle() ) == UPNP_E_OUTOF_HANDLE ) { + HandleUnlock(); + return UPNP_E_OUTOF_MEMORY; + } + HInfo = ( struct Handle_Info * )malloc( sizeof( struct Handle_Info ) ); + if( HInfo == NULL ) { + HandleUnlock(); + return UPNP_E_OUTOF_MEMORY; + } + + HInfo->HType = HND_CLIENT; + HInfo->Callback = Fun; + HInfo->Cookie = ( void * )Cookie; + HInfo->ClientSubList = NULL; + ListInit( &HInfo->SsdpSearchList, NULL, NULL ); +#ifdef INCLUDE_DEVICE_APIS + HInfo->MaxAge = 0; + HInfo->MaxSubscriptions = UPNP_INFINITE; + HInfo->MaxSubscriptionTimeOut = UPNP_INFINITE; +#endif + + HandleTable[*Hnd] = HInfo; + UpnpSdkClientRegistered = 1; + + HandleUnlock(); + + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "Exiting UpnpRegisterClient \n" ); + + return UPNP_E_SUCCESS; +} +#endif // INCLUDE_CLIENT_APIS + + +/*****************************************************************************/ +#ifdef INCLUDE_CLIENT_APIS +int UpnpUnRegisterClient(IN UpnpClient_Handle Hnd) +{ + struct Handle_Info *HInfo; + ListNode *node = NULL; + SsdpSearchArg *searchArg = NULL; + + if( UpnpSdkInit != 1 ) { + return UPNP_E_FINISH; + } + + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "Inside UpnpUnRegisterClient \n" ); + HandleLock(); + if( !UpnpSdkClientRegistered ) { + HandleUnlock(); + return UPNP_E_INVALID_HANDLE; + } + HandleUnlock(); + +#if EXCLUDE_GENA == 0 + if( genaUnregisterClient( Hnd ) != UPNP_E_SUCCESS ) + return UPNP_E_INVALID_HANDLE; +#endif + HandleLock(); + if( GetHandleInfo( Hnd, &HInfo ) == UPNP_E_INVALID_HANDLE ) { + HandleUnlock(); + return UPNP_E_INVALID_HANDLE; + } + //clean up search list + node = ListHead( &HInfo->SsdpSearchList ); + while( node != NULL ) { + searchArg = ( SsdpSearchArg * ) node->item; + if( searchArg ) { + free( searchArg->searchTarget ); + free( searchArg ); + } + ListDelNode( &HInfo->SsdpSearchList, node, 0 ); + node = ListHead( &HInfo->SsdpSearchList ); + } + + ListDestroy( &HInfo->SsdpSearchList, 0 ); + FreeHandle( Hnd ); + UpnpSdkClientRegistered = 0; + HandleUnlock(); + UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, + "Exiting UpnpUnRegisterClient \n" ); + return UPNP_E_SUCCESS; + +} +#endif // INCLUDE_CLIENT_APIS -#endif //INCLUDE_DEVICE_APIS // ************************************************************* #ifdef INCLUDE_DEVICE_APIS @@ -903,421 +1243,8 @@ GetDescDocumentAndURL( IN Upnp_DescType descriptionType, } #endif // INTERNAL_WEB_SERVER -// ******************************************************** - -/**************************************************************************** - * Function: UpnpRegisterRootDevice2 - * - * Parameters: - * IN Upnp_DescType descriptionType: The type of description document. - * IN const char* description: Treated as a URL, file name or - * memory buffer depending on description type. - * IN size_t bufferLen: Length of memory buffer if passing a description - * in a buffer, otherwize ignored. - * IN int config_baseURL: If nonzero, URLBase of description document is - * configured and the description is served using the internal - * web server. - * IN Upnp_FunPtr Fun: Pointer to the callback function for - * receiving asynchronous events. - * IN const void* Cookie: Pointer to user data returned with the - * callback function when invoked. - * OUT UpnpDevice_Handle* Hnd: Pointer to a variable to store - * the new device handle. - * - * Description: - * This function is similar to UpnpRegisterRootDevice except that - * it also allows the description document to be specified as a file or - * a memory buffer. The description can also be configured to have the - * correct IP and port address. - * - * Return Values: - * UPNP_E_SUCCESS on success, nonzero on failure. - *****************************************************************************/ -int -UpnpRegisterRootDevice2( IN Upnp_DescType descriptionType, - IN const char *description_const, - IN size_t bufferLen, // ignored unless descType == UPNPREG_BUF_DESC - - IN int config_baseURL, - IN Upnp_FunPtr Fun, - IN const void *Cookie, - OUT UpnpDevice_Handle * Hnd ) -{ - struct Handle_Info *HInfo; - int retVal = 0; - char *description = ( char * )description_const; - if( UpnpSdkInit != 1 ) { - return UPNP_E_FINISH; - } - - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Inside UpnpRegisterRootDevice2\n" ); - - if( Hnd == NULL || Fun == NULL ) { - return UPNP_E_INVALID_PARAM; - } - - HandleLock(); - if( UpnpSdkDeviceRegisteredV4 == 1 ) { - HandleUnlock(); - return UPNP_E_ALREADY_REGISTERED; - } - - if( ( *Hnd = GetFreeHandle() ) == UPNP_E_OUTOF_HANDLE ) { - HandleUnlock(); - return UPNP_E_OUTOF_MEMORY; - } - - HInfo = ( struct Handle_Info * )malloc( sizeof( struct Handle_Info ) ); - if( HInfo == NULL ) { - HandleUnlock(); - return UPNP_E_OUTOF_MEMORY; - } - HandleTable[*Hnd] = HInfo; - - // prevent accidental removal of a non-existent alias - HInfo->aliasInstalled = 0; - - retVal = GetDescDocumentAndURL( - descriptionType, description, bufferLen, - config_baseURL, AF_INET, - &HInfo->DescDocument, HInfo->DescURL ); - - if( retVal != UPNP_E_SUCCESS ) { - FreeHandle( *Hnd ); - HandleUnlock(); - return retVal; - } - - HInfo->aliasInstalled = ( config_baseURL != 0 ); - HInfo->HType = HND_DEVICE; - - HInfo->Callback = Fun; - HInfo->Cookie = ( void * )Cookie; - HInfo->MaxAge = DEFAULT_MAXAGE; - HInfo->DeviceList = NULL; - HInfo->ServiceList = NULL; - - CLIENTONLY( ListInit( &HInfo->SsdpSearchList, NULL, NULL ); ) - CLIENTONLY( HInfo->ClientSubList = NULL; ) - HInfo->MaxSubscriptions = UPNP_INFINITE; - HInfo->MaxSubscriptionTimeOut = UPNP_INFINITE; - HInfo->DeviceAf = AF_INET; - - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice2: Valid Description\n" ); - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice2: DescURL : %s\n", - HInfo->DescURL ); - - HInfo->DeviceList = - ixmlDocument_getElementsByTagName( HInfo->DescDocument, "device" ); - - if( !HInfo->DeviceList ) { - CLIENTONLY( ListDestroy( &HInfo->SsdpSearchList, 0 ); ) - ixmlDocument_free( HInfo->DescDocument ); - FreeHandle( *Hnd ); - HandleUnlock(); - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice2: No devices found for RootDevice\n" ); - return UPNP_E_INVALID_DESC; - } - - HInfo->ServiceList = ixmlDocument_getElementsByTagName( - HInfo->DescDocument, "serviceList" ); - if( !HInfo->ServiceList ) { - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice2: No services found for RootDevice\n" ); - } - - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice2: Gena Check\n" ); - //******************************* - // GENA SET UP - //******************************* - if( getServiceTable( ( IXML_Node * ) HInfo->DescDocument, - &HInfo->ServiceTable, HInfo->DescURL ) ) { - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice2: GENA Service Table\n" ); - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Here are the known services: \n" ); - printServiceTable( &HInfo->ServiceTable, UPNP_INFO, API ); - } else { - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "\nUpnpRegisterRootDevice2: Empty service table\n" ); - } - - UpnpSdkDeviceRegisteredV4 = 1; - - HandleUnlock(); - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "Exiting RegisterRootDevice2 Successfully\n" ); - - return UPNP_E_SUCCESS; -} - - -/**************************************************************************** - * Function: UpnpRegisterRootDevice3 - * - * Parameters: - * IN const char *DescUrl:Pointer to a string containing the - * description URL for this root device instance. - * IN Upnp_FunPtr Callback: Pointer to the callback function for - * receiving asynchronous events. - * IN const void *Cookie: Pointer to user data returned with the - * callback function when invoked. - * OUT UpnpDevice_Handle *Hnd: Pointer to a variable to store the - * new device handle. - * IN const int AddressFamily: Registration address family. Can be AF_INET - * or AF_INET6. - * - * Description: - * This function registers a device application with - * the UPnP Library. A device application cannot make any other API - * calls until it registers using this function. - * - * Return Values: - * UPNP_E_SUCCESS on success, nonzero on failure. - *****************************************************************************/ -int -UpnpRegisterRootDevice3( IN const char *DescUrl, - IN Upnp_FunPtr Fun, - IN const void *Cookie, - OUT UpnpDevice_Handle * Hnd, - IN const int AddressFamily ) -{ - - struct Handle_Info *HInfo; - int retVal = 0; - - if( UpnpSdkInit != 1 ) { - return UPNP_E_FINISH; - } - - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Inside UpnpRegisterRootDevice\n" ); - - HandleLock(); - if( Hnd == NULL || Fun == NULL || - DescUrl == NULL || strlen( DescUrl ) == 0 || - (AddressFamily != AF_INET && AddressFamily != AF_INET6) ) { - HandleUnlock(); - return UPNP_E_INVALID_PARAM; - } - - if( ( AddressFamily == AF_INET && UpnpSdkDeviceRegisteredV4 == 1 ) || - ( AddressFamily == AF_INET6 && UpnpSdkDeviceregisteredV6 == 1 ) ) { - HandleUnlock(); - return UPNP_E_ALREADY_REGISTERED; - } - - if( ( *Hnd = GetFreeHandle() ) == UPNP_E_OUTOF_HANDLE ) { - HandleUnlock(); - return UPNP_E_OUTOF_MEMORY; - } - - HInfo = ( struct Handle_Info * )malloc( sizeof( struct Handle_Info ) ); - if( HInfo == NULL ) { - HandleUnlock(); - return UPNP_E_OUTOF_MEMORY; - } - HandleTable[*Hnd] = HInfo; - - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Root device URL is %s\n", DescUrl ); - - HInfo->aliasInstalled = 0; - HInfo->HType = HND_DEVICE; - strcpy( HInfo->DescURL, DescUrl ); - HInfo->Callback = Fun; - HInfo->Cookie = ( void * )Cookie; - HInfo->MaxAge = DEFAULT_MAXAGE; - HInfo->DeviceList = NULL; - HInfo->ServiceList = NULL; - HInfo->DescDocument = NULL; - CLIENTONLY( ListInit( &HInfo->SsdpSearchList, NULL, NULL ); ) - CLIENTONLY( HInfo->ClientSubList = NULL; ) - HInfo->MaxSubscriptions = UPNP_INFINITE; - HInfo->MaxSubscriptionTimeOut = UPNP_INFINITE; - HInfo->DeviceAf = AddressFamily; - - if( ( retVal = - UpnpDownloadXmlDoc( HInfo->DescURL, &( HInfo->DescDocument ) ) ) - != UPNP_E_SUCCESS ) { - CLIENTONLY( ListDestroy( &HInfo->SsdpSearchList, 0 ) ); - FreeHandle( *Hnd ); - HandleUnlock(); - return retVal; - } - - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice: Valid Description\n" ); - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice: DescURL : %s\n", - HInfo->DescURL ); - - HInfo->DeviceList = - ixmlDocument_getElementsByTagName( HInfo->DescDocument, "device" ); - if( !HInfo->DeviceList ) { - CLIENTONLY( ListDestroy( &HInfo->SsdpSearchList, 0 ) ); - ixmlDocument_free( HInfo->DescDocument ); - FreeHandle( *Hnd ); - HandleUnlock(); - UpnpPrintf( UPNP_CRITICAL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice: No devices found for RootDevice\n" ); - return UPNP_E_INVALID_DESC; - } - - HInfo->ServiceList = ixmlDocument_getElementsByTagName( - HInfo->DescDocument, "serviceList" ); - if( !HInfo->ServiceList ) { - UpnpPrintf( UPNP_CRITICAL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice: No services found for RootDevice\n" ); - } - - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice: Gena Check\n" ); - //******************************* - // GENA SET UP - //******************************* - if( getServiceTable( ( IXML_Node * ) HInfo->DescDocument, - &HInfo->ServiceTable, HInfo->DescURL ) ) { - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpRegisterRootDevice: GENA Service Table \n" ); - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Here are the known services: \n" ); - printServiceTable( &HInfo->ServiceTable, UPNP_INFO, API ); - } else { - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "\nUpnpRegisterRootDevice2: Empty service table\n" ); - } - - if( AddressFamily == AF_INET ) - UpnpSdkDeviceRegisteredV4 = 1; - else - UpnpSdkDeviceregisteredV6 = 1; - - HandleUnlock(); - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Exiting RegisterRootDevice Successfully\n" ); - - return UPNP_E_SUCCESS; -} - #endif // INCLUDE_DEVICE_APIS -#ifdef INCLUDE_CLIENT_APIS - -/*****************************************************************************/ -int UpnpRegisterClient( - IN Upnp_FunPtr Fun, - IN const void *Cookie, - OUT UpnpClient_Handle *Hnd) -{ - struct Handle_Info *HInfo; - - if( UpnpSdkInit != 1 ) { - return UPNP_E_FINISH; - } - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "Inside UpnpRegisterClient \n" ); - if( Fun == NULL || Hnd == NULL ) { - return UPNP_E_INVALID_PARAM; - } - - HandleLock(); - - if( UpnpSdkClientRegistered ) { - HandleUnlock(); - return UPNP_E_ALREADY_REGISTERED; - } - if( ( *Hnd = GetFreeHandle() ) == UPNP_E_OUTOF_HANDLE ) { - HandleUnlock(); - return UPNP_E_OUTOF_MEMORY; - } - HInfo = ( struct Handle_Info * )malloc( sizeof( struct Handle_Info ) ); - if( HInfo == NULL ) { - HandleUnlock(); - return UPNP_E_OUTOF_MEMORY; - } - - HInfo->HType = HND_CLIENT; - HInfo->Callback = Fun; - HInfo->Cookie = ( void * )Cookie; - HInfo->ClientSubList = NULL; - ListInit( &HInfo->SsdpSearchList, NULL, NULL ); -#ifdef INCLUDE_DEVICE_APIS - HInfo->MaxAge = 0; - HInfo->MaxSubscriptions = UPNP_INFINITE; - HInfo->MaxSubscriptionTimeOut = UPNP_INFINITE; -#endif - - HandleTable[*Hnd] = HInfo; - UpnpSdkClientRegistered = 1; - - HandleUnlock(); - - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "Exiting UpnpRegisterClient \n" ); - - return UPNP_E_SUCCESS; -} -#endif // INCLUDE_CLIENT_APIS - - -/*****************************************************************************/ -#ifdef INCLUDE_CLIENT_APIS -int UpnpUnRegisterClient(IN UpnpClient_Handle Hnd) -{ - struct Handle_Info *HInfo; - ListNode *node = NULL; - SsdpSearchArg *searchArg = NULL; - - if( UpnpSdkInit != 1 ) { - return UPNP_E_FINISH; - } - - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "Inside UpnpUnRegisterClient \n" ); - HandleLock(); - if( !UpnpSdkClientRegistered ) { - HandleUnlock(); - return UPNP_E_INVALID_HANDLE; - } - HandleUnlock(); - -#if EXCLUDE_GENA == 0 - if( genaUnregisterClient( Hnd ) != UPNP_E_SUCCESS ) - return UPNP_E_INVALID_HANDLE; -#endif - HandleLock(); - if( GetHandleInfo( Hnd, &HInfo ) == UPNP_E_INVALID_HANDLE ) { - HandleUnlock(); - return UPNP_E_INVALID_HANDLE; - } - //clean up search list - node = ListHead( &HInfo->SsdpSearchList ); - while( node != NULL ) { - searchArg = ( SsdpSearchArg * ) node->item; - if( searchArg ) { - free( searchArg->searchTarget ); - free( searchArg ); - } - ListDelNode( &HInfo->SsdpSearchList, node, 0 ); - node = ListHead( &HInfo->SsdpSearchList ); - } - - ListDestroy( &HInfo->SsdpSearchList, 0 ); - FreeHandle( Hnd ); - UpnpSdkClientRegistered = 0; - HandleUnlock(); - UpnpPrintf( UPNP_ALL, API, __FILE__, __LINE__, - "Exiting UpnpUnRegisterClient \n" ); - return UPNP_E_SUCCESS; - -} -#endif // INCLUDE_CLIENT_APIS //----------------------------------------------------------------------------- //