Asterisk data retrieval API.

This module implements an abstraction for retrieving and exporting
asterisk data.
Developed by:
	Brett Bryant <brettbryant@gmail.com>
	Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
For the Google Summer of code 2009 Project.
Documentation can be found in doxygen format and inside the
header include/asterisk/data.h

Review: https://reviewboard.asterisk.org/r/275/



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@258517 65c4cc65-6c06-0410-ace0-fbb531ad65f3

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