Wed Jan 8 2020 09:50:22

Asterisk developer's documentation


xml.c File Reference

XML abstraction layer. More...

#include "asterisk.h"
#include "asterisk/xml.h"
#include "asterisk/logger.h"
#include <libxml/parser.h>
#include <libxml/tree.h>
#include <libxml/xinclude.h>

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...
 
void ast_xml_close (struct ast_xml_doc *doc)
 Close an already open document and free the used structure. 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_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...
 

Detailed Description

XML abstraction layer.

Author
Eliel C. Sardanons (LU1ALY) eliel.nosp@m.s@gm.nosp@m.ail.c.nosp@m.om

Definition in file xml.c.

Function Documentation

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 107 of file xml.c.

Referenced by data_get_xml_add_child().

108 {
109  if (!parent || !child) {
110  return NULL;
111  }
112  return (struct ast_xml_node *) xmlAddChild((xmlNode *) parent, (xmlNode *) child);
113 }
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 134 of file xml.c.

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

135 {
136  if (!doc) {
137  return;
138  }
139 
140  xmlFreeDoc((xmlDoc *) doc);
141  doc = NULL;
142 }
int ast_xml_doc_dump_file ( FILE *  output,
struct ast_xml_doc *  doc 
)

Dump the specified document to a file.

Definition at line 289 of file xml.c.

290 {
291  return xmlDocDump(output, (xmlDocPtr)doc);
292 }
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 220 of file xml.c.

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

Referenced by cc_esc_publish_handler(), xmldoc_build_field(), and xmldoc_get_node().

221 {
222  struct ast_xml_node *cur;
223  const char *attr;
224 
225  if (!root_node) {
226  return NULL;
227  }
228 
229  for (cur = root_node; cur; cur = ast_xml_node_get_next(cur)) {
230  /* Check if the name matchs */
231  if (strcmp(ast_xml_node_get_name(cur), name)) {
232  continue;
233  }
234  /* We need to check for a specific attribute name? */
235  if (!attrname || !attrvalue) {
236  return cur;
237  }
238  /* Get the attribute, we need to compare it. */
239  if ((attr = ast_xml_get_attribute(cur, attrname))) {
240  /* does attribute name/value matches? */
241  if (!strcmp(attr, attrvalue)) {
242  ast_xml_free_attr(attr);
243  return cur;
244  }
245  ast_xml_free_attr(attr);
246  }
247  }
248 
249  return NULL;
250 }
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
static const char name[]
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
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:294
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 261 of file xml.c.

Referenced by pidf_validate_presence().

261  {
262  xmlNsPtr ns = xmlSearchNs((xmlDocPtr) doc, (xmlNodePtr) node, (xmlChar *) ns_name);
263  return (struct ast_xml_ns *) ns;
264 }
int ast_xml_finish ( void  )

Cleanup library allocated global data.

Return values
0On success.
1On error.

Definition at line 48 of file xml.c.

Referenced by xmldoc_unload_documentation().

49 {
50  xmlCleanupParser();
51 
52  return 0;
53 }
void ast_xml_free_attr ( const char *  attribute)
void ast_xml_free_node ( struct ast_xml_node *  node)

Free node.

Parameters
nodeNode to be released.

Definition at line 166 of file xml.c.

167 {
168  if (!node) {
169  return;
170  }
171 
172  xmlFreeNode((xmlNode *) node);
173  node = NULL;
174 }
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 183 of file xml.c.

Referenced by ast_xmldoc_build_seealso(), cc_esc_publish_handler(), xmldoc_get_formatted(), xmldoc_parse_para(), and xmldoc_parse_variable().

184 {
185  if (text) {
186  xmlFree((char *) text);
187  }
188 }
char * text
Definition: app_queue.c:1091
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 190 of file xml.c.

