Fri Aug 17 00:17:20 2018

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 /*!
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 

Generated on 17 Aug 2018 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1