Asterisk - The Open Source Telephony Project  GIT-master-4a4f1a5
Functions
xml.h File Reference

Asterisk XML abstraction layer. More...

Go to the source code of this file.

Functions

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. More...
 
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. More...
 
void ast_xml_close (struct ast_xml_doc *doc)
 Close an already open document and free the used structure. More...
 
struct ast_xml_node * ast_xml_copy_node_list (struct ast_xml_node *list)
 Create a copy of a n ode list. More...
 
int ast_xml_doc_dump_file (FILE *output, struct ast_xml_doc *doc)
 Dump the specified document to a file. More...
 
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. More...
 
struct ast_xml_ns * ast_xml_find_namespace (struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name)
 
int ast_xml_finish (void)
 Cleanup library allocated global data. More...
 
void ast_xml_free_attr (const char *attribute)
 Free an attribute returned by ast_xml_get_attribute() More...
 
void ast_xml_free_node (struct ast_xml_node *node)
 Free node. More...
 
void ast_xml_free_text (const char *text)
 Free a content element that was returned by ast_xml_get_text() More...
 
const char * ast_xml_get_attribute (struct ast_xml_node *node, const char *attrname)
 Get a node attribute by name. More...
 
struct ast_xml_doc * ast_xml_get_doc (struct ast_xml_node *node)
 Get the document based on a node. More...
 
const char * ast_xml_get_ns_href (struct ast_xml_ns *ns)
 
struct ast_xml_node * ast_xml_get_root (struct ast_xml_doc *doc)
 Get the document root node. More...
 
const char * ast_xml_get_text (struct ast_xml_node *node)
 Get an element content string. More...
 
int ast_xml_init (void)
 Initialize the XML library implementation. This function is used to setup everything needed to start working with the xml implementation. More...
 
struct ast_xml_doc * ast_xml_new (void)
 Create a XML document. More...
 
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. More...
 
struct ast_xml_node * ast_xml_new_node (const char *name)
 Create a XML node. More...
 
struct ast_xml_node * ast_xml_node_get_children (struct ast_xml_node *node)
 Get the node's children. More...
 
const char * ast_xml_node_get_name (struct ast_xml_node *node)
 Get the name of a node. More...
 
struct ast_xml_node * ast_xml_node_get_next (struct ast_xml_node *node)
 Get the next node in the same level. More...
 
struct ast_xml_node * ast_xml_node_get_parent (struct ast_xml_node *node)
 Get the parent of a specified node. More...
 
struct ast_xml_node * ast_xml_node_get_prev (struct ast_xml_node *node)
 Get the previous node in the same leve. More...
 
struct ast_xml_doc * ast_xml_open (char *filename)
 Open an XML document. More...
 
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. More...
 
struct ast_xml_doc * ast_xml_read_memory (char *buffer, size_t size)
 Open an XML document that resides in memory. More...
 
int ast_xml_set_attribute (struct ast_xml_node *node, const char *name, const char *value)
 Set an attribute to a node. More...
 
void ast_xml_set_root (struct ast_xml_doc *doc, struct ast_xml_node *node)
 Specify the root node of a XML document. More...
 
void ast_xml_set_text (struct ast_xml_node *node, const char *content)
 Set an element content string. More...
 
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. More...
 
int ast_xml_xpath_num_results (struct ast_xml_xpath_results *results)
 Return the number of results from an XPath query. More...
 
void ast_xml_xpath_results_free (struct ast_xml_xpath_results *results)
 Free the XPath results. More...
 

Detailed Description

Asterisk XML abstraction layer.

Definition in file xml.h.

Function Documentation

◆ ast_xml_add_child()

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.

Parameters
parentWhere to add the child node.
childThe child node to add.
Return values
NULLon error.
non-NULLThe add child node on success.

Definition at line 137 of file xml.c.

138 {
139  if (!parent || !child) {
140  return NULL;
141  }
142  return (struct ast_xml_node *) xmlAddChild((xmlNode *) parent, (xmlNode *) child);
143 }
#define NULL
Definition: resample.c:96

References NULL.

◆ ast_xml_add_child_list()

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.

Parameters
parentWhere to add the child node.
childThe child list to add.
Return values
NULLon error.
non-NULLThe added child list on success.

Definition at line 145 of file xml.c.

146 {
147  if (!parent || !child) {
148  return NULL;
149  }
150  return (struct ast_xml_node *) xmlAddChildList((xmlNode *) parent, (xmlNode *) child);
151 }

References NULL.

◆ ast_xml_close()

void ast_xml_close ( struct ast_xml_doc *  doc)

Close an already open document and free the used structure.

