Asterisk - The Open Source Telephony Project  GIT-master-a24979a
Data Structures | Macros | Enumerations | Functions | Variables
xmldoc.c File Reference

XML Documentation API. More...

#include "asterisk.h"
#include "asterisk/_private.h"
#include "asterisk/paths.h"
#include "asterisk/linkedlists.h"
#include "asterisk/config.h"
#include "asterisk/term.h"
#include "asterisk/astobj2.h"
#include "asterisk/xmldoc.h"
#include "asterisk/cli.h"
Include dependency graph for xmldoc.c:

Go to the source code of this file.

Data Structures

struct  documentation_tree
 XML documentation tree. More...
 
struct  strcolorized_tags
 
struct  strspecial_tags
 
struct  strsyntaxtype
 Mapping between type of node and type of syntax to generate. More...
 
struct  xmldoc_tree
 Container of documentation trees. More...
 

Macros

#define GOTONEXT(__rev, __a)   (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
 
#define ISLAST(__rev, __a)   (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
 
#define MP(__a)   ((multiple ? __a : ""))
 

Enumerations

enum  syntaxtype {
  FUNCTION_SYNTAX , MANAGER_SYNTAX , MANAGER_EVENT_SYNTAX , CONFIG_INFO_SYNTAX ,
  CONFIG_FILE_SYNTAX , CONFIG_OPTION_SYNTAX , CONFIG_OBJECT_SYNTAX , COMMAND_SYNTAX
}
 Types of syntax that we are able to generate. More...
 

Functions

static char * _ast_xmldoc_build_arguments (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_description (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_seealso (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_synopsis (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_syntax (struct ast_xml_node *root_node, const char *type, const char *name)
 
static char * _xmldoc_build_field (struct ast_xml_node *node, const char *var, int raw)
 
static struct ast_xml_doc_itemast_xml_doc_item_alloc (const char *name, const char *type)
 
static int ast_xml_doc_item_cmp (void *obj, void *arg, int flags)
 
static void ast_xml_doc_item_destructor (void *obj)
 
static int ast_xml_doc_item_hash (const void *obj, const int flags)
 
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...
 
int ast_xmldoc_load_documentation (void)
 Load XML documentation. Provided by xmldoc.c. 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...
 
static void build_config_docs (struct ast_xml_node *cur, struct ast_xml_doc_item_list *root)
 
static char * handle_dump_docs (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 
static int xmldoc_attribute_match (struct ast_xml_node *node, const char *attr, const char *value)
 
static struct ast_xml_doc_itemxmldoc_build_documentation_item (struct ast_xml_node *node, const char *name, const char *type)
 
static char * xmldoc_build_field (const char *type, const char *name, const char *module, const char *var, int raw)
 
static struct ast_xml_doc_itemxmldoc_build_final_response (struct ast_xml_node *manager_action)
 
static struct ast_xml_doc_itemxmldoc_build_list_responses (struct ast_xml_node *manager_action)
 
static struct ast_strxmldoc_get_formatted (struct ast_xml_node *node, int raw_output, int raw_wrap)
 
static struct ast_xml_node * xmldoc_get_node (const char *type, const char *name, const char *module, const char *language)
 
static char * xmldoc_get_syntax_cmd (struct ast_xml_node *fixnode, const char *name, int printname)
 
static char * xmldoc_get_syntax_config_object (struct ast_xml_node *fixnode, const char *name)
 
static char * xmldoc_get_syntax_config_option (struct ast_xml_node *fixnode, const char *name)
 
static char * xmldoc_get_syntax_fun (struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
 
static char * xmldoc_get_syntax_manager (struct ast_xml_node *fixnode, const char *name, const char *manager_type)
 
static enum syntaxtype xmldoc_get_syntax_type (const char *type)
 
static int xmldoc_has_inside (struct ast_xml_node *fixnode, const char *what)
 
static int xmldoc_has_nodes (struct ast_xml_node *fixnode)
 
static int xmldoc_has_specialtags (struct ast_xml_node *fixnode)
 
static int xmldoc_parse_argument (struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer)
 
static char * xmldoc_parse_cmd_enumlist (struct ast_xml_node *fixnode)
 
static int xmldoc_parse_common_elements (struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
 
static int xmldoc_parse_enum (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
 
static int xmldoc_parse_enumlist (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
 
static int xmldoc_parse_example (struct ast_xml_node *fixnode, struct ast_str **buffer)
 
static int xmldoc_parse_info (struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
 
static int xmldoc_parse_option (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
 
static void xmldoc_parse_optionlist (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
 
static int xmldoc_parse_para (struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
 
static void xmldoc_parse_parameter (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
 
static int xmldoc_parse_specialtags (struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
 
static int xmldoc_parse_variable (struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
 
static int xmldoc_parse_variablelist (struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
 
static int xmldoc_postbrlen (const char *postbr)
 
static void xmldoc_reverse_helper (int reverse, int *len, char **syntax, const char *fmt,...)
 
static void xmldoc_setpostbr (char *postbr, size_t len, const char *text)
 
static void xmldoc_string_cleanup (const char *text, struct ast_str **output, int lastspaces, int maintain_newlines)
 
static char * xmldoc_string_wrap (const char *text, int columns)
 
static void xmldoc_unload_documentation (void)
 Close and unload XML documentation. More...
 

Variables

static struct ast_cli_entry cli_dump_xmldocs = { .handler = handle_dump_docs , .summary = "Dump the XML docs to the specified file" ,}
 
static const struct strcolorized_tags colorized_tags []
 
static const char default_documentation_language [] = "en_US"
 Default documentation language. More...
 
static char documentation_language [6]
 XML documentation language. More...
 
static const struct strspecial_tags special_tags []
 
static struct strsyntaxtype stxtype []
 
static const int xmldoc_text_columns = 79
 Number of columns to print when showing the XML documentation with a 'core show application/function *' CLI command. Used in text wrapping. More...
 
static struct xmldoc_tree xmldoc_tree = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }
 

Detailed Description

XML Documentation API.

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

libxml2 http://www.xmlsoft.org/

Definition in file xmldoc.c.

Macro Definition Documentation

◆ GOTONEXT

#define GOTONEXT (   __rev,
  __a 
)    (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))

◆ ISLAST

#define ISLAST (   __rev,
  __a 
)    (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))

◆ MP

#define MP (   __a)    ((multiple ? __a : ""))

Enumeration Type Documentation

◆ syntaxtype

enum syntaxtype

Types of syntax that we are able to generate.

Enumerator
FUNCTION_SYNTAX 
MANAGER_SYNTAX 
MANAGER_EVENT_SYNTAX 
CONFIG_INFO_SYNTAX 
CONFIG_FILE_SYNTAX 
CONFIG_OPTION_SYNTAX 
CONFIG_OBJECT_SYNTAX 
COMMAND_SYNTAX 

Definition at line 1154 of file xmldoc.c.

1154  {
1163 };
@ CONFIG_INFO_SYNTAX
Definition: xmldoc.c:1158
@ FUNCTION_SYNTAX
Definition: xmldoc.c:1155
@ CONFIG_OBJECT_SYNTAX
Definition: xmldoc.c:1161
@ CONFIG_OPTION_SYNTAX
Definition: xmldoc.c:1160
@ CONFIG_FILE_SYNTAX
Definition: xmldoc.c:1159
@ MANAGER_EVENT_SYNTAX
Definition: xmldoc.c:1157
@ COMMAND_SYNTAX
Definition: xmldoc.c:1162
@ MANAGER_SYNTAX
Definition: xmldoc.c:1156

Function Documentation

◆ _ast_xmldoc_build_arguments()

static char* _ast_xmldoc_build_arguments ( struct ast_xml_node *  node)
static

Definition at line 2037 of file xmldoc.c.

2038 {
2039  char *retstr = NULL;
2040  struct ast_str *ret;
2041 
2042  ret = ast_str_create(128);
2043  if (!ret) {
2044  return NULL;
2045  }
2046 
2047  /* Find the syntax field. */
2049  if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
2050  break;
2051  }
2052  }
2053 
2054  if (!node || !ast_xml_node_get_children(node)) {
2055  /* We couldn't find the syntax node. */
2056  ast_free(ret);
2057  return NULL;
2058  }
2059 
2061  xmldoc_parse_parameter(node, "", &ret);
2062  }
2063 
2064  if (ast_str_strlen(ret) > 0) {
2065  /* remove last '\n' */
2066  char *buf = ast_str_buffer(ret);
2067  if (buf[ast_str_strlen(ret) - 1] == '\n') {
2068  ast_str_truncate(ret, -1);
2069  }
2070  retstr = ast_strdup(ast_str_buffer(ret));
2071  }
2072  ast_free(ret);
2073 
2074  return retstr;
2075 }
#define ast_free(a)
Definition: astmm.h:180
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
#define NULL
Definition: resample.c:96
char * ast_str_truncate(struct ast_str *buf, ssize_t len)
Truncates the enclosed string to the given length.
Definition: strings.h:764
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:739
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:640
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:711
Support for dynamic strings.
Definition: strings.h:604
Definition: test_heap.c:38
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:364
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:369
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:374
static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1900

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

Referenced by ast_xmldoc_build_arguments(), ast_xmldoc_regenerate_doc_item(), and xmldoc_build_documentation_item().

◆ _ast_xmldoc_build_description()

static char* _ast_xmldoc_build_description ( struct ast_xml_node *  node)
static

Definition at line 2247 of file xmldoc.c.

2248 {
2249  return _xmldoc_build_field(node, "description", 0);
2250 }
static char * _xmldoc_build_field(struct ast_xml_node *node, const char *var, int raw)
Definition: xmldoc.c:2159

References _xmldoc_build_field().

Referenced by ast_xmldoc_regenerate_doc_item(), and xmldoc_build_documentation_item().

◆ _ast_xmldoc_build_seealso()

static char* _ast_xmldoc_build_seealso ( struct ast_xml_node *  node)
static

Definition at line 1636 of file xmldoc.c.

1637 {
1638  char *output;
1639  struct ast_str *outputstr;
1640  const char *typename;
1641  const char *content;
1642  int first = 1;
1643 
1644  /* Find the <see-also> node. */
1646  if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
1647  break;
1648  }
1649  }
1650 
1651  if (!node || !ast_xml_node_get_children(node)) {
1652  /* we couldnt find a <see-also> node. */
1653  return NULL;
1654  }
1655 
1656  /* prepare the output string. */
1657  outputstr = ast_str_create(128);
1658  if (!outputstr) {
1659  return NULL;
1660  }
1661 
1662  /* get into the <see-also> node. */
1664  if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
1665  continue;
1666  }
1667 
1668  /* parse the <ref> node. 'type' attribute is required. */
1669  typename = ast_xml_get_attribute(node, "type");
1670  if (!typename) {
1671  continue;
1672  }
1673  content = ast_xml_get_text(node);
1674  if (!content) {
1675  ast_xml_free_attr(typename);
1676  continue;
1677  }
1678  if (!strcasecmp(typename, "application")) {
1679  ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
1680  } else if (!strcasecmp(typename, "function")) {
1681  ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1682  } else if (!strcasecmp(typename, "astcli")) {
1683  ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
1684  } else {
1685  ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1686  }
1687  first = 0;
1688  ast_xml_free_text(content);
1689  ast_xml_free_attr(typename);
1690  }
1691 
1692  output = ast_strdup(ast_str_buffer(outputstr));
1693  ast_free(outputstr);
1694 
1695  return output;
1696 }
struct sla_ringing_trunk * first
Definition: app_meetme.c:1094
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:1117
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:232
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:246
const char * ast_xml_get_text(struct ast_xml_node *node)
Get an element content string.
Definition: xml.c:332
void ast_xml_free_text(const char *text)
Free a content element that was returned by ast_xml_get_text()
Definition: xml.c:239

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strdup, 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 NULL.

Referenced by ast_xmldoc_build_seealso(), ast_xmldoc_regenerate_doc_item(), and xmldoc_build_documentation_item().

◆ _ast_xmldoc_build_synopsis()

static char* _ast_xmldoc_build_synopsis ( struct ast_xml_node *  node)
static

Definition at line 2224 of file xmldoc.c.

2225 {
2226  return _xmldoc_build_field(node, "synopsis", 1);
2227 }

References _xmldoc_build_field().

Referenced by ast_xmldoc_regenerate_doc_item(), and xmldoc_build_documentation_item().

◆ _ast_xmldoc_build_syntax()

static char* _ast_xmldoc_build_syntax ( struct ast_xml_node *  root_node,
const char *  type,
const char *  name 
)
static

Definition at line 1216 of file xmldoc.c.

1217 {
1218  char *syntax = NULL;
1219  struct ast_xml_node *node = root_node;
1220 
1222  if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1223  break;
1224  }
1225  }
1226 
1227  switch (xmldoc_get_syntax_type(type)) {
1228  case FUNCTION_SYNTAX:
1229  syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1230  break;
1231  case COMMAND_SYNTAX:
1232  syntax = xmldoc_get_syntax_cmd(node, name, 1);
1233  break;
1234  case MANAGER_SYNTAX:
1235  syntax = xmldoc_get_syntax_manager(node, name, "Action");
1236  break;
1237  case MANAGER_EVENT_SYNTAX:
1238  syntax = xmldoc_get_syntax_manager(node, name, "Event");
1239  break;
1240  case CONFIG_OPTION_SYNTAX:
1241  syntax = xmldoc_get_syntax_config_option(root_node, name);
1242  break;
1243  case CONFIG_OBJECT_SYNTAX:
1245  break;
1246  default:
1247  syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1248  }
1249 
1250  return syntax;
1251 }
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
static char * xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name, const char *manager_type)
Definition: xmldoc.c:1038
static char * xmldoc_get_syntax_config_option(struct ast_xml_node *fixnode, const char *name)
Definition: xmldoc.c:1126
static enum syntaxtype xmldoc_get_syntax_type(const char *type)
Definition: xmldoc.c:1189
static char * xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
Definition: xmldoc.c:638
static char * xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
Definition: xmldoc.c:932
static char * xmldoc_get_syntax_config_object(struct ast_xml_node *fixnode, const char *name)
Definition: xmldoc.c:1090

References ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), COMMAND_SYNTAX, CONFIG_OBJECT_SYNTAX, CONFIG_OPTION_SYNTAX, FUNCTION_SYNTAX, MANAGER_EVENT_SYNTAX, MANAGER_SYNTAX, name, NULL, type, xmldoc_get_syntax_cmd(), xmldoc_get_syntax_config_object(), xmldoc_get_syntax_config_option(), xmldoc_get_syntax_fun(), xmldoc_get_syntax_manager(), and xmldoc_get_syntax_type().

Referenced by ast_xmldoc_build_syntax(), ast_xmldoc_regenerate_doc_item(), and xmldoc_build_documentation_item().

◆ _xmldoc_build_field()

static char* _xmldoc_build_field ( struct ast_xml_node *  node,
const char *  var,
int  raw 
)
static

Definition at line 2159 of file xmldoc.c.

2160 {
2161  char *ret = NULL;
2162  struct ast_str *formatted;
2163 
2165 
2166  if (!node || !ast_xml_node_get_children(node)) {
2167  return ret;
2168  }
2169 
2170  formatted = xmldoc_get_formatted(node, raw, raw);
2171  if (formatted && ast_str_strlen(formatted) > 0) {
2172  ret = ast_strdup(ast_str_buffer(formatted));
2173  }
2174  ast_free(formatted);
2175 
2176  return ret;
2177 }
#define var
Definition: ast_expr2f.c:614
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.
Definition: xml.c:276
static struct ast_str * xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
Definition: xmldoc.c:2105

References ast_free, ast_str_buffer(), ast_str_strlen(), ast_strdup, ast_xml_find_element(), ast_xml_node_get_children(), NULL, var, and xmldoc_get_formatted().

Referenced by _ast_xmldoc_build_description(), _ast_xmldoc_build_synopsis(), and xmldoc_build_field().

◆ ast_xml_doc_item_alloc()

static struct ast_xml_doc_item* ast_xml_doc_item_alloc ( const char *  name,
const char *  type 
)
static

Definition at line 2291 of file xmldoc.c.

2292 {
2293  struct ast_xml_doc_item *item;
2294 
2297  if (!item) {
2298  ast_log(AST_LOG_ERROR, "Failed to allocate memory for ast_xml_doc_item instance\n");
2299  return NULL;
2300  }
2301 
2302  if ( !(item->syntax = ast_str_create(128))
2303  || !(item->seealso = ast_str_create(128))
2304  || !(item->arguments = ast_str_create(128))
2305  || !(item->synopsis = ast_str_create(128))
2306  || !(item->description = ast_str_create(128))) {
2307  ast_log(AST_LOG_ERROR, "Failed to allocate strings for ast_xml_doc_item instance\n");
2308  goto ast_xml_doc_item_failure;
2309  }
2310 
2311  if (ast_string_field_init(item, 64)) {
2312  ast_log(AST_LOG_ERROR, "Failed to initialize string field for ast_xml_doc_item instance\n");
2313  goto ast_xml_doc_item_failure;
2314  }
2317 
2318  return item;
2319 
2320 ast_xml_doc_item_failure:
2321  ao2_ref(item, -1);
2322  return NULL;
2323 }
#define ast_log
Definition: astobj2.c:42
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_alloc_options(data_size, destructor_fn, options)
Definition: astobj2.h:404
#define AST_LOG_ERROR
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:521
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
static struct aco_type item
Definition: test_config.c:1463
static void ast_xml_doc_item_destructor(void *obj)
Definition: xmldoc.c:2262

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, ast_log, AST_LOG_ERROR, ast_str_create, ast_string_field_init, ast_string_field_set, ast_xml_doc_item_destructor(), item, name, NULL, and type.

Referenced by xmldoc_build_documentation_item().

◆ ast_xml_doc_item_cmp()

static int ast_xml_doc_item_cmp ( void *  obj,
void *  arg,
int  flags 
)
static

Definition at line 2342 of file xmldoc.c.

2343 {
2344  struct ast_xml_doc_item *left = obj;
2345  struct ast_xml_doc_item *right = arg;
2346  const char *match = (flags & OBJ_KEY) ? arg : right->name;
2347  return strcasecmp(left->name, match) ? 0 : (CMP_MATCH | CMP_STOP);
2348 }
@ CMP_MATCH
Definition: astobj2.h:1027
@ CMP_STOP
Definition: astobj2.h:1028
#define OBJ_KEY
Definition: astobj2.h:1151
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2312
const ast_string_field name
Definition: xmldoc.h:74

References CMP_MATCH, CMP_STOP, match(), ast_xml_doc_item::name, and OBJ_KEY.

Referenced by ast_xmldoc_build_documentation().

◆ ast_xml_doc_item_destructor()

static void ast_xml_doc_item_destructor ( void *  obj)
static

Definition at line 2262 of file xmldoc.c.

2263 {
2264  struct ast_xml_doc_item *doc = obj;
2265 
2266  if (!doc) {
2267  return;
2268  }
2269 
2270  ast_free(doc->syntax);
2271  ast_free(doc->seealso);
2272  ast_free(doc->arguments);
2273  ast_free(doc->synopsis);
2274  ast_free(doc->description);
2276 
2277  if (AST_LIST_NEXT(doc, next)) {
2278  ao2_ref(AST_LIST_NEXT(doc, next), -1);
2279  AST_LIST_NEXT(doc, next) = NULL;
2280  }
2281 }
#define AST_LIST_NEXT(elm, field)
Returns the next entry in the list after the given entry.
Definition: linkedlists.h:439
#define ast_string_field_free_memory(x)
free all memory - to be called before destroying the object
Definition: stringfields.h:374
struct ast_str * syntax
Definition: xmldoc.h:58
struct ast_xml_doc_item * next
Definition: xmldoc.h:80
struct ast_str * arguments
Definition: xmldoc.h:62
struct ast_str * description
Definition: xmldoc.h:66
struct ast_str * seealso
Definition: xmldoc.h:60
struct ast_str * synopsis
Definition: xmldoc.h:64

References ao2_ref, ast_xml_doc_item::arguments, ast_free, AST_LIST_NEXT, ast_string_field_free_memory, ast_xml_doc_item::description, ast_xml_doc_item::next, NULL, ast_xml_doc_item::seealso, ast_xml_doc_item::synopsis, and ast_xml_doc_item::syntax.

Referenced by ast_xml_doc_item_alloc().

◆ ast_xml_doc_item_hash()

static int ast_xml_doc_item_hash ( const void *  obj,
const int  flags 
)
static

Definition at line 2330 of file xmldoc.c.

2331 {
2332  const struct ast_xml_doc_item *item = obj;
2333  const char *name = (flags & OBJ_KEY) ? obj : item->name;
2334  return ast_str_case_hash(name);
2335 }
static force_inline int attribute_pure ast_str_case_hash(const char *str)
Compute a hash value on a case-insensitive string.
Definition: strings.h:1281
const char * name

References ast_str_case_hash(), item, name, aco_type::name, and OBJ_KEY.

Referenced by ast_xmldoc_build_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 2077 of file xmldoc.c.

2078 {
2079  struct ast_xml_node *node;
2080 
2082  return NULL;
2083  }
2084 
2086 
2087  if (!node || !ast_xml_node_get_children(node)) {
2088  return NULL;
2089  }
2090 
2092 }
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:2037
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:434

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

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

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

