Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Enumerations | Functions
xmldoc.h File Reference

Asterisk XML Documentation API. More...

#include "asterisk/xml.h"
#include "asterisk/stringfields.h"
#include "asterisk/strings.h"

Go to the source code of this file.

Data Structures

struct  ast_xml_doc_item
 Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counted object. More...
 
struct  ast_xml_doc_item_list
 The struct to be used as the head of an ast_xml_doc_item list when being manipulated. More...
 

Enumerations

enum  ast_doc_src { AST_XML_DOC, AST_STATIC_DOC }
 From where the documentation come from, this structure is useful for use it inside application/functions/manager actions structure. More...
 

Functions

char * ast_xmldoc_build_arguments (const char *type, const char *name, const char *module)
 Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name. More...
 
char * ast_xmldoc_build_description (const char *type, const char *name, const char *module)
 Generate description documentation from XML. More...
 
struct ao2_containerast_xmldoc_build_documentation (const char *type)
 Build the documentation for a particular source type. More...
 
struct ast_xml_doc_itemast_xmldoc_build_final_response (const char *type, const char *name, const char *module)
 Generate the [final response] tag based on type of node ('application', 'function' or 'agi') and name. More...
 
struct ast_xml_doc_itemast_xmldoc_build_list_responses (const char *type, const char *name, const char *module)
 Generate the [list responses] tag based on type of node ('application', 'function' or 'agi') and name. More...
 
char * ast_xmldoc_build_seealso (const char *type, const char *name, const char *module)
 Parse the <see-also> node content. More...
 
char * ast_xmldoc_build_synopsis (const char *type, const char *name, const char *module)
 Generate synopsis documentation from XML. More...
 
char * ast_xmldoc_build_syntax (const char *type, const char *name, const char *module)
 Get the syntax for a specified application or function. More...
 
char * ast_xmldoc_printable (const char *bwinput, int withcolors)
 Colorize and put delimiters (instead of tags) to the xmldoc output. More...
 
struct ast_xml_xpath_results * ast_xmldoc_query (const char *fmt,...)
 Execute an XPath query on the loaded XML documentation. More...
 
int ast_xmldoc_regenerate_doc_item (struct ast_xml_doc_item *item)
 Regenerate the documentation for a particular item. More...
 

Detailed Description

Asterisk XML Documentation API.

Definition in file xmldoc.h.

Enumeration Type Documentation

From where the documentation come from, this structure is useful for use it inside application/functions/manager actions structure.

Enumerator
AST_XML_DOC 

From XML documentation

AST_STATIC_DOC 

From application/function registration

Definition at line 30 of file xmldoc.h.

30  {
31  AST_XML_DOC, /*!< From XML documentation */
32  AST_STATIC_DOC /*!< From application/function registration */
33 };

Function Documentation

char* ast_xmldoc_build_arguments ( const char *  type,
const char *  name,
const char *  module 
)

Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name.

Parameters
type'application', 'function' or 'agi' ?
nameName of the application or function to build the 'arguments' tag.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Outputbuffer with the [arguments] tag content.

Definition at line 2084 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2(), and ast_register_application2().

2085 {
2086  struct ast_xml_node *node;
2087  char *arguments;
2088 
2089  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2090  return NULL;
2091  }
2092 
2094  node = xmldoc_get_node(type, name, module, documentation_language);
2095 
2096  if (!node || !ast_xml_node_get_children(node)) {
2098  return NULL;
2099  }
2100 
2101  arguments = _ast_xmldoc_build_arguments(node);
2103  return arguments;
2104 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
char* ast_xmldoc_build_description ( const char *  type,
const char *  name,
const char *  module 
)

Generate description documentation from XML.

Parameters
typeThe source of documentation (application, function, etc).
nameThe name of the application, function, etc.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Amalloc'ed string with the formatted description.

Definition at line 2271 of file xmldoc.c.

Referenced by ast_manager_register2(), and ast_register_application2().

2272 {
2273  return xmldoc_build_field(type, name, module, "description", 0);
2274 }
struct ao2_container* ast_xmldoc_build_documentation ( const char *  type)

Build the documentation for a particular source type.

Parameters
typeThe source of the documentation items (application, function, etc.)
Return values
NULLon error
Anao2_container populated with ast_xml_doc instances for each item that exists for the specified source type
Since
11

Definition at line 2684 of file xmldoc.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_link, AST_LIST_FIRST, AST_LIST_HEAD_INIT, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_get_root(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), documentation_tree::doc, and RAII_VAR.

Referenced by aco_init().

