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 /*! 00028 * \brief Initialize the XML library implementation. 00029 * This function is used to setup everything needed 00030 * to start working with the xml implementation. 00031 * \retval 0 On success. 00032 * \retval 1 On error. 00033 */ 00034 int ast_xml_init(void); 00035 00036 /*! 00037 * \brief Cleanup library allocated global data. 00038 * \retval 0 On success. 00039 * \retval 1 On error. 00040 */ 00041 int ast_xml_finish(void); 00042 00043 /*! 00044 * \brief Open an XML document. 00045 * \param filename Document path. 00046 * \retval NULL on error. 00047 * \retval The ast_xml_doc reference to the open document. 00048 */ 00049 struct ast_xml_doc *ast_xml_open(char *filename); 00050 00051 /*! 00052 * \brief Create a XML document. 00053 * \retval NULL on error. 00054 * \retval non-NULL The allocated document structure. 00055 */ 00056 struct ast_xml_doc *ast_xml_new(void); 00057 00058 /*! 00059 * \brief Create a XML node. 00060 * \param name The name of the node to be created. 00061 * \retval NULL on error. 00062 * \retval non-NULL The allocated node structe. 00063 */ 00064 struct ast_xml_node *ast_xml_new_node(const char *name); 00065 00066 /*! 00067 * \brief Add a child node inside a passed parent node. 00068 * \param parent The pointer of the parent node. 00069 * \param child_name The name of the child node to add. 00070 * \retval NULL on error. 00071 * \retval non-NULL The created child node pointer. 00072 */ 00073 struct ast_xml_node *ast_xml_new_child(struct ast_xml_node *parent, const char *child_name); 00074 00075 /*! 00076 * \brief Add a child node, to a specified parent node. 00077 * \param parent Where to add the child node. 00078 * \param child The child node to add. 00079 * \retval NULL on error. 00080 * \retval non-NULL The add child node on success. 00081 */ 00082 struct ast_xml_node *ast_xml_add_child(struct ast_xml_node *parent, struct ast_xml_node *child); 00083 00084 /*! 00085 * \brief Close an already open document and free the used 00086 * structure. 00087 * \retval doc The document reference. 00088 */ 00089 void ast_xml_close(struct ast_xml_doc *doc); 00090 00091 /*! \brief Open an XML document that resides in memory. 00092 * \param buffer The address where the document is stored 00093 * \param size The number of bytes in the document 00094 * \retval NULL on error. 00095 * \retval The ast_xml_doc reference to the open document. 00096 */ 00097 struct ast_xml_doc *ast_xml_read_memory(char *buffer, size_t size); 00098 00099 /*! 00100 * \brief Specify the root node of a XML document. 00101 * \param doc The document pointer. 00102 * \param node A pointer to the node we want to set as root node. 00103 */ 00104 void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node); 00105 00106 /*! 00107 * \brief Get the document root node. 00108 * \param doc Document reference 00109 * \retval NULL on error 00110 * \retval The root node on success. 00111 */ 00112 struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc); 00113 00114 /*! 00115 * \brief Free node 00116 * \param node Node to be released. 00117 */ 00118 void ast_xml_free_node(struct ast_xml_node *node); 00119 00120 /*! 00121 * \brief Free an attribute returned by ast_xml_get_attribute() 00122 * \param attribute pointer to be freed. 00123 */ 00124 void ast_xml_free_attr(const char *attribute); 00125 00126 /*! 00127 * \brief Get the document based on a node. 00128 * \param node A node that is part of the dom. 00129 * \returns The dom pointer where this node resides. 00130 */ 00131 struct ast_xml_doc *ast_xml_get_doc(struct ast_xml_node *node); 00132 00133 /*! 00134 * \brief Free a content element that was returned by ast_xml_get_text() 00135 * \param text text to be freed. 00136 */ 00137 void ast_xml_free_text(const char *text); 00138 00139 /*! 00140 * \brief Get a node attribute by name 00141 * \param node Node where to search the attribute. 00142 * \param attrname Attribute name. 00143 * \retval NULL on error 00144 * \retval The attribute value on success. 00145 */ 00146 const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname); 00147 00148 /*! 00149 * \brief Set an attribute to a node. 00150 * \param node In which node we want to insert the attribute. 00151 * \param name The attribute name. 00152 * \param value The attribute value. 00153 * \retval 0 on success. 00154 * \retval -1 on error. 00155 */ 00156 int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const char *value); 00157 00158 /*! 00159 * \brief Find a node element by name. 00160 * \param root_node This is the node starting point. 00161 * \param name Node name to find. 00162 * \param attrname attribute name to match (if NULL it won't be matched). 00163 * \param attrvalue attribute value to match (if NULL it won't be matched). 00164 * \retval NULL if not found. 00165 * \retval The node on success. 00166 */ 00167 struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue); 00168 struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name); 00169 const char *ast_xml_get_ns_href(struct ast_xml_ns *ns); 00170 00171 /*! 00172 * \brief Get an element content string. 00173 * \param node Node from where to get the string. 00174 * \retval NULL on error. 00175 * \retval The text content of node. 00176 */ 00177 const char *ast_xml_get_text(struct ast_xml_node *node); 00178 00179 /*! 00180 * \brief Set an element content string. 00181 * \param node Node from where to set the content string. 00182 * \param content The text to insert in the node. 00183 */ 00184 void ast_xml_set_text(struct ast_xml_node *node, const char *content); 00185 00186 /*! 00187 * \brief Get the name of a node. */ 00188 const char *ast_xml_node_get_name(struct ast_xml_node *node); 00189 00190 /*! 00191 * \brief Get the node's children. */ 00192 struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node); 00193 00194 /*! 00195 * \brief Get the next node in the same level. */ 00196 struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node); 00197 00198 /*! 00199 * \brief Get the previous node in the same leve. */ 00200 struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node); 00201 00202 /*! 00203 * \brief Get the parent of a specified node. */ 00204 struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node); 00205 00206 /*! 00207 * \brief Dump the specified document to a file. */ 00208 int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc); 00209 00210 /* Features using ast_xml_ */ 00211 #ifdef HAVE_LIBXML2 00212 #define AST_XML_DOCS 00213 #endif 00214 00215 #endif /* _ASTERISK_XML_H */ 00216