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