Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
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

◆ ast_doc_src

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

◆ ast_xmldoc_build_arguments()

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 2075 of file xmldoc.c.

References _ast_xmldoc_build_arguments(), ast_strlen_zero(), ast_xml_node_get_children(), documentation_language, NULL, and xmldoc_get_node().

Referenced by acf_retrieve_docs(), ast_manager_register2(), and ast_register_application2().

2076 {
2077  struct ast_xml_node *node;
2078 
2080  return NULL;
2081  }
2082 
2083  node = xmldoc_get_node(type, name, module, documentation_language);
2084 
2085  if (!node || !ast_xml_node_get_children(node)) {
2086  return NULL;
2087  }
2088 
2089  return _ast_xmldoc_build_arguments(node);
2090 }
static const char type[]
Definition: chan_ooh323.c:109
Definition: test_heap.c:38
static const char name[]
Definition: format_mp3.c:68
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
static char * _ast_xmldoc_build_arguments(struct ast_xml_node *node)
Definition: xmldoc.c:2035
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:434
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:345

◆ ast_xmldoc_build_description()

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 2250 of file xmldoc.c.

References xmldoc_build_field().

Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().

2251 {
2252  return xmldoc_build_field(type, name, module, "description", 0);
2253 }
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
static char * xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
Definition: xmldoc.c:2190

◆ ast_xmldoc_build_documentation()

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 2653 of file xmldoc.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_link, ao2_t_ref, ast_config_AST_DATA_DIR, AST_LIST_FIRST, AST_LIST_HEAD_INIT, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, ast_log, AST_LOG_ERROR, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_doc_item_cmp(), ast_xml_doc_item_hash(), 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(), ast_xmldoc_regenerate_doc_item(), build_config_docs(), CONFIG_INFO_SYNTAX, default_documentation_language, documentation_tree::doc, documentation_language, item, MANAGER_EVENT_SYNTAX, name, ast_xml_doc_item::next, NULL, RAII_VAR, xmldoc_build_documentation_item(), and xmldoc_get_syntax_type().

Referenced by __init_manager(), and aco_init().

2654 {
2655  struct ao2_container *docs;
2656  struct ast_xml_node *node = NULL, *instance = NULL;
2657  struct documentation_tree *doctree;
2658  const char *name;
2659 
2662  if (!docs) {
2663  ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
2664  return NULL;
2665  }
2666 
2668  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2669  /* the core xml documents have priority over thirdparty document. */
2670  node = ast_xml_get_root(doctree->doc);
2671  if (!node) {
2672  break;
2673  }
2674 
2675  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
2676  struct ast_xml_doc_item *item = NULL;
2677 
2678  /* Ignore empty nodes or nodes that aren't of the type requested */
2679  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), type)) {
2680  continue;
2681  }
2682  name = ast_xml_get_attribute(node, "name");
2683  if (!name) {
2684  continue;
2685  }
2686 
2687  switch (xmldoc_get_syntax_type(type)) {
2688  case MANAGER_EVENT_SYNTAX:
2689  {
2690  struct ast_xml_doc_item_list root;
2691 
2692  AST_LIST_HEAD_INIT(&root);
2693  for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
2694  struct ast_xml_doc_item *temp;
2695  if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
2696  continue;
2697  }
2698  temp = xmldoc_build_documentation_item(instance, name, type);
2699  if (!temp) {
2700  break;
2701  }
2702  AST_LIST_INSERT_TAIL(&root, temp, next);
2703  }
2704  item = AST_LIST_FIRST(&root);
2705  break;
2706  }
2707  case CONFIG_INFO_SYNTAX:
2708  {
2709  RAII_VAR(const char *, name, ast_xml_get_attribute(node, "name"), ast_xml_free_attr);
2710 
2711  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), "configInfo")) {
2712  break;
2713  }
2714 
2715  item = xmldoc_build_documentation_item(node, name, "configInfo");
2716  if (item) {
2717  struct ast_xml_doc_item_list root;
2718 
2719  AST_LIST_HEAD_INIT(&root);
2720  AST_LIST_INSERT_TAIL(&root, item, next);
2721  build_config_docs(node, &root);
2722  }
2723  break;
2724  }
2725  default:
2726  item = xmldoc_build_documentation_item(node, name, type);
2727  }
2728  ast_xml_free_attr(name);
2729 
2730  if (item) {
2731  ao2_link(docs, item);
2732  ao2_t_ref(item, -1, "Dispose of creation ref");
2733  }
2734  }
2735  }
2737 
2738  return docs;
2739 }
#define ao2_t_ref(o, delta, tag)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:463
static int ast_xml_doc_item_cmp(void *obj, void *arg, int flags)
Definition: xmldoc.c:2340
static const char type[]
Definition: chan_ooh323.c:109
Definition: test_heap.c:38
static const char name[]
Definition: format_mp3.c:68
XML documentation tree.
Definition: xmldoc.c:54
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:420
static int ast_xml_doc_item_hash(const void *obj, const int flags)
Definition: xmldoc.c:2328
struct ast_xml_doc_item * next
Definition: xmldoc.h:80
static struct ast_xml_doc_item * xmldoc_build_documentation_item(struct ast_xml_node *node, const char *name, const char *type)
Definition: xmldoc.c:2360
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
static struct aco_type item
Definition: test_config.c:1463
#define NULL
Definition: resample.c:96
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:199
static void build_config_docs(struct ast_xml_node *cur, struct ast_xml_doc_item_list *root)
Definition: xmldoc.c:2576
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:236
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:222
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:77
#define ast_log
Definition: astobj2.c:42
#define AST_LOG_ERROR
Definition: logger.h:290
#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:911
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:730
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Definition: astobj2.h:1310
static enum syntaxtype xmldoc_get_syntax_type(const char *type)
Definition: xmldoc.c:1189
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:625
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
Generic container type.
Container of documentation trees.
Definition: xmldoc.c:75
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
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:345
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:340
#define ao2_link(container, obj)
Definition: astobj2.h:1549

