Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
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
26struct ast_xml_node;
27struct ast_xml_doc;
28struct ast_xml_xpath_results;
29struct 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 */
38int ast_xml_init(void);
39
40/*!
41 * \brief Cleanup library allocated global data.
42 * \retval 0 On success.
43 * \retval 1 On error.
44 */
45int 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 */
53struct 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 */
60struct 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 */
68struct 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 */
77struct 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 */
86struct 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 */
95struct 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 */
103struct 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 */
110void 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 */
118struct 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 */
125void 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 */
133struct 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 */
139void 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 */
145void 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 */
152struct 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 */
158void 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 */
168const 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 */
178int 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 */
189struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
190struct 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 */
209const 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 */
216const 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 */
224const 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 */
231void 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 */
238void ast_xml_set_name(struct ast_xml_node *node, const char *name);
239
240/*!
241 * \brief Get the name of a node. */
242const char *ast_xml_node_get_name(struct ast_xml_node *node);
243
244/*!
245 * \brief Get the node's children. */
246struct 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. */
250struct 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. */
254struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node);
255
256/*!
257 * \brief Get the parent of a specified node. */
258struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
259
260/*!
261 * \brief Dump the specified document to a file. */
262int 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 */
273void 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 */
281void 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 */
290int 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 */
300struct 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 */
309struct 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 */
320struct 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 */
340struct 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 */
352struct 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 */
361struct 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 */
368void 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 */
381struct 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 */
394int 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 */
char * text
Definition: app_queue.c:1639
static PGresult * result
Definition: cel_pgsql.c:84
static const char name[]
Definition: format_mp3.c:68
Namespace definition.
Definition: xml.h:325
const char * prefix
Definition: xml.h:326
const char * href
Definition: xml.h:327
Definition: test_heap.c:38
int value
Definition: syslog.c:37
Vector container support.
#define AST_VECTOR(name, type)
Define a vector structure.
Definition: vector.h:44
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
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
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_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:267
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
const char * ast_xml_get_text(struct ast_xml_node *node)
Get an element content string.
Definition: xml.c:353
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:338
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
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_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
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_new_node(const char *name)
Create a XML node.
Definition: xml.c:144
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
void ast_xml_close(struct ast_xml_doc *doc)
Close an already open document and free the used structure.
Definition: xml.c:211
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
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:390
int ast_xml_finish(void)
Cleanup library allocated global data.
Definition: xml.c:57
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:253
int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc)
Dump the specified document to a file.
Definition: xml.c:380
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
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_node * ast_xml_node_get_prev(struct ast_xml_node *node)
Get the previous node in the same leve.
Definition: xml.c:405
void ast_xml_xpath_results_free(struct ast_xml_xpath_results *results)
Free the XPath results.
Definition: xml.c:425
struct ast_xml_doc * ast_xml_new(void)
Create a XML document.
Definition: xml.c:136
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
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_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
void ast_xml_free_text(const char *text)
Free a content element that was returned by ast_xml_get_text()
Definition: xml.c:260
int ast_xml_init(void)
Initialize the XML library implementation. This function is used to setup everything needed to start ...
Definition: xml.c:48
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
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_doc * ast_xml_read_memory(char *buffer, size_t size)
Open an XML document that resides in memory.
Definition: xml.c:192
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_doc * ast_xml_open(char *filename)
Open an XML document.
Definition: xml.c:94
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_doc * ast_xml_get_doc(struct ast_xml_node *node)
Get the document based on a node.
Definition: xml.c:329
void ast_xml_free_node(struct ast_xml_node *node)
Free node.
Definition: xml.c:243
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:230
const char * ast_xml_get_ns_prefix(struct ast_xml_ns *ns)
Get the prefix of a namespace.
Definition: xml.c:343