Wed Jan 8 2020 09:50:22

Asterisk developer's documentation


xmldoc.h File Reference

Asterisk XML Documentation API. More...

#include "asterisk/xml.h"

Go to the source code of this file.

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...
 
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...
 

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 28 of file xmldoc.h.

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

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

References ast_free, ast_str_buffer(), ast_str_create(), ast_str_strlen(), ast_str_truncate(), ast_strdup, ast_strlen_zero(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_get_node(), and xmldoc_parse_parameter().

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

1762 {
1763  struct ast_xml_node *node;
1764  struct ast_str *ret = ast_str_create(128);
1765  char *retstr = NULL;
1766 
1768  ast_free(ret);
1769  return NULL;
1770  }
1771 
1772  node = xmldoc_get_node(type, name, module, documentation_language);
1773 
1774  if (!node || !ast_xml_node_get_children(node)) {
1775  ast_free(ret);
1776  return NULL;
1777  }
1778 
1779  /* Find the syntax field. */
1780  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1781  if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1782  break;
1783  }
1784  }
1785 
1786  if (!node || !ast_xml_node_get_children(node)) {
1787  /* We couldn't find the syntax node. */
1788  ast_free(ret);
1789  return NULL;
1790  }
1791 
1792  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1793  xmldoc_parse_parameter(node, "", &ret);
1794  }
1795 
1796  if (ast_str_strlen(ret) > 0) {
1797  /* remove last '\n' */
1798  char *buf = ast_str_buffer(ret);
1799  if (buf[ast_str_strlen(ret) - 1] == '\n') {
1800  ast_str_truncate(ret, -1);
1801  }
1802  retstr = ast_strdup(ast_str_buffer(ret));
1803  }
1804  ast_free(ret);
1805 
1806  return retstr;
1807 }
#define ast_strdup(a)
Definition: astmm.h:109
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
struct ast_str * ast_str_create(size_t init_len)
Create a malloc&#39;ed dynamic length string.
Definition: strings.h:420
char * ast_str_truncate(struct ast_str *buf, ssize_t len)
Truncates the enclosed string to the given length.
Definition: strings.h:521
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:57
static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1704
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
static const char name[]
#define ast_free(a)
Definition: astmm.h:97
static const char type[]
Definition: chan_nbs.c:57
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:471
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
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:495
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:299
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:294
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 1899 of file xmldoc.c.

References xmldoc_build_field().

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

1900 {
1901  return xmldoc_build_field(type, name, module, "description", 0);
1902 }
static char * xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
Get the content of a field (synopsis, description, etc) from an asterisk document tree...
Definition: xmldoc.c:1861
static const char name[]
static const char type[]
Definition: chan_nbs.c:57
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 1461 of file xmldoc.c.

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_strdup, ast_strlen_zero(), ast_xml_free_attr(), ast_xml_free_text(), ast_xml_get_attribute(), ast_xml_get_text(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), first, and xmldoc_get_node().

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

1462 {
1463  struct ast_str *outputstr;
1464  char *output;
1465  struct ast_xml_node *node;
1466  const char *typename;
1467  const char *content;
1468  int first = 1;
1469 
1471  return NULL;
1472  }
1473 
1474  /* get the application/function root node. */
1475  node = xmldoc_get_node(type, name, module, documentation_language);
1476  if (!node || !ast_xml_node_get_children(node)) {
1477  return NULL;
1478  }
1479 
1480  /* Find the <see-also> node. */
1481  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1482  if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
1483  break;
1484  }
1485  }
1486 
1487  if (!node || !ast_xml_node_get_children(node)) {
1488  /* we couldnt find a <see-also> node. */
1489  return NULL;
1490  }
1491 
1492  /* prepare the output string. */
1493  outputstr = ast_str_create(128);
1494  if (!outputstr) {
1495  return NULL;
1496  }
1497 
1498  /* get into the <see-also> node. */
1499  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1500  if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
1501  continue;
1502  }
1503 
1504  /* parse the <ref> node. 'type' attribute is required. */
1505  typename = ast_xml_get_attribute(node, "type");
1506  if (!typename) {
1507  continue;
1508  }
1509  content = ast_xml_get_text(node);
1510  if (!content) {
1511  ast_xml_free_attr(typename);
1512  continue;
1513  }
1514  if (!strcasecmp(typename, "application")) {
1515  ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
1516  } else if (!strcasecmp(typename, "function")) {
1517  ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1518  } else if (!strcasecmp(typename, "astcli")) {
1519  ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
1520  } else {
1521  ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1522  }
1523  first = 0;
1524  ast_xml_free_text(content);
1525  ast_xml_free_attr(typename);
1526  }
1527 
1528  output = ast_strdup(ast_str_buffer(outputstr));
1529  ast_free(outputstr);
1530 
1531  return output;
1532 }
#define ast_strdup(a)
Definition: astmm.h:109
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
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:900
struct ast_str * ast_str_create(size_t init_len)
Create a malloc&#39;ed dynamic length string.
Definition: strings.h:420
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 force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:57
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
struct sla_ringing_trunk * first
Definition: app_meetme.c:965
static const char name[]
#define ast_free(a)
Definition: astmm.h:97
static const char type[]
Definition: chan_nbs.c:57
const char * ast_xml_get_text(struct ast_xml_node *node)
Get an element content string.
Definition: xml.c:271
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
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:495
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:299
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:294
void ast_xml_free_text(const char *text)
Free a content element that was returned by ast_xml_get_text()
Definition: xml.c:183
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 1894 of file xmldoc.c.