2253 {
2254  return xmldoc_build_field(type, name, module, "description", 0);
2255 }
static char * xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
Definition: xmldoc.c:2192

References name, type, and xmldoc_build_field().

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

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

2656 {
2657  struct ao2_container *docs;
2658  struct ast_xml_node *node = NULL, *instance = NULL;
2659  struct documentation_tree *doctree;
2660  const char *name;
2661 
2664  if (!docs) {
2665  ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
2666  return NULL;
2667  }
2668 
2670  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2671  /* the core xml documents have priority over thirdparty document. */
2672  node = ast_xml_get_root(doctree->doc);
2673  if (!node) {
2674  break;
2675  }
2676 
2678  struct ast_xml_doc_item *item = NULL;
2679 
2680  /* Ignore empty nodes or nodes that aren't of the type requested */
2682  continue;
2683  }
2684  name = ast_xml_get_attribute(node, "name");
2685  if (!name) {
2686  continue;
2687  }
2688 
2689  switch (xmldoc_get_syntax_type(type)) {
2690  case MANAGER_EVENT_SYNTAX:
2691  {
2692  struct ast_xml_doc_item_list root;
2693 
2694  AST_LIST_HEAD_INIT(&root);
2695  for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
2696  struct ast_xml_doc_item *temp;
2697  if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
2698  continue;
2699  }
2700  temp = xmldoc_build_documentation_item(instance, name, type);
2701  if (!temp) {
2702  break;
2703  }
2704  AST_LIST_INSERT_TAIL(&root, temp, next);
2705  }
2706  item = AST_LIST_FIRST(&root);
2707  break;
2708  }
2709  case CONFIG_INFO_SYNTAX:
2710  {
2711  RAII_VAR(const char *, name, ast_xml_get_attribute(node, "name"), ast_xml_free_attr);
2712 
2713  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), "configInfo")) {
2714  break;
2715  }
2716 
2717  item = xmldoc_build_documentation_item(node, name, "configInfo");
2718  if (item) {
2719  struct ast_xml_doc_item_list root;
2720 
2721  AST_LIST_HEAD_INIT(&root);
2722  AST_LIST_INSERT_TAIL(&root, item, next);
2723  build_config_docs(node, &root);
2724  }
2725  break;
2726  }
2727  default:
2729  }
2731 
2732  if (item) {
2733  ao2_link(docs, item);
2734  ao2_t_ref(item, -1, "Dispose of creation ref");
2735  }
2736  }
2737  }
2739 
2740  return docs;
2741 }
#define ao2_t_ref(o, delta, tag)
Definition: astobj2.h:460
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
@ AO2_ALLOC_OPT_LOCK_MUTEX
Definition: astobj2.h:363
#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_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:731
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:626
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:421
Generic container type.
The struct to be used as the head of an ast_xml_doc_item list when being manipulated.
Definition: xmldoc.h:45
XML documentation tree.
Definition: xmldoc.c:54
struct ast_xml_doc * doc
Definition: xmldoc.c:56
Definition: search.h:40
Container of documentation trees.
Definition: xmldoc.c:75
#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:936
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:209
static int ast_xml_doc_item_cmp(void *obj, void *arg, int flags)
Definition: xmldoc.c:2342
static int ast_xml_doc_item_hash(const void *obj, const int flags)
Definition: xmldoc.c:2330
static struct ast_xml_doc_item * xmldoc_build_documentation_item(struct ast_xml_node *node, const char *name, const char *type)
Definition: xmldoc.c:2362
static void build_config_docs(struct ast_xml_node *cur, struct ast_xml_doc_item_list *root)
Definition: xmldoc.c:2578

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_link, ao2_t_ref, 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(), build_config_docs(), CONFIG_INFO_SYNTAX, documentation_tree::doc, item, MANAGER_EVENT_SYNTAX, name, ast_xml_doc_item::next, NULL, RAII_VAR, type, xmldoc_build_documentation_item(), and xmldoc_get_syntax_type().

Referenced by __init_manager(), and aco_init().

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

2531 {
2532  struct ast_xml_node *node;
2533 
2535  return NULL;
2536  }
2537 
2539 
2540  if (!node || !ast_xml_node_get_children(node)) {
2541  return NULL;
2542  }
2543 
2545 }
static struct ast_xml_doc_item * xmldoc_build_final_response(struct ast_xml_node *manager_action)
Definition: xmldoc.c:2496

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

Referenced by ast_manager_register2().

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

2466 {
2467  struct ast_xml_node *node;
2468 
2470  return NULL;
2471  }
2472 
2474 
2475  if (!node || !ast_xml_node_get_children(node)) {
2476  return NULL;
2477  }
2478 
2480 }
static struct ast_xml_doc_item * xmldoc_build_list_responses(struct ast_xml_node *manager_action)
Definition: xmldoc.c:2421

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