2685 {
2686  struct ao2_container *docs;
2687  struct ast_xml_node *node = NULL, *instance = NULL;
2688  struct documentation_tree *doctree;
2689  const char *name;
2690 
2692  ast_xml_doc_item_hash, NULL, ast_xml_doc_item_cmp);
2693  if (!docs) {
2694  ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
2695  return NULL;
2696  }
2697 
2699  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2700  /* the core xml documents have priority over thirdparty document. */
2701  node = ast_xml_get_root(doctree->doc);
2702  if (!node) {
2703  break;
2704  }
2705 
2706  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
2707  struct ast_xml_doc_item *item = NULL;
2708 
2709  /* Ignore empty nodes or nodes that aren't of the type requested */
2710  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), type)) {
2711  continue;
2712  }
2713  name = ast_xml_get_attribute(node, "name");
2714  if (!name) {
2715  continue;
2716  }
2717 
2718  switch (xmldoc_get_syntax_type(type)) {
2719  case MANAGER_EVENT_SYNTAX:
2720  {
2721  struct ast_xml_doc_item_list root;
2722 
2723  AST_LIST_HEAD_INIT(&root);
2724  for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
2725  struct ast_xml_doc_item *temp;
2726  if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
2727  continue;
2728  }
2729  temp = xmldoc_build_documentation_item(instance, name, type);
2730  if (!temp) {
2731  break;
2732  }
2733  AST_LIST_INSERT_TAIL(&root, temp, next);
2734  }
2735  item = AST_LIST_FIRST(&root);
2736  break;
2737  }
2738  case CONFIG_INFO_SYNTAX:
2739  {
2740  RAII_VAR(const char *, name, ast_xml_get_attribute(node, "name"), ast_xml_free_attr);
2741 
2742  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), "configInfo")) {
2743  break;
2744  }
2745 
2746  item = xmldoc_build_documentation_item(node, name, "configInfo");
2747  if (item) {
2748  struct ast_xml_doc_item_list root;
2749 
2750  AST_LIST_HEAD_INIT(&root);
2751  AST_LIST_INSERT_TAIL(&root, item, next);
2752  build_config_docs(node, &root);
2753  }
2754  break;
2755  }
2756  default:
2757  item = xmldoc_build_documentation_item(node, name, type);
2758  }
2759  ast_xml_free_attr(name);
2760 
2761  if (item) {
2762  ao2_link(docs, item);
2763  ao2_t_ref(item, -1, "Dispose of creation ref");
2764  }
2765  }
2766  }
2768 
2769  return docs;
2770 }
Definition: test_heap.c:38
XML documentation tree.
Definition: xmldoc.c:54
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:421
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:230
The struct to be used as the head of an ast_xml_doc_item list when being manipulated.
Definition: xmldoc.h:45
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
const ast_string_field type
Definition: xmldoc.h:74
struct ast_xml_doc * doc
Definition: xmldoc.c:56
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:731
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:626
Definition: search.h:40
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Generic container type.
Container of documentation trees.
Definition: xmldoc.c:74
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
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
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
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
struct ast_xml_doc_item* ast_xmldoc_build_final_response ( const char *  type,
const char *  name,
const char *  module 
)

Generate the [final response] tag based on type of node ('application', 'function' or 'agi') and name.

Parameters
type'application', 'function' or 'agi'
nameName of the application or function to build the 'responses' tag.
moduleThe module the item is in (optional, can be NULL)
Returns
An XMLDoc item list with the [final response] tag content.
Since
13.0.0

Definition at line 2554 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2().

2555 {
2556  struct ast_xml_node *node;
2557  static struct ast_xml_doc_item *response;
2558 
2559  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2560  return NULL;
2561  }
2562 
2564  node = xmldoc_get_node(type, name, module, documentation_language);
2565 
2566  if (!node || !ast_xml_node_get_children(node)) {
2568  return NULL;
2569  }
2570 
2571  response = xmldoc_build_final_response(node);
2573  return response;
2574 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
const ast_string_field type
Definition: xmldoc.h:74
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
const ast_string_field name
Definition: xmldoc.h:74
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
struct ast_xml_doc_item* ast_xmldoc_build_list_responses ( const char *  type,
const char *  name,
const char *  module 
)

Generate the [list responses] tag based on type of node ('application', 'function' or 'agi') and name.

Parameters
type'application', 'function' or 'agi'
nameName of the application or function to build the 'responses' tag.
moduleThe module the item is in (optional, can be NULL)
Returns
An XMLDoc item list with the [list responses] tag content.
Since
13.0.0

Definition at line 2484 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2().

2485 {
2486  struct ast_xml_node *node;
2487  struct ast_xml_doc_item *responses;
2488 
2489  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2490  return NULL;
2491  }
2492 
2494  node = xmldoc_get_node(type, name, module, documentation_language);
2495 
2496  if (!node || !ast_xml_node_get_children(node)) {
2498  return NULL;
2499  }
2500 
2501  responses = xmldoc_build_list_responses(node);
2503  return responses;
2504 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
const ast_string_field type
Definition: xmldoc.h:74
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
const ast_string_field name
Definition: xmldoc.h:74
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
char* ast_xmldoc_build_seealso ( const char *  type,
const char *  name,
const char *  module 
)