References xmldoc_build_field().

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

1895 {
1896  return xmldoc_build_field(type, name, module, "synopsis", 1);
1897 }
static char * xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
Get the content of a field (synopsis, description, etc) from an asterisk document tree...
Definition: xmldoc.c:1861
static const char name[]
static const char type[]
Definition: chan_nbs.c:57
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 1156 of file xmldoc.c.

References ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), COMMAND_SYNTAX, FUNCTION_SYNTAX, MANAGER_SYNTAX, xmldoc_get_node(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_fun(), xmldoc_get_syntax_manager(), and xmldoc_get_syntax_type().

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

1157 {
1158  struct ast_xml_node *node;
1159  char *syntax = NULL;
1160 
1161  node = xmldoc_get_node(type, name, module, documentation_language);
1162  if (!node) {
1163  return NULL;
1164  }
1165 
1166  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1167  if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1168  break;
1169  }
1170  }
1171 
1172  if (node) {
1173  switch (xmldoc_get_syntax_type(type)) {
1174  case FUNCTION_SYNTAX:
1175  syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1176  break;
1177  case COMMAND_SYNTAX:
1178  syntax = xmldoc_get_syntax_cmd(node, name, 1);
1179  break;
1180  case MANAGER_SYNTAX:
1181  syntax = xmldoc_get_syntax_manager(node, name);
1182  break;
1183  default:
1184  syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1185  }
1186  }
1187  return syntax;
1188 }
static char * xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
Definition: xmldoc.c:974
static char * xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name)
Definition: xmldoc.c:1072
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:57
static enum syntaxtype xmldoc_get_syntax_type(const char *type)
Definition: xmldoc.c:1144
static const char name[]
static const char type[]
Definition: chan_nbs.c:57
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
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:495
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node&#39;s children.
Definition: xml.c:299
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:294
static char * xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
Definition: xmldoc.c:685
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 315 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(), COLOR_CYAN, colorized_tags, len(), strcasestr(), term_end(), and xmldoc_string_wrap().

Referenced by handle_cli_agi_show(), handle_show_function(), handle_showmancmd(), print_app_docs(), and write_htmldump().

316 {
317  struct ast_str *colorized;
318  char *wrapped = NULL;
319  int i, c, len, colorsection;
320  char *tmp;
321  size_t bwinputlen;
322  static const int base_fg = COLOR_CYAN;
323 
324  if (!bwinput) {
325  return NULL;
326  }
327 
328  bwinputlen = strlen(bwinput);
329 
330  if (!(colorized = ast_str_create(256))) {
331  return NULL;
332  }
333 
334  if (withcolors) {
335  ast_term_color_code(&colorized, base_fg, 0);
336  if (!colorized) {
337  return NULL;
338  }
339  }
340 
341  for (i = 0; i < bwinputlen; i++) {
342  colorsection = 0;
343  /* Check if we are at the beginning of a tag to be colorized. */
344  for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
345  if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
346  continue;
347  }
348 
349  if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
350  continue;
351  }
352 
353  len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
354 
355  /* Setup color */
356  if (withcolors) {
358  /* Turn off *bright* colors */
359  ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
360  } else {
361  /* Turn on *bright* colors */
362  ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
363  }
364  if (!colorized) {
365  return NULL;
366  }
367  }
368 
369  /* copy initial string replace */
370  ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
371  if (!colorized) {
372  return NULL;
373  }
374  {
375  char buf[len + 1];
376  ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
377  ast_str_append(&colorized, 0, "%s", buf);
378  }
379  if (!colorized) {
380  return NULL;
381  }
382 
383  /* copy the ending string replace */
384  ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
385  if (!colorized) {
386  return NULL;
387  }
388 
389  /* Continue with the last color. */
390  if (withcolors) {
391  ast_term_color_code(&colorized, base_fg, 0);
392  if (!colorized) {
393  return NULL;
394  }
395  }
396 
397  i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
398  colorsection = 1;
399  break;
400  }
401 
402  if (!colorsection) {
403  ast_str_append(&colorized, 0, "%c", bwinput[i]);
404  if (!colorized) {
405  return NULL;
406  }
407  }
408  }
409 
410  if (withcolors) {
411  ast_str_append(&colorized, 0, "%s", term_end());
412  if (!colorized) {
413  return NULL;
414  }
415  }
416 
417  /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
419 
420  ast_free(colorized);
421 
422  return wrapped;
423 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
#define COLOR_CYAN
Definition: term.h:59
int ast_term_color_code(struct ast_str **str, int fgcolor, int bgcolor)
Append a color sequence to an ast_str.
Definition: term.c:242
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:900
struct ast_str * ast_str_create(size_t init_len)
Create a malloc&#39;ed dynamic length string.
Definition: strings.h:420
static char * xmldoc_string_wrap(const char *text, int columns, int maxdiff)
Definition: xmldoc.c:238
static const int xmldoc_max_diff
This is a value that we will use to let the wrapping mechanism move the cursor backward and forward x...
Definition: xmldoc.c:54
static struct strcolorized_tags colorized_tags[]
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
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:49
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#define ast_free(a)
Definition: astmm.h:97
#define ast_opt_light_background
Definition: options.h:128
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:223
char * strcasestr(const char *, const char *)
char * term_end(void)
Definition: term.c:365