Referenced by ast_manager_register2().

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

1699 {
1700  char *output;
1701  struct ast_xml_node *node;
1702 
1704  return NULL;
1705  }
1706 
1707  /* get the application/function root node. */
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 char * _ast_xmldoc_build_seealso(struct ast_xml_node *node)
Definition: xmldoc.c:1636

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

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

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

2230 {
2231  return xmldoc_build_field(type, name, module, "synopsis", 1);
2232 }

References name, type, and xmldoc_build_field().

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

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

1254 {
1255  struct ast_xml_node *node;
1256 
1258  if (!node) {
1259  return NULL;
1260  }
1261 
1263 }
static char * _ast_xmldoc_build_syntax(struct ast_xml_node *root_node, const char *type, const char *name)
Definition: xmldoc.c:1216

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

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

◆ ast_xmldoc_load_documentation()

int ast_xmldoc_load_documentation ( void  )

Load XML documentation. Provided by xmldoc.c.

Return values
1on error.
0on success.

Definition at line 2881 of file xmldoc.c.

2882 {
2883  struct ast_xml_node *root_node;
2884  struct ast_xml_doc *tmpdoc;
2885  struct documentation_tree *doc_tree;
2886  char *xmlpattern;
2887  struct ast_config *cfg = NULL;
2888  struct ast_variable *var = NULL;
2889  struct ast_flags cnfflags = { 0 };
2890  int globret, i, dup, duplicate;
2891  glob_t globbuf;
2892 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
2893  int xmlpattern_maxlen;
2894 #endif
2895 
2896  /* setup default XML documentation language */
2898 
2899  if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
2900  for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
2901  if (!strcasecmp(var->name, "documentation_language")) {
2902  if (!ast_strlen_zero(var->value)) {
2903  snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
2904  }
2905  }
2906  }
2907  ast_config_destroy(cfg);
2908  }
2909 
2910  /* initialize the XML library. */
2911  ast_xml_init();
2912 
2914  /* register function to be run when asterisk finish. */
2916 
2917  globbuf.gl_offs = 0; /* slots to reserve in gl_pathv */
2918 
2919 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
2920  xmlpattern_maxlen = strlen(ast_config_AST_DATA_DIR) + strlen("/documentation/thirdparty") + strlen("/*-??_??.xml") + 1;
2921  xmlpattern = ast_malloc(xmlpattern_maxlen);
2922  globret = xml_pathmatch(xmlpattern, xmlpattern_maxlen, &globbuf);
2923 #else
2924  /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
2925  if (ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
2927  return 1;
2928  }
2929  globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
2930 #endif
2931 
2932  ast_debug(3, "gl_pathc %zu\n", (size_t)globbuf.gl_pathc);
2933  if (globret == GLOB_NOSPACE) {
2934  ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
2935  ast_free(xmlpattern);
2936  return 1;
2937  } else if (globret == GLOB_ABORTED) {
2938  ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Read error\n", xmlpattern);
2939  ast_free(xmlpattern);
2940  return 1;
2941  }
2942  ast_free(xmlpattern);
2943 
2945  /* loop over expanded files */
2946  for (i = 0; i < globbuf.gl_pathc; i++) {
2947  /* check for duplicates (if we already [try to] open the same file. */
2948  duplicate = 0;
2949  for (dup = 0; dup < i; dup++) {
2950  if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
2951  duplicate = 1;
2952  break;
2953  }
2954  }
2955  if (duplicate || strchr(globbuf.gl_pathv[i], '*')) {
2956  /* skip duplicates as well as pathnames not found
2957  * (due to use of GLOB_NOCHECK in xml_pathmatch) */
2958  continue;
2959  }
2960  tmpdoc = NULL;
2961  tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
2962  if (!tmpdoc) {
2963  ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
2964  continue;
2965  }
2966  /* Get doc root node and check if it starts with '<docs>' */
2967  root_node = ast_xml_get_root(tmpdoc);
2968  if (!root_node) {
2969  ast_log(LOG_ERROR, "Error getting documentation root node\n");
2970  ast_xml_close(tmpdoc);
2971  continue;
2972  }
2973  /* Check root node name for malformed xmls. */
2974  if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
2975  ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
2976  ast_xml_close(tmpdoc);
2977  continue;
2978  }
2979  doc_tree = ast_calloc(1, sizeof(*doc_tree));
2980  if (!doc_tree) {
2981  ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
2982  ast_xml_close(tmpdoc);
2983  continue;
2984  }
2985  doc_tree->doc = tmpdoc;
2986  doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
2988  }
2990 
2991  globfree(&globbuf);
2992 
2993  return 0;
2994 }
#define GLOB_ABORTED
Definition: ael_lex.c:839
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
#define ast_asprintf(ret, fmt,...)
A wrapper for asprintf()
Definition: astmm.h:267
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:191
#define ast_cli_register(e)
Registers a command or an array of commands.
Definition: cli.h:256
#define MY_GLOB_FLAGS
#define CONFIG_STATUS_FILEINVALID
void ast_config_destroy(struct ast_config *cfg)
Destroys a config.
Definition: extconf.c:1289
struct ast_config * ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags)
Load a config file.
Definition: main/config.c:3220
struct ast_variable * ast_variable_browse(const struct ast_config *config, const char *category_name)
Definition: extconf.c:1215
#define ast_debug(level,...)
Log a DEBUG message.
#define LOG_ERROR
#define LOG_WARNING
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
#define AST_RWLIST_INSERT_TAIL
Definition: linkedlists.h:741
const char * ast_config_AST_DATA_DIR
Definition: options.c:158
Structure used to handle boolean flags.
Definition: utils.h:199
Structure for variables, used for configurations and for channel variables.
char * filename
Definition: xmldoc.c:55
struct ast_xml_doc * ast_xml_open(char *filename)
Open an XML document.
Definition: xml.c:71
void ast_xml_close(struct ast_xml_doc *doc)
Close an already open document and free the used structure.
Definition: xml.c:190
int ast_xml_init(void)
Initialize the XML library implementation. This function is used to setup everything needed to start ...
Definition: xml.c:48
static const char default_documentation_language[]
Default documentation language.
Definition: xmldoc.c:44
static struct ast_cli_entry cli_dump_xmldocs
Definition: xmldoc.c:2861
static void xmldoc_unload_documentation(void)
Close and unload XML documentation.
Definition: xmldoc.c:2864

References ast_asprintf, ast_calloc, ast_cli_register, ast_config_AST_DATA_DIR, ast_config_destroy(), ast_config_load2(), ast_debug, ast_free, ast_log, ast_malloc, ast_register_cleanup(), AST_RWLIST_INSERT_TAIL, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strdup, ast_strlen_zero(), ast_variable_browse(), ast_xml_close(), ast_xml_get_root(), ast_xml_init(), ast_xml_node_get_name(), ast_xml_open(), cli_dump_xmldocs, CONFIG_STATUS_FILEINVALID, default_documentation_language, documentation_tree::doc, documentation_language, documentation_tree::filename, GLOB_ABORTED, LOG_ERROR, LOG_WARNING, MY_GLOB_FLAGS, NULL, var, and xmldoc_unload_documentation().

Referenced by asterisk_daemon().

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

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 }
static int tmp()
Definition: bt_open.c:389
char * end
Definition: eagi_proxy.c:73
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_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:406
const char * ast_term_reset(void)
Returns the terminal reset code.
Definition: term.c:357
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
#define COLOR_CYAN
Definition: term.h:62
static struct test_val c
#define ARRAY_LEN(a)
Definition: utils.h:661
static char * xmldoc_string_wrap(const char *text, int columns)
Definition: xmldoc.c:176
static const struct strcolorized_tags colorized_tags[]
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

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

◆ ast_xmldoc_query()

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

2548 {
2549  struct ast_xml_xpath_results *results = NULL;
2550  struct documentation_tree *doctree;
2551  RAII_VAR(struct ast_str *, xpath_str, ast_str_create(128), ast_free);
2552  va_list ap;
2553  int res;
2554 
2555  if (!xpath_str) {
2556  return NULL;
2557  }
2558 
2559  va_start(ap, fmt);
2560  res = ast_str_set_va(&xpath_str, 0, fmt, ap);
2561  va_end(ap);
2562  if (res == AST_DYNSTR_BUILD_FAILED) {
2563  return NULL;
2564  }
2565 
2567  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2568  if (!(results = ast_xml_query(doctree->doc, ast_str_buffer(xpath_str)))) {
2569  continue;
2570  }
2571  break;
2572  }
2574 
2575  return results;
2576 }
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:1008
@ AST_DYNSTR_BUILD_FAILED
Definition: strings.h:921
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:415

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

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

2607 {
2608  const char *name;
2609  char *syntax;
2610  char *seealso;
2611  char *arguments;
2612  char *synopsis;
2613  char *description;
2614 
2615  if (!item || !item->node) {
2616  return -1;
2617  }
2618 
2619  name = ast_xml_get_attribute(item->node, "name");
2620  if (!name) {
2621  return -1;
2622  }
2623 
2624  syntax = _ast_xmldoc_build_syntax(item->node, item->type, name);
2625  seealso = _ast_xmldoc_build_seealso(item->node);
2626  arguments = _ast_xmldoc_build_arguments(item->node);
2628  description = _ast_xmldoc_build_description(item->node);
2629 
2630  if (syntax) {
2631  ast_str_set(&item->syntax, 0, "%s", syntax);
2632  }
2633  if (seealso) {
2634  ast_str_set(&item->seealso, 0, "%s", seealso);
2635  }
2636  if (arguments) {
2637  ast_str_set(&item->arguments, 0, "%s", arguments);
2638  }
2639  if (synopsis) {
2640  ast_str_set(&item->synopsis, 0, "%s", synopsis);
2641  }
2642  if (description) {
2643  ast_str_set(&item->description, 0, "%s", description);
2644  }
2645 
2646  ast_free(syntax);
2647  ast_free(seealso);
2648  ast_free(arguments);
2649  ast_free(synopsis);
2650  ast_free(description);
2652  return 0;
2653 }
static char * synopsis
Definition: func_enum.c:154
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:1091
enum aco_type_t type
static char * _ast_xmldoc_build_description(struct ast_xml_node *node)
Definition: xmldoc.c:2247
static char * _ast_xmldoc_build_synopsis(struct ast_xml_node *node)
Definition: xmldoc.c:2224

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, item, name, ast_xml_doc_item::seealso, synopsis, ast_xml_doc_item::syntax, and aco_type::type.

Referenced by xmldoc_update_config_option(), and xmldoc_update_config_type().

◆ build_config_docs()

static void build_config_docs ( struct ast_xml_node *  cur,
struct ast_xml_doc_item_list root 
)
static

Definition at line 2578 of file xmldoc.c.

2579 {
2580  struct ast_xml_node *iter;
2581  struct ast_xml_doc_item *item;
2582 
2583  for (iter = ast_xml_node_get_children(cur); iter; iter = ast_xml_node_get_next(iter)) {
2584  const char *iter_name;
2585  if (strncasecmp(ast_xml_node_get_name(iter), "config", 6)) {
2586  continue;
2587  }
2588  iter_name = ast_xml_get_attribute(iter, "name");
2589  /* Now add all of the child config-related items to the list */
2590  if (!(item = xmldoc_build_documentation_item(iter, iter_name, ast_xml_node_get_name(iter)))) {
2591  ast_log(LOG_ERROR, "Could not build documentation for '%s:%s'\n", ast_xml_node_get_name(iter), iter_name);
2592  ast_xml_free_attr(iter_name);
2593  break;
2594  }
2595  ast_xml_free_attr(iter_name);
2596  if (!strcasecmp(ast_xml_node_get_name(iter), "configOption")) {
2597  const char *name = ast_xml_get_attribute(cur, "name");
2600  }
2601  AST_LIST_INSERT_TAIL(root, item, next);
2602  build_config_docs(iter, root);
2603  }
2604 }
const ast_string_field ref
Definition: xmldoc.h:74

References AST_LIST_INSERT_TAIL, ast_log, ast_string_field_set, ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), item, LOG_ERROR, name, ast_xml_doc_item::next, ast_xml_doc_item::ref, and xmldoc_build_documentation_item().

Referenced by ast_xmldoc_build_documentation().

◆ handle_dump_docs()

static char* handle_dump_docs ( struct ast_cli_entry e,
int  cmd,
struct ast_cli_args a 
)
static

Definition at line 2789 of file xmldoc.c.