Referenced by ast_xml_find_element(), ast_xmldoc_build_seealso(), pidf_validate_presence(), pidf_validate_tuple(), xmldoc_attribute_match(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_fun(), xmldoc_get_syntax_manager(), xmldoc_parse_argument(), xmldoc_parse_enumlist(), xmldoc_parse_optionlist(), xmldoc_parse_parameter(), xmldoc_parse_variable(), and xmldoc_parse_variablelist().

191 {
192  xmlChar *attrvalue;
193 
194  if (!node) {
195  return NULL;
196  }
197 
198  if (!attrname) {
199  return NULL;
200  }
201 
202  attrvalue = xmlGetProp((xmlNode *) node, (xmlChar *) attrname);
203 
204  return (const char *) attrvalue;
205 }
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 252 of file xml.c.

253 {
254  if (!node) {
255  return NULL;
256  }
257 
258  return (struct ast_xml_doc *) ((xmlNode *)node)->doc;
259 }
const char* ast_xml_get_ns_href ( struct ast_xml_ns *  ns)

Definition at line 266 of file xml.c.

Referenced by pidf_validate_presence().

267 {
268  return (const char *) ((xmlNsPtr) ns)->href;
269 }
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 153 of file xml.c.

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

154 {
155  xmlNode *root_node;
156 
157  if (!doc) {
158  return NULL;
159  }
160 
161  root_node = xmlDocGetRootElement((xmlDoc *) doc);
162 
163  return (struct ast_xml_node *) root_node;
164 }
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 271 of file xml.c.

Referenced by ast_xmldoc_build_seealso(), cc_esc_publish_handler(), xmldoc_get_formatted(), xmldoc_parse_para(), and xmldoc_parse_variable().

272 {
273  if (!node) {
274  return NULL;
275  }
276 
277  return (const char *) xmlNodeGetContent((xmlNode *) node);
278 }
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 41 of file xml.c.

Referenced by ast_xmldoc_load_documentation().

42 {
43  LIBXML_TEST_VERSION
44 
45  return 0;
46 }
struct ast_xml_doc* ast_xml_new ( void  )

Create a XML document.

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

Definition at line 75 of file xml.c.

Referenced by ast_data_get_xml().

76 {
77  xmlDoc *doc;
78 
79  doc = xmlNewDoc((const xmlChar *) "1.0");
80  return (struct ast_xml_doc *) doc;
81 }
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 95 of file xml.c.

96 {
97  xmlNode *child;
98 
99  if (!parent || !child_name) {
100  return NULL;
101  }
102 
103  child = xmlNewChild((xmlNode *) parent, NULL, (const xmlChar *) child_name, NULL);
104  return (struct ast_xml_node *) child;
105 }
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 83 of file xml.c.

Referenced by ast_data_get_xml(), and data_get_xml_add_child().

84 {
85  xmlNode *node;
86  if (!name) {
87  return NULL;
88  }
89 
90  node = xmlNewNode(NULL, (const xmlChar *) name);
91 
92  return (struct ast_xml_node *) node;
93 }
static const char name[]
struct ast_xml_node* ast_xml_node_get_parent ( struct ast_xml_node *  node)

Get the parent of a specified node.

Definition at line 314 of file xml.c.

315 {
316  return (struct ast_xml_node *) ((xmlNode *) node)->parent;
317 }
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 309 of file xml.c.

310 {
311  return (struct ast_xml_node *) ((xmlNode *) node)->prev;
312 }
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 55 of file xml.c.

Referenced by ast_xmldoc_load_documentation().

56 {
57  xmlDoc *doc;
58 
59  if (!filename) {
60  return NULL;
61  }
62 
63  doc = xmlReadFile(filename, NULL, XML_PARSE_RECOVER);
64  if (doc) {
65  /* process xinclude elements. */
66  if (xmlXIncludeProcess(doc) < 0) {
67  xmlFreeDoc(doc);
68  return NULL;
69  }
70  }
71 
72  return (struct ast_xml_doc *) doc;
73 }
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 115 of file xml.c.

Referenced by sip_pidf_validate().

116 {
117  xmlDoc *doc;
118 
119  if (!buffer) {
120  return NULL;
121  }
122 
123  if (!(doc = xmlParseMemory(buffer, (int) size))) {
124  /* process xinclude elements. */
125  if (xmlXIncludeProcess(doc) < 0) {
126  xmlFreeDoc(doc);
127  return NULL;
128  }
129  }
130 
131  return (struct ast_xml_doc *) doc;
132 }
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 207 of file xml.c.

208 {
209  if (!name || !value) {
210  return -1;
211  }
212 
213  if (!xmlSetProp((xmlNode *) node, (xmlChar *) name, (xmlChar *) value)) {
214  return -1;
215  }
216 
217  return 0;
218 }
int value
Definition: syslog.c:39
static const char name[]
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 144 of file xml.c.

Referenced by ast_data_get_xml().

145 {
146  if (!doc || !node) {
147  return;
148  }
149 
150  xmlDocSetRootElement((xmlDoc *) doc, (xmlNode *) node);
151 }
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 280 of file xml.c.

Referenced by data_get_xml_add_child().

281 {
282  if (!node || !content) {
283  return;
284  }
285 
286  xmlNodeSetContent((xmlNode *) node, (const xmlChar *) content);
287 }