Return values
docThe document reference.

Definition at line 180 of file xml.c.

181 {
182  if (!doc) {
183  return;
184  }
185 
186  xmlFreeDoc((xmlDoc *) doc);
187  doc = NULL;
188 }

References NULL.

Referenced by ast_xmldoc_load_documentation(), cc_esc_publish_handler(), sip_pidf_validate(), and xmldoc_unload_documentation().

◆ ast_xml_copy_node_list()

struct ast_xml_node* ast_xml_copy_node_list ( struct ast_xml_node *  list)

Create a copy of a n ode list.

Parameters
listThe list to copy.
Return values
NULLon error.
non-NULLThe copied list.

Definition at line 153 of file xml.c.

154 {
155  if (!list) {
156  return NULL;
157  }
158  return (struct ast_xml_node *) xmlCopyNodeList((xmlNode *) list);
159 }

References NULL.

◆ ast_xml_doc_dump_file()

int ast_xml_doc_dump_file ( FILE *  output,
struct ast_xml_doc *  doc 
)

Dump the specified document to a file.

Definition at line 335 of file xml.c.

336 {
337  return xmlDocDump(output, (xmlDocPtr)doc);
338 }

◆ ast_xml_find_element()

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.

Parameters
root_nodeThis is the node starting point.
nameNode name to find.
attrnameattribute name to match (if NULL it won't be matched).
attrvalueattribute value to match (if NULL it won't be matched).
Return values
NULLif not found.
Thenode on success.

Definition at line 266 of file xml.c.

267 {
268  struct ast_xml_node *cur;
269  const char *attr;
270 
271  if (!root_node) {
272  return NULL;
273  }
274 
275  for (cur = root_node; cur; cur = ast_xml_node_get_next(cur)) {
276  /* Check if the name matchs */
277  if (strcmp(ast_xml_node_get_name(cur), name)) {
278  continue;
279  }
280  /* We need to check for a specific attribute name? */
281  if (!attrname || !attrvalue) {
282  return cur;
283  }
284  /* Get the attribute, we need to compare it. */
285  if ((attr = ast_xml_get_attribute(cur, attrname))) {
286  /* does attribute name/value matches? */
287  if (!strcmp(attr, attrvalue)) {
288  ast_xml_free_attr(attr);
289  return cur;
290  }
291  ast_xml_free_attr(attr);
292  }
293  }
294 
295  return NULL;
296 }
static const char name[]
Definition: format_mp3.c:68
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:340
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:222
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:236
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:350

References ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_name(), ast_xml_node_get_next(), name, and NULL.

Referenced by _xmldoc_build_field(), cc_esc_publish_handler(), load_modules(), xmldoc_build_final_response(), xmldoc_build_list_responses(), xmldoc_get_node(), and xmldoc_get_syntax_config_object().

◆ ast_xml_find_namespace()

struct ast_xml_ns* ast_xml_find_namespace ( struct ast_xml_doc *  doc,
struct ast_xml_node *  node,
const char *  ns_name 
)

Definition at line 307 of file xml.c.

307  {
308  xmlNsPtr ns = xmlSearchNs((xmlDocPtr) doc, (xmlNodePtr) node, (xmlChar *) ns_name);
309  return (struct ast_xml_ns *) ns;
310 }
Definition: test_heap.c:38

Referenced by pidf_validate_presence().

◆ ast_xml_finish()

int ast_xml_finish ( void  )

Cleanup library allocated global data.

Return values
0On success.
1On error.

Definition at line 53 of file xml.c.

54 {
55  xmlCleanupParser();
56 #ifdef HAVE_LIBXSLT_CLEANUP
57  xsltCleanupGlobals();
58 #endif
59 
60  return 0;
61 }

Referenced by xmldoc_unload_documentation().

◆ ast_xml_free_attr()

void ast_xml_free_attr ( const char *  attribute)

◆ ast_xml_free_node()

void ast_xml_free_node ( struct ast_xml_node *  node)

Free node.

Parameters
nodeNode to be released.

Definition at line 212 of file xml.c.

213 {
214  if (!node) {
215  return;
216  }
217 
218  xmlFreeNode((xmlNode *) node);
219  node = NULL;
220 }

References NULL.

◆ ast_xml_free_text()

void ast_xml_free_text ( const char *  text)

Free a content element that was returned by ast_xml_get_text()

Parameters
texttext to be freed.

Definition at line 229 of file xml.c.

230 {
231  if (text) {
232  xmlFree((char *) text);
233  }
234 }
char * text
Definition: app_queue.c:1517

References text.

Referenced by _ast_xmldoc_build_seealso(), cc_esc_publish_handler(), xmldoc_get_formatted(), xmldoc_get_syntax_config_object(), xmldoc_parse_example(), xmldoc_parse_para(), and xmldoc_parse_variable().

◆ ast_xml_get_attribute()

const char* ast_xml_get_attribute ( struct ast_xml_node *  node,
const char *  attrname 
)

Get a node attribute by name.

Parameters
nodeNode where to search the attribute.
attrnameAttribute name.
Return values
NULLon error
Theattribute value on success.

Definition at line 236 of file xml.c.

237 {
238  xmlChar *attrvalue;
239 
240  if (!node) {
241  return NULL;
242  }
243 
244  if (!attrname) {
245  return NULL;
246  }
247 
248  attrvalue = xmlGetProp((xmlNode *) node, (xmlChar *) attrname);
249 
250  return (const char *) attrvalue;
251 }

References NULL.

Referenced by _ast_xmldoc_build_seealso(), ast_xml_find_element(), ast_xmldoc_build_documentation(), ast_xmldoc_regenerate_doc_item(), build_config_docs(), pidf_validate_presence(), pidf_validate_tuple(), xmldoc_attribute_match(), xmldoc_build_final_response(), xmldoc_build_list_responses(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_config_object(), xmldoc_get_syntax_config_option(), xmldoc_get_syntax_fun(), xmldoc_get_syntax_manager(), xmldoc_parse_argument(), xmldoc_parse_enumlist(), xmldoc_parse_example(), xmldoc_parse_info(), xmldoc_parse_optionlist(), xmldoc_parse_parameter(), xmldoc_parse_variable(), and xmldoc_parse_variablelist().

◆ ast_xml_get_doc()

struct ast_xml_doc* ast_xml_get_doc ( struct ast_xml_node *  node)

Get the document based on a node.

Parameters
nodeA node that is part of the dom.
Returns
The dom pointer where this node resides.

Definition at line 298 of file xml.c.

299 {
300  if (!node) {
301  return NULL;
302  }
303 
304  return (struct ast_xml_doc *) ((xmlNode *)node)->doc;
305 }

References NULL.

◆ ast_xml_get_ns_href()

const char* ast_xml_get_ns_href ( struct ast_xml_ns *  ns)

Definition at line 312 of file xml.c.

313 {
314  return (const char *) ((xmlNsPtr) ns)->href;
315 }

Referenced by pidf_validate_presence().

◆ ast_xml_get_root()

struct ast_xml_node* ast_xml_get_root ( struct ast_xml_doc *  doc)

Get the document root node.

Parameters
docDocument reference
Return values
NULLon error
Theroot node on success.

Definition at line 199 of file xml.c.

200 {
201  xmlNode *root_node;
202 
203  if (!doc) {
204  return NULL;
205  }
206 
207  root_node = xmlDocGetRootElement((xmlDoc *) doc);
208 
209  return (struct ast_xml_node *) root_node;
210 }

References NULL.

Referenced by ast_xmldoc_build_documentation(), ast_xmldoc_load_documentation(), cc_esc_publish_handler(), pidf_validate_presence(), and xmldoc_get_node().

◆ ast_xml_get_text()

const char* ast_xml_get_text ( struct ast_xml_node *  node)

Get an element content string.

Parameters
nodeNode from where to get the string.
Return values
NULLon error.
Thetext content of node.

Definition at line 317 of file xml.c.

318 {
319  if (!node) {
320  return NULL;
321  }
322 
323  return (const char *) xmlNodeGetContent((xmlNode *) node);
324 }

References NULL.

Referenced by _ast_xmldoc_build_seealso(), cc_esc_publish_handler(), load_modules(), xmldoc_get_formatted(), xmldoc_get_syntax_config_object(), xmldoc_parse_example(), xmldoc_parse_para(), and xmldoc_parse_variable().

◆ ast_xml_init()

int ast_xml_init ( void  )

Initialize the XML library implementation. This function is used to setup everything needed to start working with the xml implementation.

Return values
0On success.
1On error.

Definition at line 46 of file xml.c.

47 {
48  LIBXML_TEST_VERSION
49 
50  return 0;
51 }

Referenced by ast_xmldoc_load_documentation().

◆ ast_xml_new()

struct ast_xml_doc* ast_xml_new ( void  )

Create a XML document.

Return values
NULLon error.
non-NULLThe allocated document structure.

Definition at line 105 of file xml.c.

106 {
107  xmlDoc *doc;
108 
109  doc = xmlNewDoc((const xmlChar *) "1.0");
110  return (struct ast_xml_doc *) doc;
111 }

◆ ast_xml_new_child()

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.

Parameters
parentThe pointer of the parent node.
child_nameThe name of the child node to add.
Return values
NULLon error.
non-NULLThe created child node pointer.

Definition at line 125 of file xml.c.

126 {
127  xmlNode *child;
128 
129  if (!parent || !child_name) {
130  return NULL;
131  }
132 
133  child = xmlNewChild((xmlNode *) parent, NULL, (const xmlChar *) child_name, NULL);
134  return (struct ast_xml_node *) child;
135 }

References NULL.

Referenced by xmldoc_update_config_type().

◆ ast_xml_new_node()

struct ast_xml_node* ast_xml_new_node ( const char *  name)

Create a XML node.

Parameters
nameThe name of the node to be created.
Return values
NULLon error.
non-NULLThe allocated node structe.

Definition at line 113 of file xml.c.

114 {
115  xmlNode *node;
116  if (!name) {
117  return NULL;
118  }
119 
120  node = xmlNewNode(NULL, (const xmlChar *) name);
121 
122  return (struct ast_xml_node *) node;
123 }

References name, and NULL.

◆ ast_xml_node_get_children()

struct ast_xml_node* ast_xml_node_get_children ( struct ast_xml_node *  node)

◆ ast_xml_node_get_name()

const char* ast_xml_node_get_name ( struct ast_xml_node *  node)

◆ ast_xml_node_get_next()

struct ast_xml_node* ast_xml_node_get_next ( struct ast_xml_node *  node)

◆ ast_xml_node_get_parent()

struct ast_xml_node* ast_xml_node_get_parent ( struct ast_xml_node *  node)

Get the parent of a specified node.

Definition at line 360 of file xml.c.

361 {
362  return (struct ast_xml_node *) ((xmlNode *) node)->parent;
363 }

◆ ast_xml_node_get_prev()

struct ast_xml_node* ast_xml_node_get_prev ( struct ast_xml_node *  node)

Get the previous node in the same leve.

Definition at line 355 of file xml.c.

356 {
357  return (struct ast_xml_node *) ((xmlNode *) node)->prev;
358 }

◆ ast_xml_open()

struct ast_xml_doc* ast_xml_open ( char *  filename)

Open an XML document.

Parameters
filenameDocument path.
Return values
NULLon error.
Theast_xml_doc reference to the open document.

Definition at line 63 of file xml.c.

64 {
65  xmlDoc *doc;
66 
67  if (!filename) {
68  return NULL;
69  }
70 
71  doc = xmlReadFile(filename, NULL, XML_PARSE_RECOVER);
72  if (!doc) {
73  return NULL;
74  }
75 
76  /* process xinclude elements. */
77  if (xmlXIncludeProcess(doc) < 0) {
78  xmlFreeDoc(doc);
79  return NULL;
80  }
81 
82 #ifdef HAVE_LIBXSLT
83  {
84  xsltStylesheetPtr xslt = xsltLoadStylesheetPI(doc);
85  if (xslt) {
86  xmlDocPtr tmpdoc = xsltApplyStylesheet(xslt, doc, NULL);
87  xsltFreeStylesheet(xslt);
88  xmlFreeDoc(doc);
89  if (!tmpdoc) {
90  return NULL;
91  }
92  doc = tmpdoc;
93  }
94  }
95 #else /* no HAVE_LIBXSLT */
96  ast_log(LOG_NOTICE, "XSLT support not found. XML documentation may be incomplete.\n");
97 #endif /* HAVE_LIBXSLT */
98 
99  /* Optimize for XPath */
100  xmlXPathOrderDocElems(doc);
101 
102  return (struct ast_xml_doc *) doc;
103 }
#define ast_log
Definition: astobj2.c:42
#define LOG_NOTICE
Definition: logger.h:264

References ast_log, LOG_NOTICE, and NULL.

Referenced by ast_xmldoc_load_documentation().

◆ ast_xml_query()

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.

Parameters
docThe XML document to query
xpath_strThe XPath query string to execute on the document
Return values
Anobject containing the results of the XPath query on success
NULLon failure
Since
12

Definition at line 380 of file xml.c.

381 {
382  xmlXPathContextPtr context;
383  xmlXPathObjectPtr result;
384  if (!(context = xmlXPathNewContext((xmlDoc *) doc))) {
385  ast_log(LOG_ERROR, "Could not create XPath context!\n");
386  return NULL;
387  }
388  result = xmlXPathEvalExpression((xmlChar *) xpath_str, context);
389  xmlXPathFreeContext(context);
390  if (!result) {
391  ast_log(LOG_WARNING, "Error for query: %s\n", xpath_str);
392  return NULL;
393  }
394  if (xmlXPathNodeSetIsEmpty(result->nodesetval)) {
395  xmlXPathFreeObject(result);
396  ast_debug(5, "No results for query: %s\n", xpath_str);
397  return NULL;
398  }
399  return (struct ast_xml_xpath_results *) result;
400 }
static PGresult * result
Definition: cel_pgsql.c:88
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:453
#define LOG_ERROR
Definition: logger.h:286
#define LOG_WARNING
Definition: logger.h:275

References ast_debug, ast_log, context, LOG_ERROR, LOG_WARNING, NULL, and result.

Referenced by ast_xmldoc_query().

◆ ast_xml_read_memory()

struct ast_xml_doc* ast_xml_read_memory ( char *  buffer,
size_t  size 
)

Open an XML document that resides in memory.

Parameters
bufferThe address where the document is stored
sizeThe number of bytes in the document
Return values
NULLon error.
Theast_xml_doc reference to the open document.

Definition at line 161 of file xml.c.

162 {
163  xmlDoc *doc;
164 
165  if (!buffer) {
166  return NULL;
167  }
168 
169  if (!(doc = xmlParseMemory(buffer, (int) size))) {
170  /* process xinclude elements. */
171  if (xmlXIncludeProcess(doc) < 0) {
172  xmlFreeDoc(doc);
173  return NULL;
174  }
175  }
176 
177  return (struct ast_xml_doc *) doc;
178 }

References NULL.

Referenced by sip_pidf_validate().

◆ ast_xml_set_attribute()

int ast_xml_set_attribute ( struct ast_xml_node *  node,
const char *  name,
const char *  value 
)

Set an attribute to a node.

Parameters
nodeIn which node we want to insert the attribute.
nameThe attribute name.
valueThe attribute value.
Return values
0on success.
-1on error.

Definition at line 253 of file xml.c.

254 {
255  if (!name || !value) {
256  return -1;
257  }
258 
259  if (!xmlSetProp((xmlNode *) node, (xmlChar *) name, (xmlChar *) value)) {
260  return -1;
261  }
262 
263  return 0;
264 }
int value
Definition: syslog.c:37

References name, and value.

Referenced by xmldoc_update_config_option(), and xmldoc_update_config_type().

◆ ast_xml_set_root()

void ast_xml_set_root ( struct ast_xml_doc *  doc,
struct ast_xml_node *  node 
)

Specify the root node of a XML document.

Parameters
docThe document pointer.
nodeA pointer to the node we want to set as root node.

Definition at line 190 of file xml.c.

191 {
192  if (!doc || !node) {
193  return;
194  }
195 
196  xmlDocSetRootElement((xmlDoc *) doc, (xmlNode *) node);
197 }

◆ ast_xml_set_text()

void ast_xml_set_text ( struct ast_xml_node *  node,
const char *  content 
)

Set an element content string.

Parameters
nodeNode from where to set the content string.
contentThe text to insert in the node.

Definition at line 326 of file xml.c.

327 {
328  if (!node || !content) {
329  return;
330  }
331 
332  xmlNodeSetContent((xmlNode *) node, (const xmlChar *) content);
333 }

Referenced by xmldoc_update_config_type().

◆ ast_xml_xpath_get_first_result()

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.

Parameters
resultsThe XPath results object to get the first result from
Return values
Thefirst result in the XPath object on success
NULLon error
Since
12

Definition at line 365 of file xml.c.

366 {
367  return (struct ast_xml_node *) ((xmlXPathObjectPtr) results)->nodesetval->nodeTab[0];
368 }

Referenced by load_modules(), xmldoc_update_config_option(), and xmldoc_update_config_type().

◆ ast_xml_xpath_num_results()

int ast_xml_xpath_num_results ( struct ast_xml_xpath_results *  results)

Return the number of results from an XPath query.

Parameters
resultsThe XPath results object to count
Return values
Thenumber of results in the XPath object
Since
12

Definition at line 375 of file xml.c.

376 {
377  return ((xmlXPathObjectPtr) results)->nodesetval->nodeNr;
378 }

◆ ast_xml_xpath_results_free()

void ast_xml_xpath_results_free ( struct ast_xml_xpath_results *  results)

Free the XPath results.

Parameters
resultsThe XPath results object to dispose of
Since
12

Definition at line 370 of file xml.c.

371 {
372  xmlXPathFreeObject((xmlXPathObjectPtr) results);
373 }

Referenced by load_modules(), xmldoc_update_config_option(), and xmldoc_update_config_type().