2790 {
2791  struct documentation_tree *doctree;
2792  struct ast_xml_doc *dumpdoc;
2793  struct ast_xml_node *dumproot;
2794  FILE *f;
2795 
2796  switch (cmd) {
2797  case CLI_INIT:
2798  e->command = "xmldoc dump";
2799  e->usage =
2800  "Usage: xmldoc dump <filename>\n"
2801  " Dump XML documentation to a file\n";
2802  return NULL;
2803  case CLI_GENERATE:
2804  return NULL;
2805  }
2806 
2807  if (a->argc != 3) {
2808  return CLI_SHOWUSAGE;
2809  }
2810 
2811  dumpdoc = ast_xml_new();
2812  if (!dumpdoc) {
2813  ast_log(LOG_ERROR, "Could not create new XML document\n");
2814  return CLI_FAILURE;
2815  }
2816 
2817  dumproot = ast_xml_new_node("docs");
2818  if (!dumproot) {
2819  ast_xml_close(dumpdoc);
2820  ast_log(LOG_ERROR, "Could not create new XML root node\n");
2821  return CLI_FAILURE;
2822  }
2823 
2824  ast_xml_set_root(dumpdoc, dumproot);
2825 
2827  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2828  struct ast_xml_node *root_node = ast_xml_get_root(doctree->doc);
2829  struct ast_xml_node *kids = ast_xml_node_get_children(root_node);
2830  struct ast_xml_node *kids_copy;
2831 
2832  /* If there are no kids someone screwed up, but we check anyway. */
2833  if (!kids) {
2834  continue;
2835  }
2836 
2837  kids_copy = ast_xml_copy_node_list(kids);
2838  if (!kids_copy) {
2839  ast_xml_close(dumpdoc);
2840  ast_log(LOG_ERROR, "Could not create copy of XML node list\n");
2841  return CLI_FAILURE;
2842  }
2843 
2844  ast_xml_add_child_list(dumproot, kids_copy);
2845  }
2847 
2848  if (!(f = fopen(a->argv[2], "w"))) {
2849  ast_xml_close(dumpdoc);
2850  ast_log(LOG_ERROR, "Could not open file '%s': %s\n", a->argv[2], strerror(errno));
2851  return CLI_FAILURE;
2852  }
2853 
2854  ast_xml_doc_dump_file(f, dumpdoc);
2855  ast_xml_close(dumpdoc);
2856 
2857  fclose(f);
2858  return CLI_SUCCESS;
2859 }
#define CLI_SHOWUSAGE
Definition: cli.h:45
#define CLI_SUCCESS
Definition: cli.h:44
@ CLI_INIT
Definition: cli.h:152
@ CLI_GENERATE
Definition: cli.h:153
#define CLI_FAILURE
Definition: cli.h:46
int errno
char * command
Definition: cli.h:186
const char * usage
Definition: cli.h:177
static struct test_val a
struct ast_xml_doc * ast_xml_new(void)
Create a XML document.
Definition: xml.c:115
struct ast_xml_node * ast_xml_add_child_list(struct ast_xml_node *parent, struct ast_xml_node *child)
Add a list of child nodes, to a specified parent node.
Definition: xml.c:155
struct ast_xml_node * ast_xml_new_node(const char *name)
Create a XML node.
Definition: xml.c:123
struct ast_xml_node * ast_xml_copy_node_list(struct ast_xml_node *list)
Create a copy of a n ode list.
Definition: xml.c:163
int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc)
Dump the specified document to a file.
Definition: xml.c:359
void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node)
Specify the root node of a XML document.
Definition: xml.c:200

◆ xmldoc_attribute_match()

static int xmldoc_attribute_match ( struct ast_xml_node *  node,
const char *  attr,
const char *  value 
)
static

Definition at line 412 of file xmldoc.c.

413 {
414  const char *attr_value = ast_xml_get_attribute(node, attr);
415  int match = attr_value && !strcmp(attr_value, value);
416  ast_xml_free_attr(attr_value);
417  return match;
418 }
int value
Definition: syslog.c:37

References ast_xml_free_attr(), ast_xml_get_attribute(), match(), and value.

Referenced by xmldoc_get_node().

◆ xmldoc_build_documentation_item()

static struct ast_xml_doc_item* xmldoc_build_documentation_item ( struct ast_xml_node *  node,
const char *  name,
const char *  type 
)
static

Definition at line 2362 of file xmldoc.c.

2363 {
2364  struct ast_xml_doc_item *item;
2365  char *syntax;
2366  char *seealso;
2367  char *arguments;
2368  char *synopsis;
2369  char *description;
2370 
2371  if (!(item = ast_xml_doc_item_alloc(name, type))) {
2372  return NULL;
2373  }
2374  item->node = node;
2375 
2381 
2382  if (syntax) {
2383  ast_str_set(&item->syntax, 0, "%s", syntax);
2384  }
2385  if (seealso) {
2386  ast_str_set(&item->seealso, 0, "%s", seealso);
2387  }
2388  if (arguments) {
2389  ast_str_set(&item->arguments, 0, "%s", arguments);
2390  }
2391  if (synopsis) {
2392  ast_str_set(&item->synopsis, 0, "%s", synopsis);
2393  }
2394  if (description) {
2395  ast_str_set(&item->description, 0, "%s", description);
2396  }
2397 
2398  ast_free(syntax);
2399  ast_free(seealso);
2401  ast_free(synopsis);
2403 
2404  return item;
2405 }
struct ast_xml_node * node
Definition: xmldoc.h:78
static struct ast_xml_doc_item * ast_xml_doc_item_alloc(const char *name, const char *type)
Definition: xmldoc.c:2291

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_doc_item_alloc(), ast_xml_doc_item::description, item, name, ast_xml_doc_item::node, NULL, ast_xml_doc_item::seealso, synopsis, ast_xml_doc_item::syntax, and type.

Referenced by ast_xmldoc_build_documentation(), build_config_docs(), xmldoc_build_final_response(), and xmldoc_build_list_responses().

◆ xmldoc_build_field()

static char* xmldoc_build_field ( const char *  type,
const char *  name,
const char *  module,
const char *  var,
int  raw 
)
static

Definition at line 2192 of file xmldoc.c.

2193 {
2194  struct ast_xml_node *node;
2195 
2197  ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
2198  return NULL;
2199  }
2200 
2202 
2203  if (!node) {
2204  ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation\n", type, name);
2205  return NULL;
2206  }
2207 
2208  return _xmldoc_build_field(node, var, raw);
2209 }

References _xmldoc_build_field(), ast_log, ast_strlen_zero(), documentation_language, LOG_ERROR, LOG_WARNING, name, NULL, type, var, and xmldoc_get_node().

Referenced by ast_xmldoc_build_description(), and ast_xmldoc_build_synopsis().

◆ xmldoc_build_final_response()

static struct ast_xml_doc_item* xmldoc_build_final_response ( struct ast_xml_node *  manager_action)
static

Definition at line 2496 of file xmldoc.c.

2497 {
2498  struct ast_xml_node *responses;
2499  struct ast_xml_node *final_response_event;
2500  struct ast_xml_node *event_instance;
2501 
2503  "responses", NULL, NULL);
2504  if (!responses) {
2505  return NULL;
2506  }
2507 
2508  final_response_event = ast_xml_find_element(ast_xml_node_get_children(responses),
2509  "managerEvent", NULL, NULL);
2510  if (!final_response_event) {
2511  return NULL;
2512  }
2513 
2514  event_instance = ast_xml_find_element(ast_xml_node_get_children(final_response_event),
2515  "managerEventInstance", NULL, NULL);
2516  if (!event_instance) {
2517  return NULL;
2518  } else {
2519  const char *name;
2520  struct ast_xml_doc_item *res;
2521 
2522  name = ast_xml_get_attribute(final_response_event, "name");
2523  res = xmldoc_build_documentation_item(event_instance, name, "managerEvent");
2525  return res;
2526  }
2527 
2528 }

References ast_xml_find_element(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), name, NULL, and xmldoc_build_documentation_item().

Referenced by ast_xmldoc_build_final_response().

◆ xmldoc_build_list_responses()

static struct ast_xml_doc_item* xmldoc_build_list_responses ( struct ast_xml_node *  manager_action)
static

Definition at line 2421 of file xmldoc.c.

2422 {
2423  struct ast_xml_node *event;
2424  struct ast_xml_node *responses;
2425  struct ast_xml_node *list_elements;
2426  struct ast_xml_doc_item_list root;
2427 
2428  AST_LIST_HEAD_INIT(&root);
2429 
2431  if (!responses) {
2432  return NULL;
2433  }
2434 
2435  list_elements = ast_xml_find_element(ast_xml_node_get_children(responses), "list-elements", NULL, NULL);
2436  if (!list_elements) {
2437  return NULL;
2438  }
2439 
2440  /* Iterate over managerEvent nodes */
2441  for (event = ast_xml_node_get_children(list_elements); event; event = ast_xml_node_get_next(event)) {
2442  struct ast_xml_node *event_instance;
2443  RAII_VAR(const char *, name, ast_xml_get_attribute(event, "name"),
2445  struct ast_xml_doc_item *new_item;
2446 
2447  if (!name || strcmp(ast_xml_node_get_name(event), "managerEvent")) {
2448  continue;
2449  }
2450 
2452  "managerEventInstance", NULL, NULL);
2453  new_item = xmldoc_build_documentation_item(event_instance, name, "managerEvent");
2454  if (!new_item) {
2455  ao2_cleanup(AST_LIST_FIRST(&root));
2456  return NULL;
2457  }
2458 
2459  AST_LIST_INSERT_TAIL(&root, new_item, next);
2460  }
2461 
2462  return AST_LIST_FIRST(&root);
2463 }
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
Definition: astman.c:222

References ao2_cleanup, AST_LIST_FIRST, AST_LIST_HEAD_INIT, AST_LIST_INSERT_TAIL, ast_xml_find_element(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), name, ast_xml_doc_item::next, NULL, RAII_VAR, and xmldoc_build_documentation_item().

Referenced by ast_xmldoc_build_list_responses().

◆ xmldoc_get_formatted()

static struct ast_str* xmldoc_get_formatted ( struct ast_xml_node *  node,
int  raw_output,
int  raw_wrap 
)
static

Definition at line 2105 of file xmldoc.c.

2106 {
2107  struct ast_xml_node *tmp;
2108  const char *notcleanret, *tmpstr;
2109  struct ast_str *ret;
2110 
2111  if (raw_output) {
2112  /* xmldoc_string_cleanup will allocate the ret object */
2113  notcleanret = ast_xml_get_text(node);
2114  tmpstr = notcleanret;
2115  xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0, 0);
2116  ast_xml_free_text(tmpstr);
2117  } else {
2118  ret = ast_str_create(128);
2119  if (!ret) {
2120  return NULL;
2121  }
2123  /* if found, parse children elements. */
2124  if (xmldoc_parse_common_elements(tmp, "", "\n", &ret)) {
2125  continue;
2126  }
2127  if (xmldoc_parse_variablelist(tmp, "", &ret)) {
2128  continue;
2129  }
2130  if (xmldoc_parse_enumlist(tmp, " ", &ret)) {
2131  continue;
2132  }
2133  if (xmldoc_parse_specialtags(tmp, "", "", &ret)) {
2134  continue;
2135  }
2136  }
2137  /* remove last '\n' */
2138  /* XXX Don't modify ast_str internals manually */
2139  tmpstr = ast_str_buffer(ret);
2140  if (tmpstr[ast_str_strlen(ret) - 1] == '\n') {
2141  ast_str_truncate(ret, -1);
2142  }
2143  }
2144  return ret;
2145 }
char * ast_skip_blanks(const char *str)
Gets a pointer to the first non-whitespace character in a string.
Definition: strings.h:161
static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces, int maintain_newlines)
Definition: xmldoc.c:361
static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1411
static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1578
static int xmldoc_parse_common_elements(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1281
static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1764

References ast_skip_blanks(), ast_str_buffer(), ast_str_create, ast_str_strlen(), ast_str_truncate(), ast_xml_free_text(), ast_xml_get_text(), ast_xml_node_get_children(), ast_xml_node_get_next(), NULL, tmp(), xmldoc_parse_common_elements(), xmldoc_parse_enumlist(), xmldoc_parse_specialtags(), xmldoc_parse_variablelist(), and xmldoc_string_cleanup().

Referenced by _xmldoc_build_field().

◆ xmldoc_get_node()

static struct ast_xml_node* xmldoc_get_node ( const char *  type,
const char *  name,
const char *  module,
const char *  language 
)
static

Definition at line 434 of file xmldoc.c.

435 {
436  struct ast_xml_node *node = NULL;
437  struct ast_xml_node *first_match = NULL;
438  struct ast_xml_node *lang_match = NULL;
439  struct documentation_tree *doctree;
440 
442  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
443  /* the core xml documents have priority over thirdparty document. */
444  node = ast_xml_get_root(doctree->doc);
445  if (!node) {
446  break;
447  }
448 
450  while ((node = ast_xml_find_element(node, type, "name", name))) {
452  /* ignore empty nodes */
454  continue;
455  }
456 
457  if (!first_match) {
458  first_match = node;
459  }
460 
461  /* Check language */
462  if (xmldoc_attribute_match(node, "language", language)) {
463  if (!lang_match) {
464  lang_match = node;
465  }
466 
467  /* if module is empty we have a match */
468  if (ast_strlen_zero(module)) {
469  break;
470  }
471 
472  /* Check module */
473  if (xmldoc_attribute_match(node, "module", module)) {
474  break;
475  }
476  }
477 
479  }
480 
481  /* if we matched lang and module return this match */
482  if (node) {
483  break;
484  }
485 
486  /* we didn't match lang and module, just return the first
487  * result with a matching language if we have one */
488  if (lang_match) {
489  node = lang_match;
490  break;
491  }
492 
493  /* we didn't match with only the language, just return the
494  * first match */
495  if (first_match) {
496  node = first_match;
497  break;
498  }
499  }
501 
502  return node;
503 }
static char language[MAX_LANGUAGE]
Definition: chan_alsa.c:121
static int xmldoc_attribute_match(struct ast_xml_node *node, const char *attr, const char *value)
Definition: xmldoc.c:412

References AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_strlen_zero(), ast_xml_find_element(), ast_xml_get_root(), ast_xml_node_get_children(), ast_xml_node_get_next(), documentation_tree::doc, language, name, NULL, type, and xmldoc_attribute_match().

Referenced by ast_xmldoc_build_arguments(), ast_xmldoc_build_final_response(), ast_xmldoc_build_list_responses(), ast_xmldoc_build_seealso(), ast_xmldoc_build_syntax(), and xmldoc_build_field().

◆ xmldoc_get_syntax_cmd()

static char * xmldoc_get_syntax_cmd ( struct ast_xml_node *  fixnode,
const char *  name,
int  printname 
)
static

Definition at line 932 of file xmldoc.c.

933 {
934  struct ast_str *syntax;
935  struct ast_xml_node *tmpnode, *node = fixnode;
936  char *ret, *paramname;
937  const char *paramtype, *attrname, *literal;
938  int required, isenum, first = 1, isliteral;
939 
940  if (!fixnode) {
941  return NULL;
942  }
943 
944  syntax = ast_str_create(128);
945  if (!syntax) {
946  /* at least try to return something... */
947  return ast_strdup(name);
948  }
949 
950  /* append name to output string. */
951  if (printname) {
952  ast_str_append(&syntax, 0, "%s", name);
953  first = 0;
954  }
955 
957  if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
958  continue;
959  }
960 
961  if (xmldoc_has_inside(node, "parameter")) {
962  /* is this a recursive parameter. */
963  paramname = xmldoc_get_syntax_cmd(node, "", 0);
964  isenum = 1;
965  } else {
966  for (tmpnode = ast_xml_node_get_children(node); tmpnode; tmpnode = ast_xml_node_get_next(tmpnode)) {
967  if (!strcasecmp(ast_xml_node_get_name(tmpnode), "enumlist")) {
968  break;
969  }
970  }
971  if (tmpnode) {
972  /* parse enumlist (note that this is a special enumlist
973  that is used to describe a syntax like {<param1>|<param2>|...} */
974  paramname = xmldoc_parse_cmd_enumlist(tmpnode);
975  isenum = 1;
976  } else {
977  /* this is a simple parameter. */
978  attrname = ast_xml_get_attribute(node, "name");
979  if (!attrname) {
980  /* ignore this bogus parameter and continue. */
981  continue;
982  }
983  paramname = ast_strdup(attrname);
984  ast_xml_free_attr(attrname);
985  isenum = 0;
986  }
987  }
988 
989  /* Is this parameter required? */
990  required = 0;
991  paramtype = ast_xml_get_attribute(node, "required");
992  if (paramtype) {
993  required = ast_true(paramtype);
994  ast_xml_free_attr(paramtype);
995  }
996 
997  /* Is this a replaceable value or a fixed parameter value? */
998  isliteral = 0;
999  literal = ast_xml_get_attribute(node, "literal");
1000  if (literal) {
1001  isliteral = ast_true(literal);
1002  ast_xml_free_attr(literal);
1003  }
1004 
1005  /* if required="false" print with [...].
1006  * if literal="true" or is enum print without <..>.
1007  * if not first print a space at the beginning.
1008  */
1009  ast_str_append(&syntax, 0, "%s%s%s%s%s%s",
1010  (first ? "" : " "),
1011  (required ? "" : "["),
1012  (isenum || isliteral ? "" : "<"),
1013  paramname,
1014  (isenum || isliteral ? "" : ">"),
1015  (required ? "" : "]"));
1016  first = 0;
1017  ast_free(paramname);
1018  }
1019 
1020  /* return a common string. */
1021  ret = ast_strdup(ast_str_buffer(syntax));
1022  ast_free(syntax);
1023 
1024  return ret;
1025 }
int attribute_pure ast_true(const char *val)
Make sure something is true. Determine if a string containing a boolean value is "true"....
Definition: main/utils.c:2097
static char * xmldoc_parse_cmd_enumlist(struct ast_xml_node *fixnode)
Definition: xmldoc.c:882
static int xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
Definition: xmldoc.c:568

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strdup, ast_true(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), first, name, NULL, xmldoc_has_inside(), and xmldoc_parse_cmd_enumlist().

Referenced by _ast_xmldoc_build_syntax(), and xmldoc_parse_cmd_enumlist().

◆ xmldoc_get_syntax_config_object()

static char* xmldoc_get_syntax_config_object ( struct ast_xml_node *  fixnode,
const char *  name 
)
static

Definition at line 1090 of file xmldoc.c.

1091 {
1092  struct ast_xml_node *matchinfo, *tmp;
1093  int match;
1094  const char *attr_value;
1095  const char *text;
1096  RAII_VAR(struct ast_str *, syntax, ast_str_create(128), ast_free);
1097 
1098  if (!syntax || !fixnode) {
1099  return NULL;
1100  }
1101  if (!(matchinfo = ast_xml_find_element(ast_xml_node_get_children(fixnode), "matchInfo", NULL, NULL))) {
1102  return NULL;
1103  }
1104  if (!(tmp = ast_xml_find_element(ast_xml_node_get_children(matchinfo), "category", NULL, NULL))) {
1105  return NULL;
1106  }
1107  attr_value = ast_xml_get_attribute(tmp, "match");
1108  if (attr_value) {
1109  match = ast_true(attr_value);
1111  ast_str_set(&syntax, 0, "category %s /%s/", match ? "=~" : "!~", text);
1112  ast_xml_free_attr(attr_value);
1114  }
1115 
1116  if ((tmp = ast_xml_find_element(ast_xml_node_get_children(matchinfo), "field", NULL, NULL))) {
1118  attr_value = ast_xml_get_attribute(tmp, "name");
1119  ast_str_append(&syntax, 0, " matchfield: %s = %s", S_OR(attr_value, "Unknown"), text);
1120  ast_xml_free_attr(attr_value);
1122  }
1123  return ast_strdup(ast_str_buffer(syntax));
1124 }
char * text
Definition: app_queue.c:1641
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one.
Definition: strings.h:80

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_set(), ast_strdup, ast_true(), ast_xml_find_element(), ast_xml_free_attr(), ast_xml_free_text(), ast_xml_get_attribute(), ast_xml_get_text(), ast_xml_node_get_children(), match(), NULL, RAII_VAR, S_OR, text, and tmp().

Referenced by _ast_xmldoc_build_syntax().

◆ xmldoc_get_syntax_config_option()

static char* xmldoc_get_syntax_config_option ( struct ast_xml_node *  fixnode,
const char *  name 
)
static

Definition at line 1126 of file xmldoc.c.

1127 {
1128  const char *type;
1129  const char *default_value;
1130  const char *regex;
1131  RAII_VAR(struct ast_str *, syntax, ast_str_create(128), ast_free);
1132 
1133  if (!syntax || !fixnode) {
1134  return NULL;
1135  }
1136  type = ast_xml_get_attribute(fixnode, "type");
1137  default_value = ast_xml_get_attribute(fixnode, "default");
1138 
1139  regex = ast_xml_get_attribute(fixnode, "regex");
1140  ast_str_set(&syntax, 0, "%s = [%s] (Default: %s) (Regex: %s)\n",
1141  name,
1142  type ?: "",
1143  default_value ?: "n/a",
1144  regex ?: "False");
1145 
1147  ast_xml_free_attr(default_value);
1149 
1150  return ast_strdup(ast_str_buffer(syntax));
1151 }
static int regex(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)

References ast_free, ast_str_buffer(), ast_str_create, ast_str_set(), ast_strdup, ast_xml_free_attr(), ast_xml_get_attribute(), name, NULL, RAII_VAR, regex(), and type.

Referenced by _ast_xmldoc_build_syntax().

◆ xmldoc_get_syntax_fun()

static char* xmldoc_get_syntax_fun ( struct ast_xml_node *  rootnode,
const char *  rootname,
const char *  childname,
int  printparenthesis,
int  printrootname 
)
static

Definition at line 638 of file xmldoc.c.

639 {
640 #define GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
641 #define ISLAST(__rev, __a) (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
642 #define MP(__a) ((multiple ? __a : ""))
643  struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
644  const char *paramtype, *multipletype, *paramnameattr, *attrargsep, *parenthesis, *argname;
645  int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
646  int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis, multiple;
647  char *syntax = NULL, *argsep, *paramname;
648 
649  if (ast_strlen_zero(rootname) || ast_strlen_zero(childname)) {
650  ast_log(LOG_WARNING, "Tried to look in XML tree with faulty rootname or childname while creating a syntax.\n");
651  return NULL;
652  }
653 
654  if (!rootnode || !ast_xml_node_get_children(rootnode)) {
655  /* If the rootnode field is not found, at least print name. */
656  if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
657  syntax = NULL;
658  }
659  return syntax;
660  }
661 
662  /* Get the argument separator from the root node attribute name 'argsep', if not found
663  defaults to ','. */
664  attrargsep = ast_xml_get_attribute(rootnode, "argsep");
665  if (attrargsep) {
666  argsep = ast_strdupa(attrargsep);
667  ast_xml_free_attr(attrargsep);
668  } else {
669  argsep = ast_strdupa(",");
670  }
671 
672  /* Get order of evaluation. */
674  if (strcasecmp(ast_xml_node_get_name(node), childname)) {
675  continue;
676  }
677  required = 0;
678  hasparams = 1;
679  if ((paramtype = ast_xml_get_attribute(node, "required"))) {
680  if (ast_true(paramtype)) {
681  required = 1;
682  }
683  ast_xml_free_attr(paramtype);
684  }
685 
686  lastparam = node;
687  reqlanode = required;
688 
689  if (!firstparam) {
690  /* first parameter node */
691  firstparam = node;
692  reqfinode = required;
693  }
694  }
695 
696  if (!hasparams) {
697  /* This application, function, option, etc, doesn't have any params. */
698  if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
699  syntax = NULL;
700  }
701  return syntax;
702  }
703 
704  if (reqfinode && reqlanode) {
705  /* check midnode */
707  if (strcasecmp(ast_xml_node_get_name(node), childname)) {
708  continue;
709  }
710  if (node != firstparam && node != lastparam) {
711  if ((paramtype = ast_xml_get_attribute(node, "required"))) {
712  if (!ast_true(paramtype)) {
713  optmidnode = 1;
714  ast_xml_free_attr(paramtype);
715  break;
716  }
717  ast_xml_free_attr(paramtype);
718  }
719  }
720  }
721  }
722 
723  if ((!reqfinode && reqlanode) || (reqfinode && reqlanode && optmidnode)) {
724  reverse = 1;
725  node = lastparam;
726  } else {
727  reverse = 0;
728  node = firstparam;
729  }
730 
731  /* init syntax string. */
732  if (reverse) {
733  xmldoc_reverse_helper(reverse, &len, &syntax,
734  (printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
735  } else {
736  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
737  (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
738  }
739 
740  for (; node; node = GOTONEXT(reverse, node)) {
741  if (strcasecmp(ast_xml_node_get_name(node), childname)) {
742  continue;
743  }
744 
745  /* Get the argument name, if it is not the leaf, go inside that parameter. */
746  if (xmldoc_has_inside(node, "argument")) {
747  parenthesis = ast_xml_get_attribute(node, "hasparams");
748  prnparenthesis = 0;
749  if (parenthesis) {
750  prnparenthesis = ast_true(parenthesis);
751  if (!strcasecmp(parenthesis, "optional")) {
752  prnparenthesis = 2;
753  }
754  ast_xml_free_attr(parenthesis);
755  }
756  argname = ast_xml_get_attribute(node, "name");
757  if (argname) {
758  paramname = xmldoc_get_syntax_fun(node, argname, "argument", prnparenthesis, prnparenthesis);
759  ast_xml_free_attr(argname);
760  } else {
761  /* Malformed XML, print **UNKOWN** */
762  paramname = ast_strdup("**unknown**");
763  }
764  } else {
765  paramnameattr = ast_xml_get_attribute(node, "name");
766  if (!paramnameattr) {
767  ast_log(LOG_WARNING, "Malformed XML %s: no %s name\n", rootname, childname);
768  if (syntax) {
769  /* Free already allocated syntax */
770  ast_free(syntax);
771  }
772  /* to give up is ok? */
773  if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
774  syntax = NULL;
775  }
776  return syntax;
777  }
778  paramname = ast_strdup(paramnameattr);
779  ast_xml_free_attr(paramnameattr);
780  }
781 
782  if (!paramname) {
783  return NULL;
784  }
785 
786  /* Defaults to 'false'. */
787  multiple = 0;
788  if ((multipletype = ast_xml_get_attribute(node, "multiple"))) {
789  if (ast_true(multipletype)) {
790  multiple = 1;
791  }
792  ast_xml_free_attr(multipletype);
793  }
794 
795  required = 0; /* Defaults to 'false'. */
796  if ((paramtype = ast_xml_get_attribute(node, "required"))) {
797  if (ast_true(paramtype)) {
798  required = 1;
799  }
800  ast_xml_free_attr(paramtype);
801  }
802 
803  /* build syntax core. */
804 
805  if (required) {
806  /* First parameter */
807  if (!paramcount) {
808  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
809  } else {
810  /* Time to close open brackets. */
811  while (openbrackets > 0) {
812  xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
813  openbrackets--;
814  }
815  if (reverse) {
816  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", paramname, argsep);
817  } else {
818  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", argsep, paramname);
819  }
820  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s", MP("["), MP(argsep), MP("...]"));
821  }
822  } else {
823  /* First parameter */
824  if (!paramcount) {
825  xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]", paramname, MP("["), MP(argsep), MP("...]"));
826  } else {
827  if (ISLAST(reverse, node)) {
828  /* This is the last parameter. */
829  if (reverse) {
830  xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]%s", paramname,
831  MP("["), MP(argsep), MP("...]"), argsep);
832  } else {
833  xmldoc_reverse_helper(reverse, &len, &syntax, "%s[%s%s%s%s]", argsep, paramname,
834  MP("["), MP(argsep), MP("...]"));
835  }
836  } else {
837  if (reverse) {
838  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s%s]", paramname, argsep,
839  MP("["), MP(argsep), MP("...]"));
840  } else {
841  xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s%s", argsep, paramname,
842  MP("["), MP(argsep), MP("...]"));
843  }
844  openbrackets++;
845  }
846  }
847  }
848  ast_free(paramname);
849 
850  paramcount++;
851  }
852 
853  /* Time to close open brackets. */
854  while (openbrackets > 0) {
855  xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
856  openbrackets--;
857  }
858 
859  /* close syntax string. */
860  if (reverse) {
861  xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
862  (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
863  } else {
864  xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
865  }
866 
867  return syntax;
868 #undef ISLAST
869 #undef GOTONEXT
870 #undef MP
871 }
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
#define MP(__a)
static void xmldoc_reverse_helper(int reverse, int *len, char **syntax, const char *fmt,...)
Definition: xmldoc.c:516
#define GOTONEXT(__rev, __a)
#define ISLAST(__rev, __a)