◆ ast_xmldoc_build_final_response()

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 2528 of file xmldoc.c.

References ast_strlen_zero(), ast_xml_node_get_children(), documentation_language, NULL, xmldoc_build_final_response(), and xmldoc_get_node().

Referenced by ast_manager_register2().

2529 {
2530  struct ast_xml_node *node;
2531 
2533  return NULL;
2534  }
2535 
2536  node = xmldoc_get_node(type, name, module, documentation_language);
2537 
2538  if (!node || !ast_xml_node_get_children(node)) {
2539  return NULL;
2540  }
2541 
2542  return xmldoc_build_final_response(node);
2543 }
static const char type[]
Definition: chan_ooh323.c:109
Definition: test_heap.c:38
static const char name[]
Definition: format_mp3.c:68
#define NULL
Definition: resample.c:96
static struct ast_xml_doc_item * xmldoc_build_final_response(struct ast_xml_node *manager_action)
Definition: xmldoc.c:2494
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:434
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:345

◆ ast_xmldoc_build_list_responses()

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 2463 of file xmldoc.c.

References ast_strlen_zero(), ast_xml_node_get_children(), documentation_language, NULL, xmldoc_build_list_responses(), and xmldoc_get_node().

Referenced by ast_manager_register2().

2464 {
2465  struct ast_xml_node *node;
2466 
2468  return NULL;
2469  }
2470 
2471  node = xmldoc_get_node(type, name, module, documentation_language);
2472 
2473  if (!node || !ast_xml_node_get_children(node)) {
2474  return NULL;
2475  }
2476 
2477  return xmldoc_build_list_responses(node);
2478 }
static const char type[]
Definition: chan_ooh323.c:109
Definition: test_heap.c:38
static const char name[]
Definition: format_mp3.c:68
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
static struct ast_xml_doc_item * xmldoc_build_list_responses(struct ast_xml_node *manager_action)
Definition: xmldoc.c:2419
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:434
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:345

◆ ast_xmldoc_build_seealso()

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 1698 of file xmldoc.c.

References _ast_xmldoc_build_seealso(), ast_strlen_zero(), ast_xml_node_get_children(), documentation_language, NULL, and xmldoc_get_node().

Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().

1699 {
1700  char *output;
1701  struct ast_xml_node *node;
1702 
1704  return NULL;
1705  }
1706 
1707  /* get the application/function root node. */
1708  node = xmldoc_get_node(type, name, module, documentation_language);
1709  if (!node || !ast_xml_node_get_children(node)) {
1710  return NULL;
1711  }
1712 
1713  output = _ast_xmldoc_build_seealso(node);
1714 
1715  return output;
1716 }
static const char type[]
Definition: chan_ooh323.c:109
Definition: test_heap.c:38
static const char name[]
Definition: format_mp3.c:68
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
static char * _ast_xmldoc_build_seealso(struct ast_xml_node *node)
Definition: xmldoc.c:1636
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:434
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:345

◆ ast_xmldoc_build_synopsis()

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 2227 of file xmldoc.c.

References xmldoc_build_field().

Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().

2228 {
2229  return xmldoc_build_field(type, name, module, "synopsis", 1);
2230 }
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
static char * xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
Definition: xmldoc.c:2190

◆ ast_xmldoc_build_syntax()

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 1253 of file xmldoc.c.

