Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


xml.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16 
17 #ifndef _ASTERISK_XML_H
18 #define _ASTERISK_XML_H
19 
20 /*! \file
21  * \brief Asterisk XML abstraction layer
22  */
23 
24 struct ast_xml_node;
25 struct ast_xml_doc;
26 
27 /*!
28  * \brief Initialize the XML library implementation.
29  * This function is used to setup everything needed
30  * to start working with the xml implementation.
31  * \retval 0 On success.
32  * \retval 1 On error.
33  */
34 int ast_xml_init(void);
35 
36 /*!
37  * \brief Cleanup library allocated global data.
38  * \retval 0 On success.
39  * \retval 1 On error.
40  */
41 int ast_xml_finish(void);
42 
43 /*!
44  * \brief Open an XML document.
45  * \param filename Document path.
46  * \retval NULL on error.
47  * \retval The ast_xml_doc reference to the open document.
48  */
49 struct ast_xml_doc *ast_xml_open(char *filename);
50 
51 /*!
52  * \brief Create a XML document.
53  * \retval NULL on error.
54  * \retval non-NULL The allocated document structure.
55  */
56 struct ast_xml_doc *ast_xml_new(void);
57 
58 /*!
59  * \brief Create a XML node.
60  * \param name The name of the node to be created.
61  * \retval NULL on error.
62  * \retval non-NULL The allocated node structe.
63  */
64 struct ast_xml_node *ast_xml_new_node(const char *name);
65 
66 /*!
67  * \brief Add a child node inside a passed parent node.
68  * \param parent The pointer of the parent node.
69  * \param child_name The name of the child node to add.
70  * \retval NULL on error.
71  * \retval non-NULL The created child node pointer.
72  */
73 struct ast_xml_node *ast_xml_new_child(struct ast_xml_node *parent, const char *child_name);
74 
75 /*!
76  * \brief Add a child node, to a specified parent node.
77  * \param parent Where to add the child node.
78  * \param child The child node to add.
79  * \retval NULL on error.
80  * \retval non-NULL The add child node on success.
81  */
82 struct ast_xml_node *ast_xml_add_child(struct ast_xml_node *parent, struct ast_xml_node *child);
83 
84 /*!
85  * \brief Close an already open document and free the used
86  * structure.
87  * \retval doc The document reference.
88  */
89 void ast_xml_close(struct ast_xml_doc *doc);
90 
91 /*! \brief Open an XML document that resides in memory.
92  * \param buffer The address where the document is stored
93  * \param size The number of bytes in the document
94  * \retval NULL on error.
95  * \retval The ast_xml_doc reference to the open document.
96  */
97 struct ast_xml_doc *ast_xml_read_memory(char *buffer, size_t size);
98 
99 /*!
100  * \brief Specify the root node of a XML document.
101  * \param doc The document pointer.
102  * \param node A pointer to the node we want to set as root node.
103  */
104 void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node);
105 
106 /*!
107  * \brief Get the document root node.
108  * \param doc Document reference
109  * \retval NULL on error
110  * \retval The root node on success.
111  */
112 struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc);
113 
114 /*!
115  * \brief Free node
116  * \param node Node to be released.
117  */
118 void ast_xml_free_node(struct ast_xml_node *node);
119 
120 /*!
121  * \brief Free an attribute returned by ast_xml_get_attribute()
122  * \param attribute pointer to be freed.
123  */
124 void ast_xml_free_attr(const char *attribute);
125 
126 /*!
127  * \brief Get the document based on a node.
128  * \param node A node that is part of the dom.
129  * \returns The dom pointer where this node resides.
130  */
131 struct ast_xml_doc *ast_xml_get_doc(struct ast_xml_node *node);
132 
133 /*!
134  * \brief Free a content element that was returned by ast_xml_get_text()
135  * \param text text to be freed.
136  */
137 void ast_xml_free_text(const char *text);
138 
139 /*!
140  * \brief Get a node attribute by name
141  * \param node Node where to search the attribute.
142  * \param attrname Attribute name.
143  * \retval NULL on error
144  * \retval The attribute value on success.
145  */
146 const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname);
147 
148 /*!
149  * \brief Set an attribute to a node.
150  * \param node In which node we want to insert the attribute.
151  * \param name The attribute name.
152  * \param value The attribute value.
153  * \retval 0 on success.
154  * \retval -1 on error.
155  */
156 int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const char *value);
157 
158 /*!
159  * \brief Find a node element by name.
160  * \param root_node This is the node starting point.
161  * \param name Node name to find.
162  * \param attrname attribute name to match (if NULL it won't be matched).
163  * \param attrvalue attribute value to match (if NULL it won't be matched).
164  * \retval NULL if not found.
165  * \retval The node on success.
166  */
167 struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
168 struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name);
169 const char *ast_xml_get_ns_href(struct ast_xml_ns *ns);
170 
171 /*!
172  * \brief Get an element content string.
173  * \param node Node from where to get the string.
174  * \retval NULL on error.
175  * \retval The text content of node.
176  */
177 const char *ast_xml_get_text(struct ast_xml_node *node);
178 
179 /*!
180  * \brief Set an element content string.
181  * \param node Node from where to set the content string.
182  * \param content The text to insert in the node.
183  */
184 void ast_xml_set_text(struct ast_xml_node *node, const char *content);
185 
186 /*!
187  * \brief Get the name of a node. */
188 const char *ast_xml_node_get_name(struct ast_xml_node *node);
189 
190 /*!
191  * \brief Get the node's children. */
192 struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node);
193 
194 /*!
195  * \brief Get the next node in the same level. */
196 struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node);
197 
198 /*!
199  * \brief Get the previous node in the same leve. */
200 struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node);
201 
202 /*!
203  * \brief Get the parent of a specified node. */
204 struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
205 
206 /*!
207  * \brief Dump the specified document to a file. */
208 int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc);
209 
210 /* Features using ast_xml_ */
211 #ifdef HAVE_LIBXML2
212 #define AST_XML_DOCS
213 #endif
214 
215 #endif /* _ASTERISK_XML_H */
216 
int ast_xml_init(void)
Initialize the XML library implementation. This function is used to setup everything needed to start ...
Definition: xml.c:41
const char * ast_xml_get_ns_href(struct ast_xml_ns *ns)
Definition: xml.c:266
struct ast_xml_doc * ast_xml_open(char *filename)
Open an XML document.
Definition: xml.c:55
struct ast_xml_doc * ast_xml_new(void)
Create a XML document.
Definition: xml.c:75
void ast_xml_free_node(struct ast_xml_node *node)
Free node.
Definition: xml.c:166
struct ast_xml_node * ast_xml_add_child(struct ast_xml_node *parent, struct ast_xml_node *child)
Add a child node, to a specified parent node.
Definition: xml.c:107
int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc)
Dump the specified document to a file.
Definition: xml.c:289
char * text
Definition: app_queue.c:1091
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:153
int value
Definition: syslog.c:39
struct ast_xml_node * ast_xml_new_child(struct ast_xml_node *parent, const char *child_name)
Add a child node inside a passed parent node.
Definition: xml.c:95
struct ast_xml_doc * ast_xml_get_doc(struct ast_xml_node *node)
Get the document based on a node.
Definition: xml.c:252
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:190
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:176
struct ast_xml_node * ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue)
Find a node element by name.
Definition: xml.c:220
struct ast_xml_node * ast_xml_new_node(const char *name)
Create a XML node.
Definition: xml.c:83
void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node)
Specify the root node of a XML document.
Definition: xml.c:144
void ast_xml_set_text(struct ast_xml_node *node, const char *content)
Set an element content string.
Definition: xml.c:280
struct ast_xml_node * ast_xml_node_get_parent(struct ast_xml_node *node)
Get the parent of a specified node.
Definition: xml.c:314
static const char name[]
void ast_xml_close(struct ast_xml_doc *doc)
Close an already open document and free the used structure.
Definition: xml.c:134
int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const char *value)
Set an attribute to a node.
Definition: xml.c:207
const char * ast_xml_get_text(struct ast_xml_node *node)
Get an element content string.
Definition: xml.c:271
struct ast_xml_node * ast_xml_node_get_prev(struct ast_xml_node *node)
Get the previous node in the same leve.
Definition: xml.c:309
struct ast_xml_doc * ast_xml_read_memory(char *buffer, size_t size)
Open an XML document that resides in memory.
Definition: xml.c:115
struct ast_xml_ns * ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name)
Definition: xml.c:261
struct ast_xml_node * ast_xml_node_get_next(struct ast_xml_node *node)
Get the next node in the same level.
Definition: xml.c:304
int ast_xml_finish(void)
Cleanup library allocated global data.
Definition: xml.c:48
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:299
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:294
void ast_xml_free_text(const char *text)
Free a content element that was returned by ast_xml_get_text()
Definition: xml.c:183