Parse the <see-also> node content.

Parameters
type'application', 'function' or 'agi'.
nameApplication or functions name.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Contentof the see-also node.

Definition at line 1702 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2(), and ast_register_application2().

1703 {
1704  char *output;
1705  struct ast_xml_node *node;
1706 
1707  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1708  return NULL;
1709  }
1710 
1711  /* get the application/function root node. */
1713  node = xmldoc_get_node(type, name, module, documentation_language);
1714  if (!node || !ast_xml_node_get_children(node)) {
1716  return NULL;
1717  }
1718 
1719  output = _ast_xmldoc_build_seealso(node);
1721 
1722  return output;
1723 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
char* ast_xmldoc_build_synopsis ( const char *  type,
const char *  name,
const char *  module 
)

Generate synopsis documentation from XML.

Parameters
typeThe source of documentation (application, function, etc).
nameThe name of the application, function, etc.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Amalloc'ed string with the synopsis.

Definition at line 2248 of file xmldoc.c.

Referenced by ast_manager_register2(), and ast_register_application2().

2249 {
2250  return xmldoc_build_field(type, name, module, "synopsis", 1);
2251 }
char* ast_xmldoc_build_syntax ( const char *  type,
const char *  name,
const char *  module 
)

Get the syntax for a specified application or function.

Parameters
typeApplication, Function or AGI ?
nameName of the application or function.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Thegenerated syntax in a ast_malloc'ed string.

Definition at line 1252 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and documentation_language.

Referenced by ast_manager_register2(), and ast_register_application2().

1253 {
1254  struct ast_xml_node *node;
1255  char *syntax;
1256 
1258  node = xmldoc_get_node(type, name, module, documentation_language);
1259  if (!node) {
1261  return NULL;
1262  }
1263 
1264  syntax = _ast_xmldoc_build_syntax(node, type, name);
1266  return syntax;
1267 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
char* ast_xmldoc_printable ( const char *  bwinput,
int  withcolors 
)

Colorize and put delimiters (instead of tags) to the xmldoc output.

Parameters
bwinputNot colorized input with tags.
withcolorsResult output with colors.
Return values
NULLon error.
Newmalloced buffer colorized and with delimiters.

Definition at line 241 of file xmldoc.c.

References ast_copy_string(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_term_color_code(), ast_term_reset(), and xmldoc_text_columns.

242 {
243  struct ast_str *colorized;
244  char *wrapped = NULL;
245  int i, c, len, colorsection;
246  char *tmp;
247  size_t bwinputlen;
248  static const int base_fg = COLOR_CYAN;
249 
250  if (!bwinput) {
251  return NULL;
252  }
253 
254  bwinputlen = strlen(bwinput);
255 
256  if (!(colorized = ast_str_create(256))) {
257  return NULL;
258  }
259 
260  if (withcolors) {
261  ast_term_color_code(&colorized, base_fg, 0);
262  if (!colorized) {
263  return NULL;
264  }
265  }
266 
267  for (i = 0; i < bwinputlen; i++) {
268  colorsection = 0;
269  /* Check if we are at the beginning of a tag to be colorized. */
270  for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
271  if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
272  continue;
273  }
274 
275  if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
276  continue;
277  }
278 
279  len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
280 
281  /* Setup color */
282  if (withcolors) {
283  if (ast_opt_light_background) {
284  /* Turn off *bright* colors */
285  ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
286  } else {
287  /* Turn on *bright* colors */
288  ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
289  }
290  if (!colorized) {
291  return NULL;
292  }
293  }
294 
295  /* copy initial string replace */
296  ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
297  if (!colorized) {
298  return NULL;
299  }
300  {
301  char buf[len + 1];
302  ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
303  ast_str_append(&colorized, 0, "%s", buf);
304  }
305  if (!colorized) {
306  return NULL;
307  }
308 
309  /* copy the ending string replace */
310  ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
311  if (!colorized) {
312  return NULL;
313  }
314 
315  /* Continue with the last color. */
316  if (withcolors) {
317  ast_term_color_code(&colorized, base_fg, 0);
318  if (!colorized) {
319  return NULL;
320  }
321  }
322 
323  i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
324  colorsection = 1;
325  break;
326  }
327 
328  if (!colorsection) {
329  ast_str_append(&colorized, 0, "%c", bwinput[i]);
330  if (!colorized) {
331  return NULL;
332  }
333  }
334  }
335 
336  if (withcolors) {
337  ast_str_append(&colorized, 0, "%s", ast_term_reset());
338  if (!colorized) {
339  return NULL;
340  }
341  }
342 
343  /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
344  wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns);
345 
346  ast_free(colorized);
347 
348  return wrapped;
349 }
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
int ast_term_color_code(struct ast_str **str, int fgcolor, int bgcolor)
Append a color sequence to an ast_str.
Definition: term.c:296
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
Support for dynamic strings.
Definition: strings.h:623
static const int xmldoc_text_columns
Number of columns to print when showing the XML documentation with a 'core show application/function ...
Definition: xmldoc.c:48
const char * ast_term_reset(void)
Returns the terminal reset code.
Definition: term.c:357
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
struct ast_xml_xpath_results* ast_xmldoc_query ( const char *  fmt,
  ... 
)