References _ast_xmldoc_build_syntax(), documentation_language, NULL, and xmldoc_get_node().

Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().

1254 {
1255  struct ast_xml_node *node;
1256 
1257  node = xmldoc_get_node(type, name, module, documentation_language);
1258  if (!node) {
1259  return NULL;
1260  }
1261 
1262  return _ast_xmldoc_build_syntax(node, type, name);
1263 }
static const char type[]
Definition: chan_ooh323.c:109
Definition: test_heap.c:38
static const char name[]
Definition: format_mp3.c:68
#define NULL
Definition: resample.c:96
static char * _ast_xmldoc_build_syntax(struct ast_xml_node *root_node, const char *type, const char *name)
Definition: xmldoc.c:1216
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:434

◆ ast_xmldoc_printable()

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 242 of file xmldoc.c.

References ARRAY_LEN, ast_copy_string(), ast_free, ast_opt_light_background, ast_str_append(), ast_str_buffer(), ast_str_create, ast_term_color_code(), ast_term_reset(), buf, c, COLOR_CYAN, colorized_tags, end, len(), NULL, strcasestr(), tmp(), xmldoc_string_wrap(), and xmldoc_text_columns.

Referenced by cli_show_module_options(), cli_show_module_type(), cli_show_module_types(), handle_cli_agi_show(), handle_show_function(), handle_showmancmd(), print_app_docs(), print_event_instance(), and write_htmldump().

243 {
244  struct ast_str *colorized;
245  char *wrapped = NULL;
246  int i, c, len, colorsection;
247  char *tmp;
248  size_t bwinputlen;
249  static const int base_fg = COLOR_CYAN;
250 
251  if (!bwinput) {
252  return NULL;
253  }
254 
255  bwinputlen = strlen(bwinput);
256 
257  if (!(colorized = ast_str_create(256))) {
258  return NULL;
259  }
260 
261  if (withcolors) {
262  ast_term_color_code(&colorized, base_fg, 0);
263  if (!colorized) {
264  return NULL;
265  }
266  }
267 
268  for (i = 0; i < bwinputlen; i++) {
269  colorsection = 0;
270  /* Check if we are at the beginning of a tag to be colorized. */
271  for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
272  if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
273  continue;
274  }
275 
276  if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
277  continue;
278  }
279 
280  len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
281 
282  /* Setup color */
283  if (withcolors) {
285  /* Turn off *bright* colors */
286  ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
287  } else {
288  /* Turn on *bright* colors */
289  ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
290  }
291  if (!colorized) {
292  return NULL;
293  }
294  }
295 
296  /* copy initial string replace */
297  ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
298  if (!colorized) {
299  return NULL;
300  }
301  {
302  char buf[len + 1];
303  ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
304  ast_str_append(&colorized, 0, "%s", buf);
305  }
306  if (!colorized) {
307  return NULL;
308  }
309 
310  /* copy the ending string replace */
311  ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
312  if (!colorized) {
313  return NULL;
314  }
315 
316  /* Continue with the last color. */
317  if (withcolors) {
318  ast_term_color_code(&colorized, base_fg, 0);
319  if (!colorized) {
320  return NULL;
321  }
322  }
323 
324  i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
325  colorsection = 1;
326  break;
327  }
328 
329  if (!colorsection) {
330  ast_str_append(&colorized, 0, "%c", bwinput[i]);
331  if (!colorized) {
332  return NULL;
333  }
334  }
335  }
336 
337  if (withcolors) {
338  ast_str_append(&colorized, 0, "%s", ast_term_reset());
339  if (!colorized) {
340  return NULL;
341  }
342  }
343 
344  /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
346 
347  ast_free(colorized);
348 
349  return wrapped;
350 }
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const struct strcolorized_tags colorized_tags[]
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:714
#define COLOR_CYAN
Definition: term.h:59
static int tmp()
Definition: bt_open.c:389
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:1091
static struct test_val c
#define NULL
Definition: resample.c:96
char * end
Definition: eagi_proxy.c:73
#define ARRAY_LEN(a)
Definition: utils.h:639
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
static const int xmldoc_text_columns
Number of columns to print when showing the XML documentation with a &#39;core show application/function ...
Definition: xmldoc.c:48
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
char * strcasestr(const char *, const char *)
#define ast_free(a)
Definition: astmm.h:182
const char * ast_term_reset(void)
Returns the terminal reset code.
Definition: term.c:357
#define ast_opt_light_background
Definition: options.h:130
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:401
static char * xmldoc_string_wrap(const char *text, int columns)
Definition: xmldoc.c:176
#define ast_str_create(init_len)
Create a malloc&#39;ed dynamic length string.
Definition: strings.h:620