References ast_asprintf, ast_free, ast_log, ast_strdup, ast_strdupa, ast_strlen_zero(), ast_true(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), GOTONEXT, ISLAST, len(), LOG_WARNING, MP, NULL, xmldoc_has_inside(), and xmldoc_reverse_helper().

Referenced by _ast_xmldoc_build_syntax(), and xmldoc_parse_optionlist().

◆ xmldoc_get_syntax_manager()

static char* xmldoc_get_syntax_manager ( struct ast_xml_node *  fixnode,
const char *  name,
const char *  manager_type 
)
static

Definition at line 1038 of file xmldoc.c.

1039 {
1040  struct ast_str *syntax;
1041  struct ast_xml_node *node = fixnode;
1042  const char *paramtype, *attrname;
1043  int required;
1044  char *ret;
1045 
1046  if (!fixnode) {
1047  return NULL;
1048  }
1049 
1050  syntax = ast_str_create(128);
1051  if (!syntax) {
1052  return ast_strdup(name);
1053  }
1054 
1055  ast_str_append(&syntax, 0, "%s: %s", manager_type, name);
1056 
1058  if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
1059  continue;
1060  }
1061 
1062  /* Is this parameter required? */
1063  required = !strcasecmp(manager_type, "event") ? 1 : 0;
1064  paramtype = ast_xml_get_attribute(node, "required");
1065  if (paramtype) {
1066  required = ast_true(paramtype);
1067  ast_xml_free_attr(paramtype);
1068  }
1069 
1070  attrname = ast_xml_get_attribute(node, "name");
1071  if (!attrname) {
1072  /* ignore this bogus parameter and continue. */
1073  continue;
1074  }
1075 
1076  ast_str_append(&syntax, 0, "\n%s%s:%s <value>",
1077  (required ? "" : "["),
1078  attrname,
1079  (required ? "" : "]"));
1080  ast_xml_free_attr(attrname);
1081  }
1082 
1083  /* return a common string. */
1084  ret = ast_strdup(ast_str_buffer(syntax));
1085  ast_free(syntax);
1086 
1087  return ret;
1088 }

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strdup, ast_true(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), name, and NULL.

Referenced by _ast_xmldoc_build_syntax().

◆ xmldoc_get_syntax_type()

static enum syntaxtype xmldoc_get_syntax_type ( const char *  type)
static

Definition at line 1126 of file xmldoc.c.

1190 {
1191  int i;
1192  for (i=0; i < ARRAY_LEN(stxtype); i++) {
1193  if (!strcasecmp(stxtype[i].type, type)) {
1194  return stxtype[i].stxtype;
1195  }
1196  }
1197 
1198  return FUNCTION_SYNTAX;
1199 }
enum syntaxtype stxtype
Definition: xmldoc.c:1168
static struct strsyntaxtype stxtype[]

Referenced by _ast_xmldoc_build_syntax(), and ast_xmldoc_build_documentation().

◆ xmldoc_has_inside()

static int xmldoc_has_inside ( struct ast_xml_node *  fixnode,
const char *  what 
)
static

Definition at line 568 of file xmldoc.c.

569 {
570  struct ast_xml_node *node = fixnode;
571 
573  if (!strcasecmp(ast_xml_node_get_name(node), what)) {
574  return 1;
575  }
576  }
577  return 0;
578 }

References ast_xml_node_get_children(), ast_xml_node_get_name(), and ast_xml_node_get_next().

Referenced by xmldoc_get_syntax_cmd(), xmldoc_get_syntax_fun(), xmldoc_parse_argument(), and xmldoc_parse_parameter().

◆ xmldoc_has_nodes()

static int xmldoc_has_nodes ( struct ast_xml_node *  fixnode)
static

Definition at line 589 of file xmldoc.c.

590 {
591  struct ast_xml_node *node = fixnode;
592 
594  if (strcasecmp(ast_xml_node_get_name(node), "text")) {
595  return 1;
596  }
597  }
598  return 0;
599 }

References ast_xml_node_get_children(), ast_xml_node_get_name(), and ast_xml_node_get_next().

Referenced by xmldoc_parse_parameter().

◆ xmldoc_has_specialtags()

static int xmldoc_has_specialtags ( struct ast_xml_node *  fixnode)
static

Definition at line 610 of file xmldoc.c.

611 {
612  struct ast_xml_node *node = fixnode;
613  int i;
614 
616  for (i = 0; i < ARRAY_LEN(special_tags); i++) {
617  if (!strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
618  return 1;
619  }
620  }
621  }
622  return 0;
623 }
static const struct strspecial_tags special_tags[]

References ARRAY_LEN, ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), and special_tags.

Referenced by xmldoc_parse_argument().

◆ xmldoc_parse_argument()

static int xmldoc_parse_argument ( struct ast_xml_node *  fixnode,
int  insideparameter,
const char *  paramtabs,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1470 of file xmldoc.c.

1471 {
1472  struct ast_xml_node *node = fixnode;
1473  const char *argname;
1474  int count = 0, ret = 0;
1475 
1476  if (!node || !ast_xml_node_get_children(node)) {
1477  return ret;
1478  }
1479 
1480  /* Print the argument names */
1481  argname = ast_xml_get_attribute(node, "name");
1482  if (!argname) {
1483  return 0;
1484  }
1486  ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
1487  ast_xml_free_attr(argname);
1488  } else {
1489  ast_xml_free_attr(argname);
1490  return 0;
1491  }
1492 
1494  if (xmldoc_parse_common_elements(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
1495  count++;
1496  ret = 1;
1497  }
1498  }
1499 
1500  return ret;
1501 }
static int xmldoc_has_specialtags(struct ast_xml_node *fixnode)
Definition: xmldoc.c:610

References ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_next(), xmldoc_has_inside(), xmldoc_has_specialtags(), and xmldoc_parse_common_elements().

Referenced by xmldoc_parse_option(), and xmldoc_parse_parameter().

◆ xmldoc_parse_cmd_enumlist()

static char* xmldoc_parse_cmd_enumlist ( struct ast_xml_node *  fixnode)
static

Definition at line 882 of file xmldoc.c.

883 {
884  struct ast_xml_node *node = fixnode;
885  struct ast_str *paramname;
886  char *enumname, *ret;
887  int first = 1;
888 
889  paramname = ast_str_create(128);
890  if (!paramname) {
891  return ast_strdup("{<unkown>}");
892  }
893 
894  ast_str_append(&paramname, 0, "{");
895 
897  if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
898  continue;
899  }
900 
901  enumname = xmldoc_get_syntax_cmd(node, "", 0);
902  if (!enumname) {
903  continue;
904  }
905  if (!first) {
906  ast_str_append(&paramname, 0, "|");
907  }
908  ast_str_append(&paramname, 0, "%s", enumname);
909  first = 0;
910  ast_free(enumname);
911  }
912 
913  ast_str_append(&paramname, 0, "}");
914 
915  ret = ast_strdup(ast_str_buffer(paramname));
916  ast_free(paramname);
917 
918  return ret;
919 }

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strdup, ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), first, and xmldoc_get_syntax_cmd().

Referenced by xmldoc_get_syntax_cmd().

◆ xmldoc_parse_common_elements()

static int xmldoc_parse_common_elements ( struct ast_xml_node *  node,
const char *  tabs,
const char *  posttabs,
struct ast_str **  buffer 
)
static

Definition at line 1281 of file xmldoc.c.

1282 {
1283  return (xmldoc_parse_para(node, tabs, posttabs, buffer)
1284  || xmldoc_parse_specialtags(node, tabs, posttabs, buffer)
1285  || xmldoc_parse_info(node, tabs, posttabs, buffer));
1286 }
static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1983
static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1303

References xmldoc_parse_info(), xmldoc_parse_para(), and xmldoc_parse_specialtags().

Referenced by xmldoc_get_formatted(), xmldoc_parse_argument(), xmldoc_parse_enum(), xmldoc_parse_info(), xmldoc_parse_option(), xmldoc_parse_variable(), and xmldoc_parse_variablelist().

◆ xmldoc_parse_enum()

static int xmldoc_parse_enum ( struct ast_xml_node *  fixnode,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1729 of file xmldoc.c.

1730 {
1731  struct ast_xml_node *node = fixnode;
1732  int ret = 0;
1733  char *optiontabs;
1734 
1735  if (ast_asprintf(&optiontabs, "%s ", tabs) < 0) {
1736  return ret;
1737  }
1738 
1740  if (xmldoc_parse_common_elements(node, (ret ? tabs : " - "), "\n", buffer)) {
1741  ret = 1;
1742  }
1743 
1744  xmldoc_parse_enumlist(node, optiontabs, buffer);
1745  xmldoc_parse_parameter(node, optiontabs, buffer);
1746  }
1747 
1748  ast_free(optiontabs);
1749 
1750  return ret;
1751 }

References ast_asprintf, ast_free, ast_xml_node_get_children(), ast_xml_node_get_next(), xmldoc_parse_common_elements(), xmldoc_parse_enumlist(), and xmldoc_parse_parameter().

Referenced by xmldoc_parse_enumlist().

◆ xmldoc_parse_enumlist()

static int xmldoc_parse_enumlist ( struct ast_xml_node *  fixnode,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1764 of file xmldoc.c.

1765 {
1766  struct ast_xml_node *node = fixnode;
1767  const char *enumname;
1768  int ret = 0;
1769 
1771  if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
1772  continue;
1773  }
1774 
1775  enumname = ast_xml_get_attribute(node, "name");
1776  if (enumname) {
1777  ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
1778  ast_xml_free_attr(enumname);
1779 
1780  /* parse only enum elements inside a enumlist node. */
1781  if ((xmldoc_parse_enum(node, tabs, buffer))) {
1782  ret = 1;
1783  } else {
1784  ast_str_append(buffer, 0, "\n");
1785  }
1786  }
1787  }
1788  return ret;
1789 }
static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1729

References ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), and xmldoc_parse_enum().

Referenced by xmldoc_get_formatted(), xmldoc_parse_enum(), xmldoc_parse_info(), xmldoc_parse_option(), and xmldoc_parse_parameter().

◆ xmldoc_parse_example()

static int xmldoc_parse_example ( struct ast_xml_node *  fixnode,
struct ast_str **  buffer 
)
static

Definition at line 1358 of file xmldoc.c.