Execute an XPath query on the loaded XML documentation.

Parameters
fmtThe XPath query string to execute
...Variable printf style format arguments
Return values
AnXPath results object on success
NULLif no match found
Since
12

Definition at line 2576 of file xmldoc.c.

References AST_DYNSTR_BUILD_FAILED, AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_str_buffer(), ast_str_create, ast_str_set_va(), ast_xml_query(), documentation_tree::doc, and RAII_VAR.

Referenced by load_modules().

2577 {
2578  struct ast_xml_xpath_results *results = NULL;
2579  struct documentation_tree *doctree;
2580  RAII_VAR(struct ast_str *, xpath_str, ast_str_create(128), ast_free);
2581  va_list ap;
2582  int res;
2583 
2584  if (!xpath_str) {
2585  return NULL;
2586  }
2587 
2588  va_start(ap, fmt);
2589  res = ast_str_set_va(&xpath_str, 0, fmt, ap);
2590  va_end(ap);
2591  if (res == AST_DYNSTR_BUILD_FAILED) {
2592  return NULL;
2593  }
2594 
2596  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2597  if (!(results = ast_xml_query(doctree->doc, ast_str_buffer(xpath_str)))) {
2598  continue;
2599  }
2600  break;
2601  }
2603 
2604  return results;
2605 }
XML documentation tree.
Definition: xmldoc.c:54
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:1030
struct ast_xml_doc * doc
Definition: xmldoc.c:56
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
Support for dynamic strings.
Definition: strings.h:623
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
Definition: search.h:40
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
int ast_xmldoc_regenerate_doc_item ( struct ast_xml_doc_item item)

Regenerate the documentation for a particular item.

Parameters
itemThe documentation item to regenerate
Return values
-1on error
0on success
Since
12

Definition at line 2635 of file xmldoc.c.

References ast_xml_doc_item::arguments, ast_str_set(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_doc_item::description, ast_xml_doc_item::name, ast_xml_doc_item::node, ast_xml_doc_item::seealso, ast_xml_doc_item::synopsis, ast_xml_doc_item::syntax, and ast_xml_doc_item::type.

2636 {
2637  const char *name;
2638  char *syntax;
2639  char *seealso;
2640  char *arguments;
2641  char *synopsis;
2642  char *description;
2643 
2644  if (!item || !item->node) {
2645  return -1;
2646  }
2647 
2648  name = ast_xml_get_attribute(item->node, "name");
2649  if (!name) {
2650  return -1;
2651  }
2652 
2653  syntax = _ast_xmldoc_build_syntax(item->node, item->type, name);
2654  seealso = _ast_xmldoc_build_seealso(item->node);
2655  arguments = _ast_xmldoc_build_arguments(item->node);
2656  synopsis = _ast_xmldoc_build_synopsis(item->node);
2657  description = _ast_xmldoc_build_description(item->node);
2658 
2659  if (syntax) {
2660  ast_str_set(&item->syntax, 0, "%s", syntax);
2661  }
2662  if (seealso) {
2663  ast_str_set(&item->seealso, 0, "%s", seealso);
2664  }
2665  if (arguments) {
2666  ast_str_set(&item->arguments, 0, "%s", arguments);
2667  }
2668  if (synopsis) {
2669  ast_str_set(&item->synopsis, 0, "%s", synopsis);
2670  }
2671  if (description) {
2672  ast_str_set(&item->description, 0, "%s", description);
2673  }
2674 
2675  ast_free(syntax);
2676  ast_free(seealso);
2677  ast_free(arguments);
2678  ast_free(synopsis);
2679  ast_free(description);
2680  ast_xml_free_attr(name);
2681  return 0;
2682 }
struct ast_xml_node * node
Definition: xmldoc.h:78
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
int ast_str_set(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Set a dynamic string using variable arguments.
Definition: strings.h:1113
const ast_string_field type
Definition: xmldoc.h:74
struct ast_str * description
Definition: xmldoc.h:66
struct ast_str * arguments
Definition: xmldoc.h:62
struct ast_str * syntax
Definition: xmldoc.h:58
struct ast_str * seealso
Definition: xmldoc.h:60
struct ast_str * synopsis
Definition: xmldoc.h:64