Asterisk - The Open Source Telephony Project  21.4.1
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 #include "asterisk/vector.h"
25 
26 struct ast_xml_node;
27 struct ast_xml_doc;
28 struct ast_xml_xpath_results;
29 struct ast_xslt_doc;
30 
31 /*!
32  * \brief Initialize the XML library implementation.
33  * This function is used to setup everything needed
34  * to start working with the xml implementation.
35  * \retval 0 On success.
36  * \retval 1 On error.
37  */
38 int ast_xml_init(void);
39 
40 /*!
41  * \brief Cleanup library allocated global data.
42  * \retval 0 On success.
43  * \retval 1 On error.
44  */
45 int ast_xml_finish(void);
46 
47 /*!
48  * \brief Open an XML document.
49  * \param filename Document path.
50  * \retval NULL on error.
51  * \return The ast_xml_doc reference to the open document.
52  */
53 struct ast_xml_doc *ast_xml_open(char *filename);
54 
55 /*!
56  * \brief Create a XML document.
57  * \retval NULL on error.
58  * \retval non-NULL The allocated document structure.
59  */
60 struct ast_xml_doc *ast_xml_new(void);
61 
62 /*!
63  * \brief Create a XML node.
64  * \param name The name of the node to be created.
65  * \retval NULL on error.
66  * \retval non-NULL The allocated node structe.
67  */
68 struct ast_xml_node *ast_xml_new_node(const char *name);
69 
70 /*!
71  * \brief Add a child node inside a passed parent node.
72  * \param parent The pointer of the parent node.
73  * \param child_name The name of the child node to add.
74  * \retval NULL on error.
75  * \retval non-NULL The created child node pointer.
76  */
77 struct ast_xml_node *ast_xml_new_child(struct ast_xml_node *parent, const char *child_name);
78 
79 /*!
80  * \brief Add a child node, to a specified parent node.
81  * \param parent Where to add the child node.
82  * \param child The child node to add.
83  * \retval NULL on error.
84  * \retval non-NULL The add child node on success.
85  */
86 struct ast_xml_node *ast_xml_add_child(struct ast_xml_node *parent, struct ast_xml_node *child);
87 
88 /*!
89  * \brief Add a list of child nodes, to a specified parent node.
90  * \param parent Where to add the child node.
91  * \param child The child list to add.
92  * \retval NULL on error.
93  * \retval non-NULL The added child list on success.
94  */
95 struct ast_xml_node *ast_xml_add_child_list(struct ast_xml_node *parent, struct ast_xml_node *child);
96 
97 /*!
98  * \brief Create a copy of a n ode list.
99  * \param list The list to copy.
100  * \retval NULL on error.
101  * \retval non-NULL The copied list.
102  */
103 struct ast_xml_node *ast_xml_copy_node_list(struct ast_xml_node *list);
104 
105 /*!
106  * \brief Close an already open document and free the used
107  * structure.
108  * \param doc XML Document to close
109  */
110 void ast_xml_close(struct ast_xml_doc *doc);
111 
112 /*! \brief Open an XML document that resides in memory.
113  * \param buffer The address where the document is stored
114  * \param size The number of bytes in the document
115  * \retval NULL on error.
116  * \return The ast_xml_doc reference to the open document.
117  */
118 struct ast_xml_doc *ast_xml_read_memory(char *buffer, size_t size);
119 
120 /*!
121  * \brief Specify the root node of a XML document.
122  * \param doc XML Document reference
123  * \param node A pointer to the node we want to set as root node.
124  */
125 void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node);
126 
127 /*!
128  * \brief Get the document root node.
129  * \param doc XML Document reference
130  * \retval NULL on error
131  * \return The root node on success.
132  */
133 struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc);
134 
135 /*!
136  * \brief Free node
137  * \param node Node to be released.
138  */
139 void ast_xml_free_node(struct ast_xml_node *node);
140 
141 /*!
142  * \brief Free an attribute returned by ast_xml_get_attribute()
143  * \param attribute pointer to be freed.
144  */
145 void ast_xml_free_attr(const char *attribute);
146 
147 /*!
148  * \brief Get the document based on a node.
149  * \param node A node that is part of the dom.
150  * \return The dom pointer where this node resides.
151  */
152 struct ast_xml_doc *ast_xml_get_doc(struct ast_xml_node *node);
153 
154 /*!
155  * \brief Free a content element that was returned by ast_xml_get_text()
156  * \param text text to be freed.
157  */
158 void ast_xml_free_text(const char *text);
159 
160 /*!
161  * \brief Get a node attribute by name
162  * \param node Node where to search the attribute.
163  * \param attrname Attribute name.
164  * \retval NULL on error
165  * \return The attribute value on success.
166  * \note The result must be freed with ast_xml_free_attr().
167  */
168 const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname);
169 
170 /*!
171  * \brief Set an attribute to a node.
172  * \param node In which node we want to insert the attribute.
173  * \param name The attribute name.
174  * \param value The attribute value.
175  * \retval 0 on success.
176  * \retval -1 on error.
177  */
178 int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const char *value);
179 
180 /*!
181  * \brief Find a node element by name.
182  * \param root_node This is the node starting point.
183  * \param name Node name to find.
184  * \param attrname attribute name to match (if NULL it won't be matched).
185  * \param attrvalue attribute value to match (if NULL it won't be matched).
186  * \retval NULL if not found.
187  * \return The node on success.
188  */
189 struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
190 struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name);
191 
192 /*!
193  * \brief Find a direct child element by name.
194  * \param _parent_node This is the parent node to search.
195  * \param _name Node name to find.
196  * \param _attrname attribute name to match (if NULL it won't be matched).
197  * \param _attrvalue attribute value to match (if NULL it won't be matched).
198  * \retval NULL if not found.
199  * \return The node on success.
200  */
201 #define ast_xml_find_child_element(_parent_node, _name, _attrname, _attrvalue) \
202  ast_xml_find_element(ast_xml_node_get_children(_parent_node), _name, _attrname, _attrvalue)
203 
204 /*!
205  * \brief Get the prefix of a namespace.
206  * \param ns The namespace
207  * \return The prefix of the namespace.
208  */
209 const char *ast_xml_get_ns_prefix(struct ast_xml_ns *ns);
210 
211 /*!
212  * \brief Get the href of a namespace.
213  * \param ns The namespace
214  * \return The href of the namespace.
215  */
216 const char *ast_xml_get_ns_href(struct ast_xml_ns *ns);
217 
218 /*!
219  * \brief Get an element content string.
220  * \param node Node from where to get the string.
221  * \retval NULL on error.
222  * \return The text content of node.
223  */
224 const char *ast_xml_get_text(struct ast_xml_node *node);
225 
226 /*!
227  * \brief Set an element content string.
228  * \param node Node from where to set the content string.
229  * \param content The text to insert in the node.
230  */
231 void ast_xml_set_text(struct ast_xml_node *node, const char *content);
232 
233 /*!
234  * \brief Set or reset an element's name.
235  * \param node Node whose name is to be set.
236  * \param name New name.
237  */
238 void ast_xml_set_name(struct ast_xml_node *node, const char *name);
239 
240 /*!
241  * \brief Get the name of a node. */
242 const char *ast_xml_node_get_name(struct ast_xml_node *node);
243 
244 /*!
245  * \brief Get the node's children. */
246 struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node);
247 
248 /*!
249  * \brief Get the next node in the same level. */
250 struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node);
251 
252 /*!
253  * \brief Get the previous node in the same leve. */
254 struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node);
255 
256 /*!
257  * \brief Get the parent of a specified node. */
258 struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
259 
260 /*!
261  * \brief Dump the specified document to a file. */
262 int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc);
263 
264 /*!
265  * \brief Dump the specified document to a buffer
266  *
267  * \param doc The XML doc to dump
268  * \param buffer A pointer to a char * to receive the address of the results
269  * \param length A pointer to an int to receive the length of the results
270  *
271  * \note The result buffer must be freed with ast_xml_free_text().
272  */
273 void ast_xml_doc_dump_memory(struct ast_xml_doc *doc, char **buffer, int *length);
274 
275 /*!
276  * \brief Free the XPath results
277  * \param results The XPath results object to dispose of
278  *
279  * \since 12
280  */
281 void ast_xml_xpath_results_free(struct ast_xml_xpath_results *results);
282 
283 /*!
284  * \brief Return the number of results from an XPath query
285  * \param results The XPath results object to count
286  * \return The number of results in the XPath object
287  *
288  * \since 12
289  */
290 int ast_xml_xpath_num_results(struct ast_xml_xpath_results *results);
291 
292 /*!
293  * \brief Return the first result node of an XPath query
294  * \param results The XPath results object to get the first result from
295  * \return The first result in the XPath object on success
296  * \retval NULL on error
297  *
298  * \since 12
299  */
300 struct ast_xml_node *ast_xml_xpath_get_first_result(struct ast_xml_xpath_results *results);
301 
302 /*!
303  * \brief Return a specific result node of an XPath query
304  * \param results The XPath results object to get the result from
305  * \param n The index of the result to get
306  * \return The nth result in the XPath object on success
307  * \retval NULL on error
308  */
309 struct ast_xml_node *ast_xml_xpath_get_result(struct ast_xml_xpath_results *results, int n);
310 
311 /*!
312  * \brief Execute an XPath query on an XML document
313  * \param doc XML document to query
314  * \param xpath_str The XPath query string to execute on the document
315  * \return An object containing the results of the XPath query on success
316  * \retval NULL on failure
317  *
318  * \since 12
319  */
320 struct ast_xml_xpath_results *ast_xml_query(struct ast_xml_doc *doc, const char *xpath_str);
321 
322 /*!
323  * \brief Namespace definition
324  */
326  const char *prefix;
327  const char *href;
328 };
329 
331 
332 /*!
333  * \brief Execute an XPath query on an XML document with namespaces
334  * \param doc XML document to query
335  * \param xpath_str The XPath query string to execute on the document
336  * \param namespaces A vector of ast_xml_namespace structures (not pointers)
337  * \return An object containing the results of the XPath query on success
338  * \retval NULL on failure
339  */
340 struct ast_xml_xpath_results *ast_xml_query_with_namespaces(struct ast_xml_doc *doc, const char *xpath_str,
341  struct ast_xml_namespace_def_vector *namespaces);
342 
343 #ifdef HAVE_LIBXSLT
344 
345 /*! \brief Open an XSLT document that resides in memory.
346  *
347  * \param buffer The address where the stylesheet is stored
348  * \param size The number of bytes in the stylesheet
349  *
350  * \return The stylesheet document. Must be closed with ast_xslt_close().
351  */
352 struct ast_xslt_doc *ast_xslt_read_memory(char *buffer, size_t size);
353 
354 /*!
355  * \brief Open an XSLT document.
356  *
357  * \param filename stylesheet path.
358  *
359  * \return The stylesheet document. Must be closed with ast_xslt_close().
360  */
361 struct ast_xslt_doc *ast_xslt_open(char *filename);
362 
363 /*!
364  * \brief Close a stylesheet document and free its resources.
365  *
366  * \param xslt XSLT stylesheet to close
367  */
368 void ast_xslt_close(struct ast_xslt_doc *xslt);
369 
370 /*!
371  * \brief Apply an XSLT stylesheet to an XML document
372  *
373  * \param xslt XSLT stylesheet to apply.
374  * \param doc XML document the stylesheet will be applied to.
375  * \param params An array of name value pairs to pass as parameters
376  * The array must terminate with a NULL sentinel.
377  * Example: { "name1", "value1", "name2", "value2", NULL }
378  *
379  * \return A pointer to the result document which must be freed with ast_xml_close()
380  */
381 struct ast_xml_doc *ast_xslt_apply(struct ast_xslt_doc *xslt, struct ast_xml_doc *doc, const char **params);
382 
383 /*!
384  * \brief Save the results of applying a stylesheet to a string
385  *
386  * \param[out] buffer A pointer to a char * to receive the address of the result string.
387  * The buffer must be freed with ast_xml_free_text().
388  * \param[out] length A pointer to an int to receive the result string length.
389  * \param result The result document from ast_xslt_apply.
390  * \param xslt The stylesheet that was applied.
391  *
392  * \return 0 on success, any other value on failure.
393  */
394 int ast_xslt_save_result_to_string(char **buffer, int *length, struct ast_xml_doc *result,
395  struct ast_xslt_doc *xslt);
396 
397 #endif /* HAVE_LIBXSLT */
398 #endif /* _ASTERISK_XML_H */
Definition: test_heap.c:38
int ast_xml_init(void)
Initialize the XML library implementation. This function is used to setup everything needed to start ...
Definition: xml.c:48
const char * ast_xml_get_ns_href(struct ast_xml_ns *ns)
Get the href of a namespace.
Definition: xml.c:348
struct ast_xml_doc * ast_xml_open(char *filename)
Open an XML document.
Definition: xml.c:94
struct ast_xml_doc * ast_xml_new(void)
Create a XML document.
Definition: xml.c:136
void ast_xml_free_node(struct ast_xml_node *node)
Free node.
Definition: xml.c:243
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:168
int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc)
Dump the specified document to a file.
Definition: xml.c:380
int ast_xml_xpath_num_results(struct ast_xml_xpath_results *results)
Return the number of results from an XPath query.
Definition: xml.c:433
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:230
void ast_xml_set_name(struct ast_xml_node *node, const char *name)
Set or reset an element's name.
Definition: xml.c:371
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:156
struct ast_xml_doc * ast_xml_get_doc(struct ast_xml_node *node)
Get the document based on a node.
Definition: xml.c:329
struct ast_xml_doc * ast_xslt_apply(struct ast_xslt_doc *xslt, struct ast_xml_doc *doc, const char **params)
Apply an XSLT stylesheet to an XML document.
Definition: xml.c:561
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:267
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:253
struct ast_xml_node * ast_xml_add_child_list(struct ast_xml_node *parent, struct ast_xml_node *child)
Add a list of child nodes, to a specified parent node.
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:297
struct ast_xml_node * ast_xml_new_node(const char *name)
Create a XML node.
Definition: xml.c:144
#define AST_VECTOR(name, type)
Define a vector structure.
Definition: vector.h:44
void ast_xslt_close(struct ast_xslt_doc *xslt)
Close a stylesheet document and free its resources.
Definition: xml.c:552
struct ast_xml_node * ast_xml_xpath_get_result(struct ast_xml_xpath_results *results, int n)
Return a specific result node of an XPath query.
Definition: xml.c:420
struct ast_xml_xpath_results * ast_xml_query(struct ast_xml_doc *doc, const char *xpath_str)
Execute an XPath query on an XML document.
Definition: xml.c:441
struct ast_xml_xpath_results * ast_xml_query_with_namespaces(struct ast_xml_doc *doc, const char *xpath_str, struct ast_xml_namespace_def_vector *namespaces)
Execute an XPath query on an XML document with namespaces.
Definition: xml.c:463
void ast_xml_doc_dump_memory(struct ast_xml_doc *doc, char **buffer, int *length)
Dump the specified document to a buffer.
Definition: xml.c:385
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:221
void ast_xml_set_text(struct ast_xml_node *node, const char *content)
Set an element content string.
Definition: xml.c:362
struct ast_xml_node * ast_xml_node_get_parent(struct ast_xml_node *node)
Get the parent of a specified node.
Definition: xml.c:410
struct ast_xml_node * ast_xml_copy_node_list(struct ast_xml_node *list)
Create a copy of a n ode list.
Definition: xml.c:184
Vector container support.
void ast_xml_xpath_results_free(struct ast_xml_xpath_results *results)
Free the XPath results.
Definition: xml.c:425
void ast_xml_close(struct ast_xml_doc *doc)
Close an already open document and free the used structure.
Definition: xml.c:211
Namespace definition.
Definition: xml.h:325
struct ast_xslt_doc * ast_xslt_read_memory(char *buffer, size_t size)
Open an XSLT document that resides in memory.
Definition: xml.c:525
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:284
const char * ast_xml_get_text(struct ast_xml_node *node)
Get an element content string.
Definition: xml.c:353
const char * ast_xml_get_ns_prefix(struct ast_xml_ns *ns)
Get the prefix of a namespace.
Definition: xml.c:343
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:405
struct ast_xml_doc * ast_xml_read_memory(char *buffer, size_t size)
Open an XML document that resides in memory.
Definition: xml.c:192
int ast_xslt_save_result_to_string(char **buffer, int *length, struct ast_xml_doc *result, struct ast_xslt_doc *xslt)
Save the results of applying a stylesheet to a string.
Definition: xml.c:608
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:400
int ast_xml_finish(void)
Cleanup library allocated global data.
Definition: xml.c:57
struct ast_xml_node * ast_xml_xpath_get_first_result(struct ast_xml_xpath_results *results)
Return the first result node of an XPath query.
Definition: xml.c:415
struct ast_xslt_doc * ast_xslt_open(char *filename)
Open an XSLT document.
Definition: xml.c:501
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:390
void ast_xml_free_text(const char *text)
Free a content element that was returned by ast_xml_get_text()
Definition: xml.c:260