1359 {
1360  struct ast_xml_node *node = fixnode;
1361  const char *tmptext;
1362  const char *title;
1363  struct ast_str *stripped_text;
1364  int ret = 0;
1365 
1366  if (!node || !ast_xml_node_get_children(node)) {
1367  return ret;
1368  }
1369 
1370  if (strcasecmp(ast_xml_node_get_name(node), "example")) {
1371  return ret;
1372  }
1373 
1374  ret = 1;
1375 
1376  title = ast_xml_get_attribute(node, "title");
1377  if (title) {
1378  ast_str_append(buffer, 0, "%s", title);
1379  ast_xml_free_attr(title);
1380  }
1381  ast_str_append(buffer, 0, "\n");
1382 
1384  tmptext = ast_xml_get_text(node);
1385  if (tmptext) {
1386  xmldoc_string_cleanup(tmptext, &stripped_text, 0, 1);
1387  if (stripped_text) {
1388  ast_str_append(buffer, 0, "<exampletext>%s</exampletext>\n", ast_str_buffer(stripped_text));
1389  ast_xml_free_text(tmptext);
1390  ast_free(stripped_text);
1391  }
1392  }
1393  }
1394 
1395  return ret;
1396 }

References ast_free, ast_str_append(), ast_str_buffer(), 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(), and xmldoc_string_cleanup().

Referenced by xmldoc_parse_specialtags().

◆ xmldoc_parse_info()

static int xmldoc_parse_info ( struct ast_xml_node *  node,
const char *  tabs,
const char *  posttabs,
struct ast_str **  buffer 
)
static

Definition at line 1983 of file xmldoc.c.

1984 {
1985  const char *tech;
1986  char *internaltabs;
1987  int internal_ret;
1988  int ret = 0;
1989 
1990  if (strcasecmp(ast_xml_node_get_name(node), "info")) {
1991  return ret;
1992  }
1993 
1994  ast_asprintf(&internaltabs, "%s ", tabs);
1995  if (!internaltabs) {
1996  return ret;
1997  }
1998 
1999  tech = ast_xml_get_attribute(node, "tech");
2000  if (tech) {
2001  ast_str_append(buffer, 0, "%s<note>Technology: %s</note>\n", internaltabs, tech);
2002  ast_xml_free_attr(tech);
2003  }
2004 
2005  ret = 1;
2006 
2008  if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
2009  xmldoc_parse_enumlist(node, internaltabs, buffer);
2010  } else if (!strcasecmp(ast_xml_node_get_name(node), "parameter")) {
2011  xmldoc_parse_parameter(node, internaltabs, buffer);
2012  } else if ((internal_ret = xmldoc_parse_common_elements(node, internaltabs, posttabs, buffer))) {
2013  if (internal_ret > ret) {
2014  ret = internal_ret;
2015  }
2016  }
2017  }
2018  ast_free(internaltabs);
2019 
2020  return ret;
2021 }

References ast_asprintf, ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_parse_common_elements(), xmldoc_parse_enumlist(), and xmldoc_parse_parameter().

Referenced by xmldoc_parse_common_elements(), xmldoc_parse_parameter(), and xmldoc_parse_specialtags().

◆ xmldoc_parse_option()

static int xmldoc_parse_option ( struct ast_xml_node *  fixnode,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1803 of file xmldoc.c.

1804 {
1805  struct ast_xml_node *node;
1806  int ret = 0;
1807  char *optiontabs;
1808 
1809  if (ast_asprintf(&optiontabs, "%s ", tabs) < 0) {
1810  return ret;
1811  }
1813  if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1814  /* if this is the first data appended to buffer, print a \n*/
1815  if (!ret && ast_xml_node_get_children(node)) {
1816  /* print \n */
1817  ast_str_append(buffer, 0, "\n");
1818  }
1819  if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
1820  ret = 1;
1821  }
1822  continue;
1823  }
1824 
1825  if (xmldoc_parse_common_elements(node, (ret ? tabs : ""), "\n", buffer)) {
1826  ret = 1;
1827  }
1828 
1829  xmldoc_parse_variablelist(node, optiontabs, buffer);
1830 
1831  xmldoc_parse_enumlist(node, optiontabs, buffer);
1832  }
1833  ast_free(optiontabs);
1834 
1835  return ret;
1836 }
static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1470

References ast_asprintf, ast_free, ast_str_append(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), NULL, xmldoc_parse_argument(), xmldoc_parse_common_elements(), xmldoc_parse_enumlist(), and xmldoc_parse_variablelist().

Referenced by xmldoc_parse_optionlist().

◆ xmldoc_parse_optionlist()

static void xmldoc_parse_optionlist ( struct ast_xml_node *  fixnode,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1847 of file xmldoc.c.

1848 {
1849  struct ast_xml_node *node;
1850  const char *optname, *hasparams;
1851  char *optionsyntax;
1852  int optparams;
1853 
1855  /* Start appending every option tag. */
1856  if (strcasecmp(ast_xml_node_get_name(node), "option")) {
1857  continue;
1858  }
1859 
1860  /* Get the option name. */
1861  optname = ast_xml_get_attribute(node, "name");
1862  if (!optname) {
1863  continue;
1864  }
1865 
1866  optparams = 1;
1867  hasparams = ast_xml_get_attribute(node, "hasparams");
1868  if (hasparams && !strcasecmp(hasparams, "optional")) {
1869  optparams = 2;
1870  }
1871 
1872  optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
1873  if (!optionsyntax) {
1874  ast_xml_free_attr(optname);
1875  ast_xml_free_attr(hasparams);
1876  continue;
1877  }
1878 
1879  ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
1880 
1881  if (!xmldoc_parse_option(node, tabs, buffer)) {
1882  ast_str_append(buffer, 0, "\n");
1883  }
1884  ast_str_append(buffer, 0, "\n");
1885  ast_xml_free_attr(optname);
1886  ast_xml_free_attr(hasparams);
1887  ast_free(optionsyntax);
1888  }
1889 }
static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1803

References ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_get_syntax_fun(), and xmldoc_parse_option().

Referenced by xmldoc_parse_parameter().

◆ xmldoc_parse_para()

static int xmldoc_parse_para ( struct ast_xml_node *  node,
const char *  tabs,
const char *  posttabs,
struct ast_str **  buffer 
)
static

Definition at line 1303 of file xmldoc.c.

1304 {
1305  const char *tmptext;
1306  struct ast_xml_node *tmp;
1307  int ret = 0;
1308  struct ast_str *tmpstr;
1309 
1310  if (!node || !ast_xml_node_get_children(node)) {
1311  return ret;
1312  }
1313 
1314  if (strcasecmp(ast_xml_node_get_name(node), "para")) {
1315  return ret;
1316  }
1317 
1318  ast_str_append(buffer, 0, "%s", tabs);
1319 
1320  ret = 1;
1321 
1323  /* Get the text inside the <para> element and append it to buffer. */
1324  tmptext = ast_xml_get_text(tmp);
1325  if (tmptext) {
1326  /* Strip \n etc. */
1327  xmldoc_string_cleanup(tmptext, &tmpstr, 0, 0);
1328  ast_xml_free_text(tmptext);
1329  if (tmpstr) {
1330  if (strcasecmp(ast_xml_node_get_name(tmp), "text")) {
1331  ast_str_append(buffer, 0, "<%s>%s</%s>", ast_xml_node_get_name(tmp),
1333  } else {
1334  ast_str_append(buffer, 0, "%s", ast_str_buffer(tmpstr));
1335  }
1336  ast_free(tmpstr);
1337  ret = 2;
1338  }
1339  }
1340  }
1341 
1342  ast_str_append(buffer, 0, "%s", posttabs);
1343 
1344  return ret;
1345 }

References ast_free, ast_str_append(), ast_str_buffer(), ast_xml_free_text(), ast_xml_get_text(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), tmp(), and xmldoc_string_cleanup().

Referenced by xmldoc_parse_common_elements(), xmldoc_parse_parameter(), and xmldoc_parse_specialtags().

◆ xmldoc_parse_parameter()

static void xmldoc_parse_parameter ( struct ast_xml_node *  fixnode,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1900 of file xmldoc.c.

1901 {
1902  const char *paramname;
1903  struct ast_xml_node *node = fixnode;
1904  int hasarguments, printed = 0;
1905  char *internaltabs;
1906 
1907  if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
1908  return;
1909  }
1910 
1911  hasarguments = xmldoc_has_inside(node, "argument");
1912  if (!(paramname = ast_xml_get_attribute(node, "name"))) {
1913  /* parameter MUST have an attribute name. */
1914  return;
1915  }
1916 
1917  if (ast_asprintf(&internaltabs, "%s ", tabs) < 0) {
1918  ast_xml_free_attr(paramname);
1919  return;
1920  }
1921 
1922  if (!hasarguments && xmldoc_has_nodes(node)) {
1923  ast_str_append(buffer, 0, "%s\n", paramname);
1924  ast_xml_free_attr(paramname);
1925  printed = 1;
1926  }
1927 
1929  if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
1930  xmldoc_parse_optionlist(node, internaltabs, buffer);
1931  } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
1932  xmldoc_parse_enumlist(node, internaltabs, buffer);
1933  } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1934  xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? " " : ""), buffer);
1935  } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
1936  if (!printed) {
1937  ast_str_append(buffer, 0, "%s\n", paramname);
1938  ast_xml_free_attr(paramname);
1939  printed = 1;
1940  }
1941  if (xmldoc_parse_para(node, internaltabs, "\n", buffer)) {
1942  /* If anything ever goes in below this condition before the continue below,
1943  * we should probably continue immediately. */
1944  continue;
1945  }
1946  continue;
1947  } else if (!strcasecmp(ast_xml_node_get_name(node), "info")) {
1948  if (!printed) {
1949  ast_str_append(buffer, 0, "%s\n", paramname);
1950  ast_xml_free_attr(paramname);
1951  printed = 1;
1952  }
1953  if (xmldoc_parse_info(node, internaltabs, "\n", buffer)) {
1954  /* If anything ever goes in below this condition before the continue below,
1955  * we should probably continue immediately. */
1956  continue;
1957  }
1958  continue;
1959  } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
1960  continue;
1961  }
1962  }
1963  if (!printed) {
1964  ast_xml_free_attr(paramname);
1965  }
1966  ast_free(internaltabs);
1967 }
static int xmldoc_has_nodes(struct ast_xml_node *fixnode)
Definition: xmldoc.c:589
static void xmldoc_parse_optionlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1847

References ast_asprintf, ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_has_inside(), xmldoc_has_nodes(), xmldoc_parse_argument(), xmldoc_parse_enumlist(), xmldoc_parse_info(), xmldoc_parse_optionlist(), xmldoc_parse_para(), and xmldoc_parse_specialtags().

Referenced by _ast_xmldoc_build_arguments(), xmldoc_parse_enum(), and xmldoc_parse_info().

◆ xmldoc_parse_specialtags()

static int xmldoc_parse_specialtags ( struct ast_xml_node *  fixnode,
const char *  tabs,
const char *  posttabs,
struct ast_str **  buffer 
)
static

Definition at line 1411 of file xmldoc.c.

1412 {
1413  struct ast_xml_node *node = fixnode;
1414  int ret = 0, i;
1415 
1416  if (!node || !ast_xml_node_get_children(node)) {
1417  return ret;
1418  }
1419 
1420  for (i = 0; i < ARRAY_LEN(special_tags); i++) {
1421  if (strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
1422  continue;
1423  }
1424 
1425  ret = 1;
1426  /* This is a special tag. */
1427 
1428  /* concat data */
1429  if (!ast_strlen_zero(special_tags[i].init)) {
1430  ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init);
1431  }
1432 
1433  if (xmldoc_parse_example(node, buffer)) {
1434  ret = 1;
1435  break;
1436  }
1437 
1438  /* parse <para> elements inside special tags. */
1440  /* first <para> just print it without tabs at the begining. */
1441  if ((xmldoc_parse_para(node, "", posttabs, buffer) == 2)
1442  || (xmldoc_parse_info(node, "", posttabs, buffer) == 2)) {
1443  ret = 2;
1444  }
1445  }
1446 
1447  if (!ast_strlen_zero(special_tags[i].end)) {
1448  ast_str_append(buffer, 0, "%s%s", special_tags[i].end, posttabs);
1449  }
1450 
1451  break;
1452  }
1453 
1454  return ret;
1455 }
static int xmldoc_parse_example(struct ast_xml_node *fixnode, struct ast_str **buffer)
Definition: xmldoc.c:1358

References ARRAY_LEN, ast_str_append(), ast_strlen_zero(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), end, special_tags, xmldoc_parse_example(), xmldoc_parse_info(), and xmldoc_parse_para().

Referenced by xmldoc_get_formatted(), xmldoc_parse_common_elements(), and xmldoc_parse_parameter().

◆ xmldoc_parse_variable()