◆ ast_xmldoc_query()

struct ast_xml_xpath_results* ast_xmldoc_query ( const char *  fmt,
  ... 
)

Execute an XPath query on the loaded XML documentation.

Parameters
queryThe 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 2545 of file xmldoc.c.

References AST_DYNSTR_BUILD_FAILED, ast_free, 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, NULL, and RAII_VAR.

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

2546 {
2547  struct ast_xml_xpath_results *results = NULL;
2548  struct documentation_tree *doctree;
2549  RAII_VAR(struct ast_str *, xpath_str, ast_str_create(128), ast_free);
2550  va_list ap;
2551  int res;
2552 
2553  if (!xpath_str) {
2554  return NULL;
2555  }
2556 
2557  va_start(ap, fmt);
2558  res = ast_str_set_va(&xpath_str, 0, fmt, ap);
2559  va_end(ap);
2560  if (res == AST_DYNSTR_BUILD_FAILED) {
2561  return NULL;
2562  }
2563 
2565  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2566  if (!(results = ast_xml_query(doctree->doc, ast_str_buffer(xpath_str)))) {
2567  continue;
2568  }
2569  break;
2570  }
2572 
2573  return results;
2574 }
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:714
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
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:982
#define NULL
Definition: resample.c:96
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:77
#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:911
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:380
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
#define ast_free(a)
Definition: astmm.h:182
Definition: search.h:40
Container of documentation trees.
Definition: xmldoc.c:75
#define ast_str_create(init_len)
Create a malloc&#39;ed dynamic length string.
Definition: strings.h:620

◆ ast_xmldoc_regenerate_doc_item()

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 2604 of file xmldoc.c.

References _ast_xmldoc_build_arguments(), _ast_xmldoc_build_description(), _ast_xmldoc_build_seealso(), _ast_xmldoc_build_synopsis(), _ast_xmldoc_build_syntax(), ast_xml_doc_item::arguments, ast_free, ast_str_set(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_doc_item::description, name, ast_xml_doc_item::node, ast_xml_doc_item::seealso, ast_xml_doc_item::synopsis, synopsis, ast_xml_doc_item::syntax, and ast_xml_doc_item::type.

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

2605 {
2606  const char *name;
2607  char *syntax;
2608  char *seealso;
2609  char *arguments;
2610  char *synopsis;
2611  char *description;
2612 
2613  if (!item || !item->node) {
2614  return -1;
2615  }
2616 
2617  name = ast_xml_get_attribute(item->node, "name");
2618  if (!name) {
2619  return -1;
2620  }
2621 
2622  syntax = _ast_xmldoc_build_syntax(item->node, item->type, name);
2623  seealso = _ast_xmldoc_build_seealso(item->node);
2624  arguments = _ast_xmldoc_build_arguments(item->node);
2625  synopsis = _ast_xmldoc_build_synopsis(item->node);
2626  description = _ast_xmldoc_build_description(item->node);
2627 
2628  if (syntax) {
2629  ast_str_set(&item->syntax, 0, "%s", syntax);
2630  }
2631  if (seealso) {
2632  ast_str_set(&item->seealso, 0, "%s", seealso);
2633  }
2634  if (arguments) {
2635  ast_str_set(&item->arguments, 0, "%s", arguments);
2636  }
2637  if (synopsis) {
2638  ast_str_set(&item->synopsis, 0, "%s", synopsis);
2639  }
2640  if (description) {
2641  ast_str_set(&item->description, 0, "%s", description);
2642  }
2643 
2644  ast_free(syntax);
2645  ast_free(seealso);
2646  ast_free(arguments);
2647  ast_free(synopsis);
2648  ast_free(description);
2649  ast_xml_free_attr(name);
2650  return 0;
2651 }
static const char name[]
Definition: format_mp3.c:68
static char * _ast_xmldoc_build_synopsis(struct ast_xml_node *node)
Definition: xmldoc.c:2222
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:236
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:222
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:1065
const ast_string_field type
Definition: xmldoc.h:74
static char * _ast_xmldoc_build_syntax(struct ast_xml_node *root_node, const char *type, const char *name)
Definition: xmldoc.c:1216
static char * _ast_xmldoc_build_description(struct ast_xml_node *node)
Definition: xmldoc.c:2245
struct ast_str * description
Definition: xmldoc.h:66
static char * synopsis
Definition: func_enum.c:154
#define ast_free(a)
Definition: astmm.h:182
static char * _ast_xmldoc_build_seealso(struct ast_xml_node *node)
Definition: xmldoc.c:1636
static char * _ast_xmldoc_build_arguments(struct ast_xml_node *node)
Definition: xmldoc.c:2035
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