Thu Apr 28 2011 17:13:36

Asterisk developer's documentation


xml.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
00005  *
00006  * See http://www.asterisk.org for more information about
00007  * the Asterisk project. Please do not directly contact
00008  * any of the maintainers of this project for assistance;
00009  * the project provides a web site, mailing lists and IRC
00010  * channels for your use.
00011  *
00012  * This program is free software, distributed under the terms of
00013  * the GNU General Public License Version 2. See the LICENSE file
00014  * at the top of the source tree.
00015  */
00016 
00017 #ifndef _ASTERISK_XML_H
00018 #define _ASTERISK_XML_H
00019 
00020 /*! \file
00021  *  \brief Asterisk XML abstraction layer
00022  */
00023 
00024 struct ast_xml_node;
00025 struct ast_xml_doc;
00026 
00027 /*! \brief Initialize the XML library implementation.
00028  *         This function is used to setup everything needed
00029  *         to start working with the xml implementation.
00030  *  \retval 0 On success.
00031  *  \retval 1 On error.
00032  */
00033 int ast_xml_init(void);
00034 
00035 /*! \brief Cleanup library allocated global data.
00036  *  \retval 0 On success.
00037  *  \retval 1 On error.
00038  */
00039 int ast_xml_finish(void);
00040 
00041 /*! \brief Open an XML document.
00042  *  \param filename Document path.
00043  *  \retval NULL on error.
00044  *  \retval The ast_xml_doc reference to the open document.
00045  */
00046 struct ast_xml_doc *ast_xml_open(char *filename);
00047 
00048 /*! \brief Close an already open document and free the used
00049  *        structure.
00050  *  \retval doc The document reference.
00051  */
00052 void ast_xml_close(struct ast_xml_doc *doc);
00053 
00054 /*! \brief Get the document root node.
00055  *  \param doc Document reference
00056  *  \retval NULL on error
00057  *  \retval The root node on success.
00058  */
00059 struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc);
00060 
00061 /*! \brief Free node
00062  *  \param node Node to be released.
00063  */
00064 void ast_xml_free_node(struct ast_xml_node *node);
00065 
00066 /*! \brief Free an attribute returned by ast_xml_get_attribute()
00067  *  \param data pointer to be freed.
00068  */
00069 void ast_xml_free_attr(const char *attribute);
00070 
00071 /*! \brief Free a content element that was returned by ast_xml_get_text()
00072  *  \param text text to be freed.
00073  */
00074 void ast_xml_free_text(const char *text);
00075 
00076 /*! \brief Get a node attribute by name
00077  *  \param node Node where to search the attribute.
00078  *  \param attrname Attribute name.
00079  *  \retval NULL on error
00080  *  \retval The attribute value on success.
00081  */
00082 const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname);
00083 
00084 /*! \brief Find a node element by name.
00085  *  \param node This is the node starting point.
00086  *  \param name Node name to find.
00087  *  \param attrname attribute name to match (if NULL it won't be matched).
00088  *  \param attrvalue attribute value to match (if NULL it won't be matched).
00089  *  \retval NULL if not found
00090  *  \retval The node on success.
00091  */
00092 struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
00093 
00094 /*! \brief Get an element content string.
00095  *  \param node Node from where to get the string.
00096  *  \retval NULL on error.
00097  *  \retval The text content of node.
00098  */
00099 const char *ast_xml_get_text(struct ast_xml_node *node);
00100 
00101 /*! \brief Get the name of a node. */
00102 const char *ast_xml_node_get_name(struct ast_xml_node *node);
00103 
00104 /*! \brief Get the node's children. */
00105 struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node);
00106 
00107 /*! \brief Get the next node in the same level. */
00108 struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node);
00109 
00110 /*! \brief Get the previous node in the same leve. */
00111 struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node);
00112 
00113 /*! \brief Get the parent of a specified node. */
00114 struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
00115 
00116 /* Features using ast_xml_ */
00117 #ifdef HAVE_LIBXML2
00118 #define AST_XML_DOCS
00119 #endif
00120 
00121 #endif /* _ASTERISK_XML_H */
00122