static int xmldoc_parse_variable ( struct ast_xml_node *  node,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1517 of file xmldoc.c.

1518 {
1519  struct ast_xml_node *tmp;
1520  const char *valname;
1521  const char *tmptext;
1522  struct ast_str *cleanstr;
1523  int ret = 0, printedpara=0;
1524 
1526  if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
1527  printedpara = 1;
1528  continue;
1529  }
1530 
1531  if (strcasecmp(ast_xml_node_get_name(tmp), "value")) {
1532  continue;
1533  }
1534 
1535  /* Parse a <value> tag only. */
1536  if (!printedpara) {
1537  ast_str_append(buffer, 0, "\n");
1538  printedpara = 1;
1539  }
1540  /* Parse each <value name='valuename'>desciption</value> */
1541  valname = ast_xml_get_attribute(tmp, "name");
1542  if (valname) {
1543  ret = 1;
1544  ast_str_append(buffer, 0, "%s<value>%s</value>", tabs, valname);
1545  ast_xml_free_attr(valname);
1546  }
1547  tmptext = ast_xml_get_text(tmp);
1548  /* Check inside this node for any explanation about its meaning. */
1549  if (tmptext) {
1550  /* Cleanup text. */
1551  xmldoc_string_cleanup(tmptext, &cleanstr, 1, 0);
1552  ast_xml_free_text(tmptext);
1553  if (cleanstr && ast_str_strlen(cleanstr) > 0) {
1554  ast_str_append(buffer, 0, ":%s", ast_str_buffer(cleanstr));
1555  }
1556  ast_free(cleanstr);
1557  }
1558  ast_str_append(buffer, 0, "\n");
1559  }
1560 
1561  return ret;
1562 }

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_strlen(), 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(), tmp(), xmldoc_parse_common_elements(), and xmldoc_string_cleanup().

Referenced by xmldoc_parse_variablelist().

◆ xmldoc_parse_variablelist()

static int xmldoc_parse_variablelist ( struct ast_xml_node *  node,
const char *  tabs,
struct ast_str **  buffer 
)
static

Definition at line 1578 of file xmldoc.c.

1579 {
1580  struct ast_xml_node *tmp;
1581  const char *varname;
1582  char *vartabs;
1583  int ret = 0;
1584 
1585  if (!node || !ast_xml_node_get_children(node)) {
1586  return ret;
1587  }
1588 
1589  if (strcasecmp(ast_xml_node_get_name(node), "variablelist")) {
1590  return ret;
1591  }
1592 
1593  /* use this spacing (add 4 spaces) inside a variablelist node. */
1594  if (ast_asprintf(&vartabs, "%s ", tabs) < 0) {
1595  return ret;
1596  }
1598  /* We can have a <para> element inside the variable list */
1599  if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
1600  ret = 1;
1601  continue;
1602  }
1603 
1604  if (!strcasecmp(ast_xml_node_get_name(tmp), "variable")) {
1605  /* Store the variable name in buffer. */
1606  varname = ast_xml_get_attribute(tmp, "name");
1607  if (varname) {
1608  ast_str_append(buffer, 0, "%s<variable>%s</variable>: ", tabs, varname);
1609  ast_xml_free_attr(varname);
1610  /* Parse the <variable> possible values. */
1611  xmldoc_parse_variable(tmp, vartabs, buffer);
1612  ret = 1;
1613  }
1614  }
1615  }
1616 
1617  ast_free(vartabs);
1618 
1619  return ret;
1620 }
static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1517

References ast_asprintf, ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), tmp(), xmldoc_parse_common_elements(), and xmldoc_parse_variable().

Referenced by xmldoc_get_formatted(), and xmldoc_parse_option().

◆ xmldoc_postbrlen()

static int xmldoc_postbrlen ( const char *  postbr)
static

Definition at line 120 of file xmldoc.c.

121 {
122  int postbrreallen = 0, i;
123  size_t postbrlen;
124 
125  if (!postbr) {
126  return 0;
127  }
128  postbrlen = strlen(postbr);
129  for (i = 0; i < postbrlen; i++) {
130  if (postbr[i] == '\t') {
131  postbrreallen += 8 - (postbrreallen % 8);
132  } else {
133  postbrreallen++;
134  }
135  }
136  return postbrreallen;
137 }

Referenced by xmldoc_string_wrap().

◆ xmldoc_reverse_helper()

static void xmldoc_reverse_helper ( int  reverse,
int *  len,
char **  syntax,
const char *  fmt,
  ... 
)
static

Definition at line 516 of file xmldoc.c.

517 {
518  int totlen;
519  int tmpfmtlen;
520  char *tmpfmt;
521  char *new_syntax;
522  char tmp;
523  va_list ap;
524 
525  va_start(ap, fmt);
526  if (ast_vasprintf(&tmpfmt, fmt, ap) < 0) {
527  va_end(ap);
528  return;
529  }
530  va_end(ap);
531 
532  tmpfmtlen = strlen(tmpfmt);
533  totlen = *len + tmpfmtlen + 1;
534 
535  new_syntax = ast_realloc(*syntax, totlen);
536  if (!new_syntax) {
537  ast_free(tmpfmt);
538  return;
539  }
540  *syntax = new_syntax;
541 
542  if (reverse) {
543  memmove(*syntax + tmpfmtlen, *syntax, *len);
544  /* Save this char, it will be overwritten by the \0 of strcpy. */
545  tmp = (*syntax)[0];
546  strcpy(*syntax, tmpfmt);
547  /* Restore the already saved char. */
548  (*syntax)[tmpfmtlen] = tmp;
549  (*syntax)[totlen - 1] = '\0';
550  } else {
551  strcpy(*syntax + *len, tmpfmt);
552  }
553 
554  *len = totlen - 1;
555  ast_free(tmpfmt);
556 }
#define ast_realloc(p, len)
A wrapper for realloc()
Definition: astmm.h:226
#define ast_vasprintf(ret, fmt, ap)
A wrapper for vasprintf()
Definition: astmm.h:278

References ast_free, ast_realloc, ast_vasprintf, len(), and tmp().

Referenced by xmldoc_get_syntax_fun().

◆ xmldoc_setpostbr()

static void xmldoc_setpostbr ( char *  postbr,
size_t  len,
const char *  text 
)
static

Definition at line 148 of file xmldoc.c.

149 {
150  int c, postbrlen = 0;
151 
152  if (!text) {
153  return;
154  }
155 
156  for (c = 0; c < len; c++) {
157  if (text[c] == '\t' || text[c] == ' ') {
158  postbr[postbrlen++] = text[c];
159  } else {
160  break;
161  }
162  }
163  postbr[postbrlen] = '\0';
164 }

References c, len(), and text.

Referenced by xmldoc_string_wrap().

◆ xmldoc_string_cleanup()

static void xmldoc_string_cleanup ( const char *  text,
struct ast_str **  output,
int  lastspaces,
int  maintain_newlines 
)
static

Definition at line 361 of file xmldoc.c.

362 {
363  int i;
364  size_t textlen;
365 
366  if (!text) {
367  *output = NULL;
368  return;
369  }
370 
371  textlen = strlen(text);
372 
373  *output = ast_str_create(textlen);
374  if (!(*output)) {
375  ast_log(LOG_ERROR, "Problem allocating output buffer\n");
376  return;
377  }
378 
379  for (i = 0; i < textlen; i++) {
380  if (text[i] == '\n' || text[i] == '\r') {
381  if (maintain_newlines) {
382  ast_str_append(output, 0, "%c", text[i]);
383  }
384  /* remove spaces/tabs/\n after a \n. */
385  while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') {
386  i++;
387  }
388  ast_str_append(output, 0, " ");
389  continue;
390  } else {
391  ast_str_append(output, 0, "%c", text[i]);
392  }
393  }
394 
395  /* remove last spaces (we don't want always to remove the trailing spaces). */
396  if (lastspaces) {
397  ast_str_trim_blanks(*output);
398  }
399 }
void ast_str_trim_blanks(struct ast_str *buf)
Trims trailing whitespace characters from an ast_str string.
Definition: strings.h:700

References ast_log, ast_str_append(), ast_str_create, ast_str_trim_blanks(), LOG_ERROR, NULL, and text.

Referenced by xmldoc_get_formatted(), xmldoc_parse_example(), xmldoc_parse_para(), and xmldoc_parse_variable().

◆ xmldoc_string_wrap()

static char* xmldoc_string_wrap ( const char *  text,
int  columns 
)
static

Definition at line 176 of file xmldoc.c.

177 {
178  struct ast_str *tmp;
179  char *ret, postbr[160];
180  int count, i, textlen, postbrlen, lastbreak;
181 
182  /* sanity check */
183  if (!text || columns <= 0) {
184  ast_log(LOG_WARNING, "Passing wrong arguments while trying to wrap the text\n");
185  return NULL;
186  }
187 
188  tmp = ast_str_create(strlen(text) * 3);
189 
190  if (!tmp) {
191  return NULL;
192  }
193 
194  /* Check for blanks and tabs and put them in postbr. */
195  xmldoc_setpostbr(postbr, sizeof(postbr), text);
196  postbrlen = xmldoc_postbrlen(postbr);
197 
198  count = 0;
199  lastbreak = 0;
200 
201  textlen = strlen(text);
202  for (i = 0; i < textlen; i++) {
203  if (text[i] == '\n') {
204  xmldoc_setpostbr(postbr, sizeof(postbr), &text[i] + 1);
205  postbrlen = xmldoc_postbrlen(postbr);
206  count = 0;
207  lastbreak = 0;
208  } else if (text[i] == ESC) {
209  /* Walk over escape sequences without counting them. */
210  do {
211  ast_str_append(&tmp, 0, "%c", text[i]);
212  i++;
213  } while (i < textlen && text[i] != 'm');
214  } else {
215  if (text[i] == ' ') {
216  lastbreak = i;
217  }
218  count++;
219  }
220 
221  if (count > columns) {
222  /* Seek backwards if it was at most 30 characters ago. */
223  int back = i - lastbreak;
224  if (lastbreak && back > 0 && back < 30) {
225  ast_str_truncate(tmp, -back);
226  i = lastbreak; /* go back a bit */
227  }
228  ast_str_append(&tmp, 0, "\n%s", postbr);
229  count = postbrlen;
230  lastbreak = 0;
231  } else {
232  ast_str_append(&tmp, 0, "%c", text[i]);
233  }
234  }
235 
236  ret = ast_strdup(ast_str_buffer(tmp));
237  ast_free(tmp);
238 
239  return ret;
240 }
#define ESC
Definition: term.h:30
static void xmldoc_setpostbr(char *postbr, size_t len, const char *text)
Definition: xmldoc.c:148
static int xmldoc_postbrlen(const char *postbr)
Definition: xmldoc.c:120

References ast_free, ast_log, ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_truncate(), ast_strdup, ESC, LOG_WARNING, NULL, text, tmp(), xmldoc_postbrlen(), and xmldoc_setpostbr().

Referenced by ast_xmldoc_printable().

◆ xmldoc_unload_documentation()

static void xmldoc_unload_documentation ( void  )
static

Close and unload XML documentation.

Definition at line 2864 of file xmldoc.c.

2865 {
2866  struct documentation_tree *doctree;
2867 
2869 
2871  while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
2872  ast_free(doctree->filename);
2873  ast_xml_close(doctree->doc);
2874  ast_free(doctree);
2875  }
2877 
2878  ast_xml_finish();
2879 }
int ast_cli_unregister(struct ast_cli_entry *e)
Unregisters a command or an array of commands.
Definition: main/cli.c:2431
#define AST_RWLIST_REMOVE_HEAD
Definition: linkedlists.h:844
int ast_xml_finish(void)
Cleanup library allocated global data.
Definition: xml.c:57

References ast_cli_unregister(), ast_free, AST_RWLIST_REMOVE_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_xml_close(), ast_xml_finish(), cli_dump_xmldocs, documentation_tree::doc, and documentation_tree::filename.

Referenced by ast_xmldoc_load_documentation().

Variable Documentation

◆ cli_dump_xmldocs

struct ast_cli_entry cli_dump_xmldocs = { .handler = handle_dump_docs , .summary = "Dump the XML docs to the specified file" ,}
static

Definition at line 2789 of file xmldoc.c.

Referenced by ast_xmldoc_load_documentation(), and xmldoc_unload_documentation().

◆ colorized_tags

const struct strcolorized_tags colorized_tags[]
static

Referenced by ast_xmldoc_printable().

◆ default_documentation_language

const char default_documentation_language[] = "en_US"
static

Default documentation language.

Definition at line 44 of file xmldoc.c.

Referenced by ast_xmldoc_load_documentation().

◆ documentation_language

char documentation_language[6]
static

◆ special_tags

const struct strspecial_tags special_tags[]
static
Initial value:
= {
{ "note", "<note>NOTE:</note> ", "" },
{ "warning", "<warning>WARNING!!!:</warning> ", "" },
{ "example", "<example>Example:</example> ", "" },
}

Referenced by xmldoc_has_specialtags(), and xmldoc_parse_specialtags().

◆ stxtype

struct strsyntaxtype stxtype[]
static

◆ xmldoc_text_columns

const int xmldoc_text_columns = 79
static

Number of columns to print when showing the XML documentation with a 'core show application/function *' CLI command. Used in text wrapping.

Definition at line 48 of file xmldoc.c.

Referenced by ast_xmldoc_printable().

◆ xmldoc_tree

struct xmldoc_tree xmldoc_tree = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }
static