diff options
Diffstat (limited to 'include/asterisk/xml.h')
-rw-r--r-- | include/asterisk/xml.h | 176 |
1 files changed, 130 insertions, 46 deletions
diff --git a/include/asterisk/xml.h b/include/asterisk/xml.h index 2c30986cc..836a4f386 100644 --- a/include/asterisk/xml.h +++ b/include/asterisk/xml.h @@ -18,33 +18,76 @@ #define _ASTERISK_XML_H /*! \file - * \brief Asterisk XML abstraction layer + * \brief Asterisk XML abstraction layer */ struct ast_xml_node; struct ast_xml_doc; -/*! \brief Initialize the XML library implementation. +/*! + * \brief Initialize the XML library implementation. * This function is used to setup everything needed * to start working with the xml implementation. - * \retval 0 On success. - * \retval 1 On error. + * \retval 0 On success. + * \retval 1 On error. */ int ast_xml_init(void); -/*! \brief Cleanup library allocated global data. - * \retval 0 On success. - * \retval 1 On error. +/*! + * \brief Cleanup library allocated global data. + * \retval 0 On success. + * \retval 1 On error. */ int ast_xml_finish(void); -/*! \brief Open an XML document. - * \param filename Document path. - * \retval NULL on error. - * \retval The ast_xml_doc reference to the open document. +/*! + * \brief Open an XML document. + * \param filename Document path. + * \retval NULL on error. + * \retval The ast_xml_doc reference to the open document. */ struct ast_xml_doc *ast_xml_open(char *filename); +/*! + * \brief Create a XML document. + * \retval NULL on error. + * \retval non-NULL The allocated document structure. + */ +struct ast_xml_doc *ast_xml_new(void); + +/*! + * \brief Create a XML node. + * \param name The name of the node to be created. + * \retval NULL on error. + * \retval non-NULL The allocated node structe. + */ +struct ast_xml_node *ast_xml_new_node(const char *name); + +/*! + * \brief Add a child node inside a passed parent node. + * \param parent The pointer of the parent node. + * \param child_name The name of the child node to add. + * \retval NULL on error. + * \retval non-NULL The created child node pointer. + */ +struct ast_xml_node *ast_xml_new_child(struct ast_xml_node *parent, const char *child_name); + +/*! + * \brief Add a child node, to a specified parent node. + * \param parent Where to add the child node. + * \param child The child node to add. + * \retval NULL on error. + * \retval non-NULL The add child node on success. + */ +struct ast_xml_node *ast_xml_add_child(struct ast_xml_node *parent, struct ast_xml_node *child); + +/*! + * \brief Close an already open document and free the used + * structure. + * \retval doc The document reference. + */ +void ast_xml_close(struct ast_xml_doc *doc); + /*! \brief Open an XML document that resides in memory. * \param buffer The address where the document is stored * \size The number of bytes in the document @@ -53,76 +96,117 @@ struct ast_xml_doc *ast_xml_open(char *filename); */ struct ast_xml_doc *ast_xml_read_memory(char *buffer, size_t size); -/*! \brief Close an already open document and free the used - * structure. - * \retval doc The document reference. +/*! + * \brief Specify the root node of a XML document. + * \param doc The document pointer. + * \param node A pointer to the node we want to set as root node. */ -void ast_xml_close(struct ast_xml_doc *doc); +void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node); -/*! \brief Get the document root node. - * \param doc Document reference - * \retval NULL on error - * \retval The root node on success. +/*! + * \brief Get the document root node. + * \param doc Document reference + * \retval NULL on error + * \retval The root node on success. */ struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc); -/*! \brief Free node - * \param node Node to be released. +/*! + * \brief Free node + * \param node Node to be released. */ void ast_xml_free_node(struct ast_xml_node *node); -/*! \brief Free an attribute returned by ast_xml_get_attribute() - * \param data pointer to be freed. +/*! + * \brief Free an attribute returned by ast_xml_get_attribute() + * \param data pointer to be freed. */ void ast_xml_free_attr(const char *attribute); -/*! \brief Free a content element that was returned by ast_xml_get_text() - * \param text text to be freed. +/*! + * \brief Get the document based on a node. + * \param node A node that is part of the dom. + * \returns The dom pointer where this node resides. + */ +struct ast_xml_doc *ast_xml_get_doc(struct ast_xml_node *node); + +/*! + * \brief Free a content element that was returned by ast_xml_get_text() + * \param text text to be freed. */ void ast_xml_free_text(const char *text); -/*! \brief Get a node attribute by name - * \param node Node where to search the attribute. - * \param attrname Attribute name. - * \retval NULL on error - * \retval The attribute value on success. +/*! + * \brief Get a node attribute by name + * \param node Node where to search the attribute. + * \param attrname Attribute name. + * \retval NULL on error + * \retval The attribute value on success. */ const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname); -/*! \brief Find a node element by name. - * \param node This is the node starting point. - * \param name Node name to find. - * \param attrname attribute name to match (if NULL it won't be matched). - * \param attrvalue attribute value to match (if NULL it won't be matched). - * \retval NULL if not found - * \retval The node on success. +/*! + * \brief Set an attribute to a node. + * \param node In which node we want to insert the attribute. + * \param name The attribute name. + * \param value The attribute value. + * \retval 0 on success. + * \retval -1 on error. + */ +int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const char *value); + +/*! + * \brief Find a node element by name. + * \param node This is the node starting point. + * \param name Node name to find. + * \param attrname attribute name to match (if NULL it won't be matched). + * \param attrvalue attribute value to match (if NULL it won't be matched). + * \retval NULL if not found + * \retval The node on success. */ struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue); struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name); const char *ast_xml_get_ns_href(struct ast_xml_ns *ns); -/*! \brief Get an element content string. - * \param node Node from where to get the string. - * \retval NULL on error. - * \retval The text content of node. +/*! + * \brief Get an element content string. + * \param node Node from where to get the string. + * \retval NULL on error. + * \retval The text content of node. */ const char *ast_xml_get_text(struct ast_xml_node *node); -/*! \brief Get the name of a node. */ +/*! + * \brief Set an element content string. + * \param node Node from where to set the content string. + * \param content The text to insert in the node. + */ +void ast_xml_set_text(struct ast_xml_node *node, const char *content); + +/*! + * \brief Get the name of a node. */ const char *ast_xml_node_get_name(struct ast_xml_node *node); -/*! \brief Get the node's children. */ +/*! + * \brief Get the node's children. */ struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node); -/*! \brief Get the next node in the same level. */ +/*! + * \brief Get the next node in the same level. */ struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node); -/*! \brief Get the previous node in the same leve. */ +/*! + * \brief Get the previous node in the same leve. */ struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node); -/*! \brief Get the parent of a specified node. */ +/*! + * \brief Get the parent of a specified node. */ struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node); +/*! + * \brief Dump the specified document to a file. */ +int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc); + /* Features using ast_xml_ */ #ifdef HAVE_LIBXML2 #define AST_XML_DOCS |