Asterisk - The Open Source Telephony Project GIT-master-754dea3
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Modules Pages
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_since (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_since (const char *type, const char *name, const char *module)
 Parse the <since> 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 char * handle_reload_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_load_documentation (int first_time)
 
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_purge_documentation (void)
 
static int xmldoc_reload_documentation (void)
 
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 struct ast_cli_entry cli_reload_xmldocs = { .handler = handle_reload_docs , .summary = "Reload the XML docs" ,}
 
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 1153 of file xmldoc.c.

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

Function Documentation

◆ _ast_xmldoc_build_arguments()

static char * _ast_xmldoc_build_arguments ( struct ast_xml_node *  node)
static

Definition at line 2129 of file xmldoc.c.

2130{
2131 char *retstr = NULL;
2132 struct ast_str *ret;
2133
2134 ret = ast_str_create(128);
2135 if (!ret) {
2136 return NULL;
2137 }
2138
2139 /* Find the syntax field. */
2141 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
2142 break;
2143 }
2144 }
2145
2147 /* We couldn't find the syntax node. */
2148 ast_free(ret);
2149 return NULL;
2150 }
2151
2153 xmldoc_parse_parameter(node, "", &ret);
2154 }
2155
2156 if (ast_str_strlen(ret) > 0) {
2157 /* remove last '\n' */
2158 char *buf = ast_str_buffer(ret);
2159 if (buf[ast_str_strlen(ret) - 1] == '\n') {
2160 ast_str_truncate(ret, -1);
2161 }
2162 retstr = ast_strdup(ast_str_buffer(ret));
2163 }
2164 ast_free(ret);
2165
2166 return retstr;
2167}
#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:786
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:730
Support for dynamic strings.
Definition: strings.h:623
Definition: test_heap.c:38
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:390
struct ast_xml_node * ast_xml_node_get_next(struct ast_xml_node *node)
Get the next node in the same level.
Definition: xml.c:400
static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1992

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

2352{
2353 return _xmldoc_build_field(node, "description", 0);
2354}
static char * _xmldoc_build_field(struct ast_xml_node *node, const char *var, int raw)
Definition: xmldoc.c:2256

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

1641{
1642 char *output;
1643 struct ast_str *outputstr;
1644 const char *typename;
1645 const char *content;
1646 int first = 1;
1647
1648 /* Find the <see-also> node. */
1650 if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
1651 break;
1652 }
1653 }
1654
1656 /* we couldn't find a <see-also> node. */
1657 return NULL;
1658 }
1659
1660 /* prepare the output string. */
1661 outputstr = ast_str_create(128);
1662 if (!outputstr) {
1663 return NULL;
1664 }
1665
1666 /* get into the <see-also> node. */
1668 if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
1669 continue;
1670 }
1671
1672 /* parse the <ref> node. 'type' attribute is required. */
1673 typename = ast_xml_get_attribute(node, "type");
1674 if (!typename) {
1675 continue;
1676 }
1677 content = ast_xml_get_text(node);
1678 if (!content) {
1679 ast_xml_free_attr(typename);
1680 continue;
1681 }
1682 if (!strcasecmp(typename, "application")) {
1683 ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
1684 } else if (!strcasecmp(typename, "function")) {
1685 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1686 } else if (!strcasecmp(typename, "astcli")) {
1687 ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
1688 } else {
1689 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1690 }
1691 first = 0;
1692 ast_xml_free_text(content);
1693 ast_xml_free_attr(typename);
1694 }
1695
1696 output = ast_strdup(ast_str_buffer(outputstr));
1697 ast_free(outputstr);
1698
1699 return output;
1700}
struct sla_ringing_trunk * first
Definition: app_sla.c:338
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:267
const char * ast_xml_get_text(struct ast_xml_node *node)
Get an element content string.
Definition: xml.c:353
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:253
void ast_xml_free_text(const char *text)
Free a content element that was returned by ast_xml_get_text()
Definition: xml.c:260

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

static char * _ast_xmldoc_build_since ( struct ast_xml_node *  node)
static

Definition at line 1739 of file xmldoc.c.

1740{
1741 char *output;
1742 struct ast_str *outputstr;
1743 const char *content;
1744 int first = 1;
1745
1746 /* Find the <since> node. */
1748 if (!strcasecmp(ast_xml_node_get_name(node), "since")) {
1749 break;
1750 }
1751 }
1752
1754 /* we couldn't find a <since> node. */
1755 return NULL;
1756 }
1757
1758 /* prepare the output string. */
1759 outputstr = ast_str_create(128);
1760 if (!outputstr) {
1761 return NULL;
1762 }
1763
1764 /* get into the <since> node. */
1766 if (strcasecmp(ast_xml_node_get_name(node), "version")) {
1767 continue;
1768 }
1769
1770 content = ast_xml_get_text(node);
1771 if (!content) {
1772 continue;
1773 }
1774
1775 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1776
1777 first = 0;
1778 ast_xml_free_text(content);
1779 }
1780
1781 output = ast_strdup(ast_str_buffer(outputstr));
1782 ast_free(outputstr);
1783
1784 return output;
1785}

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strdup, ast_xml_free_text(), 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_since(), and xmldoc_build_documentation_item().

◆ _ast_xmldoc_build_synopsis()

static char * _ast_xmldoc_build_synopsis ( struct ast_xml_node *  node)
static

Definition at line 2328 of file xmldoc.c.

2329{
2330 return _xmldoc_build_field(node, "synopsis", 1);
2331}

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

1216{
1217 char *syntax = NULL;
1218 struct ast_xml_node *node = root_node;
1219
1221 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1222 break;
1223 }
1224 }
1225
1226 switch (xmldoc_get_syntax_type(type)) {
1227 case FUNCTION_SYNTAX:
1228 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1229 break;
1230 case COMMAND_SYNTAX:
1231 syntax = xmldoc_get_syntax_cmd(node, name, 1);
1232 break;
1233 case MANAGER_SYNTAX:
1234 syntax = xmldoc_get_syntax_manager(node, name, "Action");
1235 break;
1237 syntax = xmldoc_get_syntax_manager(node, name, "Event");
1238 break;
1240 syntax = xmldoc_get_syntax_config_option(root_node, name);
1241 break;
1244 break;
1245 default:
1246 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1247 }
1248
1249 return syntax;
1250}
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
static char * xmldoc_get_syntax_config_object(struct ast_xml_node *fixnode, const char *name)
Definition: xmldoc.c:1089
static enum syntaxtype xmldoc_get_syntax_type(const char *type)
Definition: xmldoc.c:1188
static char * xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
Definition: xmldoc.c:931
static char * xmldoc_get_syntax_config_option(struct ast_xml_node *fixnode, const char *name)
Definition: xmldoc.c:1125
static char * xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name, const char *manager_type)
Definition: xmldoc.c:1037
static char * xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
Definition: xmldoc.c:637

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

2257{
2258 char *ret = NULL;
2259 struct ast_str *formatted;
2260
2262
2264 return ret;
2265 }
2266
2267 formatted = xmldoc_get_formatted(node, raw, raw);
2268 if (formatted && ast_str_strlen(formatted) > 0) {
2269 ret = ast_strdup(ast_str_buffer(formatted));
2270 }
2271 ast_free(formatted);
2272
2273 return ret;
2274}
#define var
Definition: ast_expr2f.c:605
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:297
static struct ast_str * xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
Definition: xmldoc.c:2202

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

2397{
2398 struct ast_xml_doc_item *item;
2399
2402 if (!item) {
2403 ast_log(AST_LOG_ERROR, "Failed to allocate memory for ast_xml_doc_item instance\n");
2404 return NULL;
2405 }
2406
2407 if ( !(item->synopsis = ast_str_create(128))
2408 || !(item->since = ast_str_create(128))
2409 || !(item->description = ast_str_create(128))
2410 || !(item->syntax = ast_str_create(128))
2411 || !(item->arguments = ast_str_create(128))
2412 || !(item->seealso = ast_str_create(128))
2413 ) {
2414 ast_log(AST_LOG_ERROR, "Failed to allocate strings for ast_xml_doc_item instance\n");
2415 goto ast_xml_doc_item_failure;
2416 }
2417
2418 if (ast_string_field_init(item, 64)) {
2419 ast_log(AST_LOG_ERROR, "Failed to initialize string field for ast_xml_doc_item instance\n");
2420 goto ast_xml_doc_item_failure;
2421 }
2424
2425 return item;
2426
2427ast_xml_doc_item_failure:
2428 ao2_ref(item, -1);
2429 return NULL;
2430}
#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:2366

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

2450{
2451 struct ast_xml_doc_item *left = obj;
2452 struct ast_xml_doc_item *right = arg;
2453 const char *match = (flags & OBJ_KEY) ? arg : right->name;
2454 return strcasecmp(left->name, match) ? 0 : (CMP_MATCH | CMP_STOP);
2455}
@ 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:2387
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 2366 of file xmldoc.c.

2367{
2368 struct ast_xml_doc_item *doc = obj;
2369
2370 if (!doc) {
2371 return;
2372 }
2373
2374 ast_free(doc->synopsis);
2375 ast_free(doc->since);
2376 ast_free(doc->description);
2377 ast_free(doc->syntax);
2378 ast_free(doc->arguments);
2379 ast_free(doc->seealso);
2381
2382 if (AST_LIST_NEXT(doc, next)) {
2383 ao2_ref(AST_LIST_NEXT(doc, next), -1);
2384 AST_LIST_NEXT(doc, next) = NULL;
2385 }
2386}
#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 * since
Definition: xmldoc.h:82
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::since, 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 2437 of file xmldoc.c.

2438{
2439 const struct ast_xml_doc_item *item = obj;
2440 const char *name = (flags & OBJ_KEY) ? obj : item->name;
2441 return ast_str_case_hash(name);
2442}
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:1303
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 2169 of file xmldoc.c.

2170{
2171 struct ast_xml_node *node;
2172 char *arguments;
2173
2175 return NULL;
2176 }
2177
2180
2183 return NULL;
2184 }
2185
2186 arguments = _ast_xmldoc_build_arguments(node);
2188 return arguments;
2189}
#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
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
Container of documentation trees.
Definition: xmldoc.c:74
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:2129
static struct ast_xml_node * xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
Definition: xmldoc.c:435

References _ast_xmldoc_build_arguments(), AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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_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 2356 of file xmldoc.c.

2357{
2358 return xmldoc_build_field(type, name, module, "description", 0);
2359}
static char * xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
Definition: xmldoc.c:2289

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

2779{
2780 struct ao2_container *docs;
2781 struct ast_xml_node *node = NULL, *instance = NULL;
2782 struct documentation_tree *doctree;
2783 const char *name;
2784
2787 if (!docs) {
2788 ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
2789 return NULL;
2790 }
2791
2793 AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2794 /* the core xml documents have priority over thirdparty document. */
2795 node = ast_xml_get_root(doctree->doc);
2796 if (!node) {
2797 break;
2798 }
2799
2801 struct ast_xml_doc_item *item = NULL;
2802
2803 /* Ignore empty nodes or nodes that aren't of the type requested */
2805 continue;
2806 }
2807 name = ast_xml_get_attribute(node, "name");
2808 if (!name) {
2809 continue;
2810 }
2811
2812 switch (xmldoc_get_syntax_type(type)) {
2814 {
2815 struct ast_xml_doc_item_list root;
2816
2817 AST_LIST_HEAD_INIT(&root);
2818 for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
2819 struct ast_xml_doc_item *temp;
2820 if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
2821 continue;
2822 }
2823 temp = xmldoc_build_documentation_item(instance, name, type);
2824 if (!temp) {
2825 break;
2826 }
2827 AST_LIST_INSERT_TAIL(&root, temp, next);
2828 }
2829 item = AST_LIST_FIRST(&root);
2830 break;
2831 }
2832 case CONFIG_INFO_SYNTAX:
2833 {
2834 RAII_VAR(const char *, name, ast_xml_get_attribute(node, "name"), ast_xml_free_attr);
2835
2836 if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), "configInfo")) {
2837 break;
2838 }
2839
2841 if (item) {
2842 struct ast_xml_doc_item_list root;
2843
2844 AST_LIST_HEAD_INIT(&root);
2845 AST_LIST_INSERT_TAIL(&root, item, next);
2846 build_config_docs(node, &root);
2847 }
2848 break;
2849 }
2850 default:
2852 }
2854
2855 if (item) {
2856 ao2_link(docs, item);
2857 ao2_t_ref(item, -1, "Dispose of creation ref");
2858 }
2859 }
2860 }
2862
2863 return docs;
2864}
#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_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
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:230
static int ast_xml_doc_item_cmp(void *obj, void *arg, int flags)
Definition: xmldoc.c:2449
static struct ast_xml_doc_item * xmldoc_build_documentation_item(struct ast_xml_node *node, const char *name, const char *type)
Definition: xmldoc.c:2469
static int ast_xml_doc_item_hash(const void *obj, const int flags)
Definition: xmldoc.c:2437
static void build_config_docs(struct ast_xml_node *cur, struct ast_xml_doc_item_list *root)
Definition: xmldoc.c:2701

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

2649{
2650 struct ast_xml_node *node;
2651 static struct ast_xml_doc_item *response;
2652
2654 return NULL;
2655 }
2656
2659
2662 return NULL;
2663 }
2664
2667 return response;
2668}
static struct ast_xml_doc_item * xmldoc_build_final_response(struct ast_xml_node *manager_action)
Definition: xmldoc.c:2614

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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 2578 of file xmldoc.c.

2579{
2580 struct ast_xml_node *node;
2581 struct ast_xml_doc_item *responses;
2582
2584 return NULL;
2585 }
2586
2589
2592 return NULL;
2593 }
2594
2595 responses = xmldoc_build_list_responses(node);
2597 return responses;
2598}
static struct ast_xml_doc_item * xmldoc_build_list_responses(struct ast_xml_node *manager_action)
Definition: xmldoc.c:2534

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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 1702 of file xmldoc.c.

1703{
1704 char *output;
1705 struct ast_xml_node *node;
1706
1708 return NULL;
1709 }
1710
1711 /* get the application/function root node. */
1716 return NULL;
1717 }
1718
1721
1722 return output;
1723}
static char * _ast_xmldoc_build_seealso(struct ast_xml_node *node)
Definition: xmldoc.c:1640

References _ast_xmldoc_build_seealso(), AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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_since()

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

Parse the <since> 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 since node.

Definition at line 1787 of file xmldoc.c.

1788{
1789 char *output;
1790 struct ast_xml_node *node;
1791
1793 return NULL;
1794 }
1795
1796 /* get the application/function root node. */
1801 return NULL;
1802 }
1803
1804 output = _ast_xmldoc_build_since(node);
1806
1807 return output;
1808}
static char * _ast_xmldoc_build_since(struct ast_xml_node *node)
Definition: xmldoc.c:1739

References _ast_xmldoc_build_since(), AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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 2333 of file xmldoc.c.

2334{
2335 return xmldoc_build_field(type, name, module, "synopsis", 1);
2336}

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

1253{
1254 struct ast_xml_node *node;
1255 char *syntax;
1256
1259 if (!node) {
1261 return NULL;
1262 }
1263
1266 return syntax;
1267}
static char * _ast_xmldoc_build_syntax(struct ast_xml_node *root_node, const char *type, const char *name)
Definition: xmldoc.c:1215

References _ast_xmldoc_build_syntax(), AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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 3141 of file xmldoc.c.

3142{
3143 return xmldoc_load_documentation(1);
3144}
static int xmldoc_load_documentation(int first_time)
Definition: xmldoc.c:3014

References xmldoc_load_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 241 of file xmldoc.c.

242{
243 struct ast_str *colorized;
244 char *wrapped = NULL;
245 int i, c, len, colorsection;
246 char *tmp;
247 size_t bwinputlen;
248 static const int base_fg = COLOR_CYAN;
249
250 if (!bwinput) {
251 return NULL;
252 }
253
254 bwinputlen = strlen(bwinput);
255
256 if (!(colorized = ast_str_create(256))) {
257 return NULL;
258 }
259
260 if (withcolors) {
261 ast_term_color_code(&colorized, base_fg, 0);
262 if (!colorized) {
263 return NULL;
264 }
265 }
266
267 for (i = 0; i < bwinputlen; i++) {
268 colorsection = 0;
269 /* Check if we are at the beginning of a tag to be colorized. */
270 for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
271 if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
272 continue;
273 }
274
275 if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
276 continue;
277 }
278
279 len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
280
281 /* Setup color */
282 if (withcolors) {
284 /* Turn off *bright* colors */
285 ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
286 } else {
287 /* Turn on *bright* colors */
288 ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
289 }
290 if (!colorized) {
291 return NULL;
292 }
293 }
294
295 /* copy initial string replace */
296 ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
297 if (!colorized) {
298 return NULL;
299 }
300 {
301 char buf[len + 1];
302 ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
303 ast_str_append(&colorized, 0, "%s", buf);
304 }
305 if (!colorized) {
306 return NULL;
307 }
308
309 /* copy the ending string replace */
310 ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
311 if (!colorized) {
312 return NULL;
313 }
314
315 /* Continue with the last color. */
316 if (withcolors) {
317 ast_term_color_code(&colorized, base_fg, 0);
318 if (!colorized) {
319 return NULL;
320 }
321 }
322
323 i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
324 colorsection = 1;
325 break;
326 }
327
328 if (!colorsection) {
329 ast_str_append(&colorized, 0, "%c", bwinput[i]);
330 if (!colorized) {
331 return NULL;
332 }
333 }
334 }
335
336 if (withcolors) {
337 ast_str_append(&colorized, 0, "%s", ast_term_reset());
338 if (!colorized) {
339 return NULL;
340 }
341 }
342
343 /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
345
346 ast_free(colorized);
347
348 return wrapped;
349}
char * strcasestr(const char *, const char *)
char * end
Definition: eagi_proxy.c:73
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#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:425
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
const char * ast_term_reset(void)
Returns the terminal reset code.
Definition: term.c:357
#define COLOR_CYAN
Definition: term.h:62
static struct test_val c
#define ARRAY_LEN(a)
Definition: utils.h:666
static const struct strcolorized_tags colorized_tags[]
static char * xmldoc_string_wrap(const char *text, int columns)
Definition: xmldoc.c:175
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(), 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 2670 of file xmldoc.c.

2671{
2672 struct ast_xml_xpath_results *results = NULL;
2673 struct documentation_tree *doctree;
2674 RAII_VAR(struct ast_str *, xpath_str, ast_str_create(128), ast_free);
2675 va_list ap;
2676 int res;
2677
2678 if (!xpath_str) {
2679 return NULL;
2680 }
2681
2682 va_start(ap, fmt);
2683 res = ast_str_set_va(&xpath_str, 0, fmt, ap);
2684 va_end(ap);
2685 if (res == AST_DYNSTR_BUILD_FAILED) {
2686 return NULL;
2687 }
2688
2690 AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2691 if (!(results = ast_xml_query(doctree->doc, ast_str_buffer(xpath_str)))) {
2692 continue;
2693 }
2694 break;
2695 }
2697
2698 return results;
2699}
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:1030
@ AST_DYNSTR_BUILD_FAILED
Definition: strings.h:943
struct ast_xml_xpath_results * ast_xml_query(struct ast_xml_doc *doc, const char *xpath_str)
Execute an XPath query on an XML document.
Definition: xml.c:441

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

2730{
2731 const char *name;
2732 char *syntax;
2733 char *seealso;
2734 char *arguments;
2735 char *synopsis;
2736 char *description;
2737
2738 if (!item || !item->node) {
2739 return -1;
2740 }
2741
2742 name = ast_xml_get_attribute(item->node, "name");
2743 if (!name) {
2744 return -1;
2745 }
2746
2747 syntax = _ast_xmldoc_build_syntax(item->node, item->type, name);
2748 seealso = _ast_xmldoc_build_seealso(item->node);
2749 arguments = _ast_xmldoc_build_arguments(item->node);
2751 description = _ast_xmldoc_build_description(item->node);
2752
2753 if (syntax) {
2754 ast_str_set(&item->syntax, 0, "%s", syntax);
2755 }
2756 if (seealso) {
2757 ast_str_set(&item->seealso, 0, "%s", seealso);
2758 }
2759 if (arguments) {
2760 ast_str_set(&item->arguments, 0, "%s", arguments);
2761 }
2762 if (synopsis) {
2763 ast_str_set(&item->synopsis, 0, "%s", synopsis);
2764 }
2765 if (description) {
2766 ast_str_set(&item->description, 0, "%s", description);
2767 }
2768
2769 ast_free(syntax);
2770 ast_free(seealso);
2771 ast_free(arguments);
2773 ast_free(description);
2775 return 0;
2776}
static char * synopsis
Definition: func_enum.c:166
int ast_str_set(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Set a dynamic string using variable arguments.
Definition: strings.h:1113
enum aco_type_t type
static char * _ast_xmldoc_build_synopsis(struct ast_xml_node *node)
Definition: xmldoc.c:2328
static char * _ast_xmldoc_build_description(struct ast_xml_node *node)
Definition: xmldoc.c:2351

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

2702{
2703 struct ast_xml_node *iter;
2704 struct ast_xml_doc_item *item;
2705
2706 for (iter = ast_xml_node_get_children(cur); iter; iter = ast_xml_node_get_next(iter)) {
2707 const char *iter_name;
2708 if (strncasecmp(ast_xml_node_get_name(iter), "config", 6)) {
2709 continue;
2710 }
2711 iter_name = ast_xml_get_attribute(iter, "name");
2712 /* Now add all of the child config-related items to the list */
2713 if (!(item = xmldoc_build_documentation_item(iter, iter_name, ast_xml_node_get_name(iter)))) {
2714 ast_log(LOG_ERROR, "Could not build documentation for '%s:%s'\n", ast_xml_node_get_name(iter), iter_name);
2715 ast_xml_free_attr(iter_name);
2716 break;
2717 }
2718 ast_xml_free_attr(iter_name);
2719 if (!strcasecmp(ast_xml_node_get_name(iter), "configOption")) {
2720 const char *name = ast_xml_get_attribute(cur, "name");
2723 }
2725 build_config_docs(iter, root);
2726 }
2727}
#define LOG_ERROR
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(), build_config_docs(), 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(), and build_config_docs().

◆ handle_dump_docs()

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

Definition at line 2912 of file xmldoc.c.

2913{
2914 struct documentation_tree *doctree;
2915 struct ast_xml_doc *dumpdoc;
2916 struct ast_xml_node *dumproot;
2917 FILE *f;
2918
2919 switch (cmd) {
2920 case CLI_INIT:
2921 e->command = "xmldoc dump";
2922 e->usage =
2923 "Usage: xmldoc dump <filename>\n"
2924 " Dump XML documentation to a file\n";
2925 return NULL;
2926 case CLI_GENERATE:
2927 return NULL;
2928 }
2929
2930 if (a->argc != 3) {
2931 return CLI_SHOWUSAGE;
2932 }
2933
2934 dumpdoc = ast_xml_new();
2935 if (!dumpdoc) {
2936 ast_log(LOG_ERROR, "Could not create new XML document\n");
2937 return CLI_FAILURE;
2938 }
2939
2940 dumproot = ast_xml_new_node("docs");
2941 if (!dumproot) {
2942 ast_xml_close(dumpdoc);
2943 ast_log(LOG_ERROR, "Could not create new XML root node\n");
2944 return CLI_FAILURE;
2945 }
2946
2947 ast_xml_set_root(dumpdoc, dumproot);
2948
2950 AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2951 struct ast_xml_node *root_node = ast_xml_get_root(doctree->doc);
2952 struct ast_xml_node *kids = ast_xml_node_get_children(root_node);
2953 struct ast_xml_node *kids_copy;
2954
2955 /* If there are no kids someone screwed up, but we check anyway. */
2956 if (!kids) {
2957 continue;
2958 }
2959
2960 kids_copy = ast_xml_copy_node_list(kids);
2961 if (!kids_copy) {
2962 ast_xml_close(dumpdoc);
2963 ast_log(LOG_ERROR, "Could not create copy of XML node list\n");
2964 return CLI_FAILURE;
2965 }
2966
2967 ast_xml_add_child_list(dumproot, kids_copy);
2968 }
2970
2971 if (!(f = fopen(a->argv[2], "w"))) {
2972 ast_xml_close(dumpdoc);
2973 ast_log(LOG_ERROR, "Could not open file '%s': %s\n", a->argv[2], strerror(errno));
2974 return CLI_FAILURE;
2975 }
2976
2977 ast_xml_doc_dump_file(f, dumpdoc);
2978 ast_xml_close(dumpdoc);
2979
2980 fclose(f);
2981 return CLI_SUCCESS;
2982}
#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_node * ast_xml_copy_node_list(struct ast_xml_node *list)
Create a copy of a n ode list.
Definition: xml.c:184
struct ast_xml_node * ast_xml_new_node(const char *name)
Create a XML node.
Definition: xml.c:144
void ast_xml_close(struct ast_xml_doc *doc)
Close an already open document and free the used structure.
Definition: xml.c:211
int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc)
Dump the specified document to a file.
Definition: xml.c:380
struct ast_xml_doc * ast_xml_new(void)
Create a XML document.
Definition: xml.c:136
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:176
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:221

References a, AST_LIST_TRAVERSE, ast_log, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_add_child_list(), ast_xml_close(), ast_xml_copy_node_list(), ast_xml_doc_dump_file(), ast_xml_get_root(), ast_xml_new(), ast_xml_new_node(), ast_xml_node_get_children(), ast_xml_set_root(), CLI_FAILURE, CLI_GENERATE, CLI_INIT, CLI_SHOWUSAGE, CLI_SUCCESS, ast_cli_entry::command, documentation_tree::doc, errno, LOG_ERROR, NULL, and ast_cli_entry::usage.

◆ handle_reload_docs()

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

Definition at line 3151 of file xmldoc.c.

3152{
3153 switch (cmd) {
3154 case CLI_INIT:
3155 e->command = "xmldoc reload";
3156 e->usage =
3157 "Usage: xmldoc reload\n"
3158 " Reload XML documentation\n";
3159 return NULL;
3160 case CLI_GENERATE:
3161 return NULL;
3162 }
3163
3165 return CLI_SUCCESS;
3166}
static int xmldoc_reload_documentation(void)
Definition: xmldoc.c:3146

References CLI_GENERATE, CLI_INIT, CLI_SUCCESS, ast_cli_entry::command, NULL, ast_cli_entry::usage, and xmldoc_reload_documentation().

◆ xmldoc_attribute_match()

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

Definition at line 411 of file xmldoc.c.

412{
413 const char *attr_value = ast_xml_get_attribute(node, attr);
414 int match = attr_value && !strcmp(attr_value, value);
415 ast_xml_free_attr(attr_value);
416 return match;
417}
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 2469 of file xmldoc.c.

2470{
2471 struct ast_xml_doc_item *item;
2472 char *synopsis;
2473 char *since;
2474 char *description;
2475 char *syntax;
2476 char *arguments;
2477 char *seealso;
2478
2479 if (!(item = ast_xml_doc_item_alloc(name, type))) {
2480 return NULL;
2481 }
2482 item->node = node;
2483
2490
2491 if (synopsis) {
2492 ast_str_set(&item->synopsis, 0, "%s", synopsis);
2493 }
2494 if (since) {
2495 ast_str_set(&item->since, 0, "%s", since);
2496 }
2497 if (description) {
2498 ast_str_set(&item->description, 0, "%s", description);
2499 }
2500 if (syntax) {
2501 ast_str_set(&item->syntax, 0, "%s", syntax);
2502 }
2503 if (arguments) {
2504 ast_str_set(&item->arguments, 0, "%s", arguments);
2505 }
2506 if (seealso) {
2507 ast_str_set(&item->seealso, 0, "%s", seealso);
2508 }
2509
2511 ast_free(since);
2516
2517 return item;
2518}
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:2396

References _ast_xmldoc_build_arguments(), _ast_xmldoc_build_description(), _ast_xmldoc_build_seealso(), _ast_xmldoc_build_since(), _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, ast_xml_doc_item::since, 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 2289 of file xmldoc.c.

2290{
2291 struct ast_xml_node *node;
2292 char *field;
2293
2295 ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
2296 return NULL;
2297 }
2298
2301
2302 if (!node) {
2304 ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation"
2305 " If this module was recently built, run 'xmldoc reload' to refresh documentation\n",
2306 type, name);
2307 return NULL;
2308 }
2309
2310 field = _xmldoc_build_field(node, var, raw);
2312 return field;
2313}
#define LOG_WARNING

References _xmldoc_build_field(), ast_log, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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 2614 of file xmldoc.c.

2615{
2616 struct ast_xml_node *responses;
2617 struct ast_xml_node *final_response_event;
2618 struct ast_xml_node *event_instance;
2619
2621 "responses", NULL, NULL);
2622 if (!responses) {
2623 return NULL;
2624 }
2625
2626 final_response_event = ast_xml_find_element(ast_xml_node_get_children(responses),
2627 "managerEvent", NULL, NULL);
2628 if (!final_response_event) {
2629 return NULL;
2630 }
2631
2632 event_instance = ast_xml_find_element(ast_xml_node_get_children(final_response_event),
2633 "managerEventInstance", NULL, NULL);
2634 if (!event_instance) {
2635 return NULL;
2636 } else {
2637 const char *name;
2638 struct ast_xml_doc_item *res;
2639
2640 name = ast_xml_get_attribute(final_response_event, "name");
2641 res = xmldoc_build_documentation_item(event_instance, name, "managerEvent");
2643 return res;
2644 }
2645
2646}

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

2535{
2536 struct ast_xml_node *event;
2537 struct ast_xml_node *responses;
2538 struct ast_xml_node *list_elements;
2539 struct ast_xml_doc_item_list root;
2540
2541 AST_LIST_HEAD_INIT(&root);
2542
2544 if (!responses) {
2545 return NULL;
2546 }
2547
2548 list_elements = ast_xml_find_element(ast_xml_node_get_children(responses), "list-elements", NULL, NULL);
2549 if (!list_elements) {
2550 return NULL;
2551 }
2552
2553 /* Iterate over managerEvent nodes */
2554 for (event = ast_xml_node_get_children(list_elements); event; event = ast_xml_node_get_next(event)) {
2555 struct ast_xml_node *event_instance;
2556 RAII_VAR(const char *, name, ast_xml_get_attribute(event, "name"),
2558 struct ast_xml_doc_item *new_item;
2559
2560 if (!name || strcmp(ast_xml_node_get_name(event), "managerEvent")) {
2561 continue;
2562 }
2563
2565 "managerEventInstance", NULL, NULL);
2566 new_item = xmldoc_build_documentation_item(event_instance, name, "managerEvent");
2567 if (!new_item) {
2569 return NULL;
2570 }
2571
2572 AST_LIST_INSERT_TAIL(&root, new_item, next);
2573 }
2574
2575 return AST_LIST_FIRST(&root);
2576}
#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 2202 of file xmldoc.c.

2203{
2204 struct ast_xml_node *tmp;
2205 const char *notcleanret, *tmpstr;
2206 struct ast_str *ret;
2207
2208 if (raw_output) {
2209 /* xmldoc_string_cleanup will allocate the ret object */
2210 notcleanret = ast_xml_get_text(node);
2211 tmpstr = notcleanret;
2212 xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0, 0);
2213 ast_xml_free_text(tmpstr);
2214 } else {
2215 ret = ast_str_create(128);
2216 if (!ret) {
2217 return NULL;
2218 }
2219 for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
2220 /* if found, parse children elements. */
2221 if (xmldoc_parse_common_elements(tmp, "", "\n", &ret)) {
2222 continue;
2223 }
2224 if (xmldoc_parse_variablelist(tmp, "", &ret)) {
2225 continue;
2226 }
2227 if (xmldoc_parse_enumlist(tmp, " ", &ret)) {
2228 continue;
2229 }
2230 if (xmldoc_parse_specialtags(tmp, "", "", &ret)) {
2231 continue;
2232 }
2233 }
2234 /* remove last '\n' */
2235 /* XXX Don't modify ast_str internals manually */
2236 tmpstr = ast_str_buffer(ret);
2237 if (tmpstr[ast_str_strlen(ret) - 1] == '\n') {
2238 ast_str_truncate(ret, -1);
2239 }
2240 }
2241 return ret;
2242}
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:360
static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1415
static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1582
static int xmldoc_parse_common_elements(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1285
static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1856

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

436{
437 struct ast_xml_node *node = NULL;
438 struct ast_xml_node *first_match = NULL;
439 struct ast_xml_node *lang_match = NULL;
440 struct documentation_tree *doctree;
441
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 }
500
501 return node;
502}
static char language[MAX_LANGUAGE]
Definition: chan_iax2.c:348
static int xmldoc_attribute_match(struct ast_xml_node *node, const char *attr, const char *value)
Definition: xmldoc.c:411

References AST_LIST_TRAVERSE, 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_since(), 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 931 of file xmldoc.c.

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

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_get_syntax_cmd(), xmldoc_has_inside(), and xmldoc_parse_cmd_enumlist().

Referenced by _ast_xmldoc_build_syntax(), xmldoc_get_syntax_cmd(), 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 1089 of file xmldoc.c.

1090{
1091 struct ast_xml_node *matchinfo, *tmp;
1092 int match;
1093 const char *attr_value;
1094 const char *text;
1095 RAII_VAR(struct ast_str *, syntax, ast_str_create(128), ast_free);
1096
1097 if (!syntax || !fixnode) {
1098 return NULL;
1099 }
1100 if (!(matchinfo = ast_xml_find_element(ast_xml_node_get_children(fixnode), "matchInfo", NULL, NULL))) {
1101 return NULL;
1102 }
1103 if (!(tmp = ast_xml_find_element(ast_xml_node_get_children(matchinfo), "category", NULL, NULL))) {
1104 return NULL;
1105 }
1106 attr_value = ast_xml_get_attribute(tmp, "match");
1107 if (attr_value) {
1108 match = ast_true(attr_value);
1109 text = ast_xml_get_text(tmp);
1110 ast_str_set(&syntax, 0, "category %s /%s/", match ? "=~" : "!~", text);
1111 ast_xml_free_attr(attr_value);
1113 }
1114
1115 if ((tmp = ast_xml_find_element(ast_xml_node_get_children(matchinfo), "field", NULL, NULL))) {
1116 text = ast_xml_get_text(tmp);
1117 attr_value = ast_xml_get_attribute(tmp, "name");
1118 ast_str_append(&syntax, 0, " matchfield: %s = %s", S_OR(attr_value, "Unknown"), text);
1119 ast_xml_free_attr(attr_value);
1121 }
1122 return ast_strdup(ast_str_buffer(syntax));
1123}
char * text
Definition: app_queue.c:1809
#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, and text.

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

1126{
1127 const char *type;
1128 const char *default_value;
1129 const char *regex;
1130 RAII_VAR(struct ast_str *, syntax, ast_str_create(128), ast_free);
1131
1132 if (!syntax || !fixnode) {
1133 return NULL;
1134 }
1135 type = ast_xml_get_attribute(fixnode, "type");
1136 default_value = ast_xml_get_attribute(fixnode, "default");
1137
1138 regex = ast_xml_get_attribute(fixnode, "regex");
1139 ast_str_set(&syntax, 0, "%s = [%s] (Default: %s) (Regex: %s)\n",
1140 name,
1141 type ?: "",
1142 default_value ?: "n/a",
1143 regex ?: "False");
1144
1146 ast_xml_free_attr(default_value);
1148
1149 return ast_strdup(ast_str_buffer(syntax));
1150}
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 637 of file xmldoc.c.

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

Referenced by _ast_xmldoc_build_syntax(), xmldoc_get_syntax_fun(), 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 1037 of file xmldoc.c.

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

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

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

References ARRAY_LEN, FUNCTION_SYNTAX, strsyntaxtype::stxtype, stxtype, and type.

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

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

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

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

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

610{
611 struct ast_xml_node *node = fixnode;
612 int i;
613
615 for (i = 0; i < ARRAY_LEN(special_tags); i++) {
616 if (!strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
617 return 1;
618 }
619 }
620 }
621 return 0;
622}
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_load_documentation()

static int xmldoc_load_documentation ( int  first_time)
static

Definition at line 3014 of file xmldoc.c.

3015{
3016 struct ast_xml_node *root_node;
3017 struct ast_xml_doc *tmpdoc;
3018 struct documentation_tree *doc_tree;
3019 char *xmlpattern;
3020 struct ast_config *cfg = NULL;
3021 struct ast_variable *var = NULL;
3022 struct ast_flags cnfflags = { 0 };
3023 int globret, i, dup, duplicate;
3024 glob_t globbuf;
3025#if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
3026 int xmlpattern_maxlen;
3027#endif
3028
3029 /* setup default XML documentation language */
3031
3032 if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
3033 for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
3034 if (!strcasecmp(var->name, "documentation_language")) {
3035 if (!ast_strlen_zero(var->value)) {
3036 snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
3037 }
3038 }
3039 }
3040 ast_config_destroy(cfg);
3041 }
3042
3043 if (first_time) {
3044 /* initialize the XML library. */
3045 ast_xml_init();
3048 /* register function to be run when asterisk finish. */
3050 }
3051
3052 globbuf.gl_offs = 0; /* slots to reserve in gl_pathv */
3053
3054#if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
3055 xmlpattern_maxlen = strlen(ast_config_AST_DATA_DIR) + strlen("/documentation/thirdparty") + strlen("/*-??_??.xml") + 1;
3056 xmlpattern = ast_malloc(xmlpattern_maxlen);
3057 globret = xml_pathmatch(xmlpattern, xmlpattern_maxlen, &globbuf);
3058#else
3059 /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
3060 if (ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
3062 return 1;
3063 }
3064 globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
3065#endif
3066
3067 ast_debug(3, "gl_pathc %zu\n", (size_t)globbuf.gl_pathc);
3068 if (globret == GLOB_NOSPACE) {
3069 ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
3070 ast_free(xmlpattern);
3071 return 1;
3072 } else if (globret == GLOB_ABORTED) {
3073 ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Read error\n", xmlpattern);
3074 ast_free(xmlpattern);
3075 return 1;
3076 }
3077 ast_free(xmlpattern);
3078
3080
3081 if (!first_time) {
3082 /* If we're reloading, purge the existing documentation.
3083 * We do this with the lock held so that if somebody
3084 * else tries to get documentation, there's no chance
3085 * of retrieiving it after we purged the old docs
3086 * but before we loaded the new ones. */
3088 }
3089
3090 /* loop over expanded files */
3091 for (i = 0; i < globbuf.gl_pathc; i++) {
3092 /* check for duplicates (if we already [try to] open the same file. */
3093 duplicate = 0;
3094 for (dup = 0; dup < i; dup++) {
3095 if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
3096 duplicate = 1;
3097 break;
3098 }
3099 }
3100 if (duplicate || strchr(globbuf.gl_pathv[i], '*')) {
3101 /* skip duplicates as well as pathnames not found
3102 * (due to use of GLOB_NOCHECK in xml_pathmatch) */
3103 continue;
3104 }
3105 tmpdoc = NULL;
3106 tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
3107 if (!tmpdoc) {
3108 ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
3109 continue;
3110 }
3111 /* Get doc root node and check if it starts with '<docs>' */
3112 root_node = ast_xml_get_root(tmpdoc);
3113 if (!root_node) {
3114 ast_log(LOG_ERROR, "Error getting documentation root node\n");
3115 ast_xml_close(tmpdoc);
3116 continue;
3117 }
3118 /* Check root node name for malformed xmls. */
3119 if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
3120 ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
3121 ast_xml_close(tmpdoc);
3122 continue;
3123 }
3124 doc_tree = ast_calloc(1, sizeof(*doc_tree));
3125 if (!doc_tree) {
3126 ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
3127 ast_xml_close(tmpdoc);
3128 continue;
3129 }
3130 doc_tree->doc = tmpdoc;
3131 doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
3132 AST_RWLIST_INSERT_TAIL(&xmldoc_tree, doc_tree, entry);
3133 }
3135
3136 globfree(&globbuf);
3137
3138 return 0;
3139}
#define GLOB_ABORTED
Definition: ael_lex.c:828
#define MY_GLOB_FLAGS
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
#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
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:3541
#define CONFIG_STATUS_FILEINVALID
void ast_config_destroy(struct ast_config *cfg)
Destroys a config.
Definition: extconf.c:1289
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 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
int ast_xml_init(void)
Initialize the XML library implementation. This function is used to setup everything needed to start ...
Definition: xml.c:48
struct ast_xml_doc * ast_xml_open(char *filename)
Open an XML document.
Definition: xml.c:94
static void xmldoc_purge_documentation(void)
Definition: xmldoc.c:2990
static const char default_documentation_language[]
Default documentation language.
Definition: xmldoc.c:44
static struct ast_cli_entry cli_dump_xmldocs
Definition: xmldoc.c:2984
static struct ast_cli_entry cli_reload_xmldocs
Definition: xmldoc.c:2987
static void xmldoc_unload_documentation(void)
Close and unload XML documentation.
Definition: xmldoc.c:3002

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, cli_reload_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, xmldoc_purge_documentation(), and xmldoc_unload_documentation().

Referenced by ast_xmldoc_load_documentation(), and xmldoc_reload_documentation().

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

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

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

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

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

1286{
1287 return (xmldoc_parse_para(node, tabs, posttabs, buffer)
1288 || xmldoc_parse_specialtags(node, tabs, posttabs, buffer)
1289 || xmldoc_parse_info(node, tabs, posttabs, buffer));
1290}
static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:2075
static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
Definition: xmldoc.c:1307

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

1822{
1823 struct ast_xml_node *node = fixnode;
1824 int ret = 0;
1825 char *optiontabs;
1826
1827 if (ast_asprintf(&optiontabs, "%s ", tabs) < 0) {
1828 return ret;
1829 }
1830
1832 if (xmldoc_parse_common_elements(node, (ret ? tabs : " - "), "\n", buffer)) {
1833 ret = 1;
1834 }
1835
1836 xmldoc_parse_enumlist(node, optiontabs, buffer);
1837 xmldoc_parse_parameter(node, optiontabs, buffer);
1838 }
1839
1840 ast_free(optiontabs);
1841
1842 return ret;
1843}

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

1857{
1858 struct ast_xml_node *node = fixnode;
1859 const char *enumname;
1860 int ret = 0;
1861
1863 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
1864 continue;
1865 }
1866
1867 enumname = ast_xml_get_attribute(node, "name");
1868 if (enumname) {
1869 ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
1870 ast_xml_free_attr(enumname);
1871
1872 /* parse only enum elements inside a enumlist node. */
1873 if ((xmldoc_parse_enum(node, tabs, buffer))) {
1874 ret = 1;
1875 } else {
1876 ast_str_append(buffer, 0, "\n");
1877 }
1878 }
1879 }
1880 return ret;
1881}
static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1821

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

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

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

2076{
2077 const char *tech;
2078 char *internaltabs;
2079 int internal_ret;
2080 int ret = 0;
2081
2082 if (strcasecmp(ast_xml_node_get_name(node), "info")) {
2083 return ret;
2084 }
2085
2086 ast_asprintf(&internaltabs, "%s ", tabs);
2087 if (!internaltabs) {
2088 return ret;
2089 }
2090
2091 tech = ast_xml_get_attribute(node, "tech");
2092 if (tech) {
2093 ast_str_append(buffer, 0, "%s<note>Technology: %s</note>\n", internaltabs, tech);
2094 ast_xml_free_attr(tech);
2095 }
2096
2097 ret = 1;
2098
2100 if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
2101 xmldoc_parse_enumlist(node, internaltabs, buffer);
2102 } else if (!strcasecmp(ast_xml_node_get_name(node), "parameter")) {
2103 xmldoc_parse_parameter(node, internaltabs, buffer);
2104 } else if ((internal_ret = xmldoc_parse_common_elements(node, internaltabs, posttabs, buffer))) {
2105 if (internal_ret > ret) {
2106 ret = internal_ret;
2107 }
2108 }
2109 }
2110 ast_free(internaltabs);
2111
2112 return ret;
2113}

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

1896{
1897 struct ast_xml_node *node;
1898 int ret = 0;
1899 char *optiontabs;
1900
1901 if (ast_asprintf(&optiontabs, "%s ", tabs) < 0) {
1902 return ret;
1903 }
1905 if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1906 /* if this is the first data appended to buffer, print a \n*/
1907 if (!ret && ast_xml_node_get_children(node)) {
1908 /* print \n */
1909 ast_str_append(buffer, 0, "\n");
1910 }
1911 if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
1912 ret = 1;
1913 }
1914 continue;
1915 }
1916
1917 if (xmldoc_parse_common_elements(node, (ret ? tabs : ""), "\n", buffer)) {
1918 ret = 1;
1919 }
1920
1921 xmldoc_parse_variablelist(node, optiontabs, buffer);
1922
1923 xmldoc_parse_enumlist(node, optiontabs, buffer);
1924 }
1925 ast_free(optiontabs);
1926
1927 return ret;
1928}
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:1474

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

1940{
1941 struct ast_xml_node *node;
1942 const char *optname, *hasparams;
1943 char *optionsyntax;
1944 int optparams;
1945
1947 /* Start appending every option tag. */
1948 if (strcasecmp(ast_xml_node_get_name(node), "option")) {
1949 continue;
1950 }
1951
1952 /* Get the option name. */
1953 optname = ast_xml_get_attribute(node, "name");
1954 if (!optname) {
1955 continue;
1956 }
1957
1958 optparams = 1;
1959 hasparams = ast_xml_get_attribute(node, "hasparams");
1960 if (hasparams && !strcasecmp(hasparams, "optional")) {
1961 optparams = 2;
1962 }
1963
1964 optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
1965 if (!optionsyntax) {
1966 ast_xml_free_attr(optname);
1967 ast_xml_free_attr(hasparams);
1968 continue;
1969 }
1970
1971 ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
1972
1973 if (!xmldoc_parse_option(node, tabs, buffer)) {
1974 ast_str_append(buffer, 0, "\n");
1975 }
1976 ast_str_append(buffer, 0, "\n");
1977 ast_xml_free_attr(optname);
1978 ast_xml_free_attr(hasparams);
1979 ast_free(optionsyntax);
1980 }
1981}
static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1895

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

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

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(), 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 1992 of file xmldoc.c.

1993{
1994 const char *paramname;
1995 struct ast_xml_node *node = fixnode;
1996 int hasarguments, printed = 0;
1997 char *internaltabs;
1998
1999 if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
2000 return;
2001 }
2002
2003 hasarguments = xmldoc_has_inside(node, "argument");
2004 if (!(paramname = ast_xml_get_attribute(node, "name"))) {
2005 /* parameter MUST have an attribute name. */
2006 return;
2007 }
2008
2009 if (ast_asprintf(&internaltabs, "%s ", tabs) < 0) {
2010 ast_xml_free_attr(paramname);
2011 return;
2012 }
2013
2014 if (!hasarguments && xmldoc_has_nodes(node)) {
2015 ast_str_append(buffer, 0, "%s\n", paramname);
2016 ast_xml_free_attr(paramname);
2017 printed = 1;
2018 }
2019
2021 if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
2022 xmldoc_parse_optionlist(node, internaltabs, buffer);
2023 } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
2024 xmldoc_parse_enumlist(node, internaltabs, buffer);
2025 } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
2026 xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? " " : ""), buffer);
2027 } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
2028 if (!printed) {
2029 ast_str_append(buffer, 0, "%s\n", paramname);
2030 ast_xml_free_attr(paramname);
2031 printed = 1;
2032 }
2033 if (xmldoc_parse_para(node, internaltabs, "\n", buffer)) {
2034 /* If anything ever goes in below this condition before the continue below,
2035 * we should probably continue immediately. */
2036 continue;
2037 }
2038 continue;
2039 } else if (!strcasecmp(ast_xml_node_get_name(node), "info")) {
2040 if (!printed) {
2041 ast_str_append(buffer, 0, "%s\n", paramname);
2042 ast_xml_free_attr(paramname);
2043 printed = 1;
2044 }
2045 if (xmldoc_parse_info(node, internaltabs, "\n", buffer)) {
2046 /* If anything ever goes in below this condition before the continue below,
2047 * we should probably continue immediately. */
2048 continue;
2049 }
2050 continue;
2051 } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
2052 continue;
2053 }
2054 }
2055 if (!printed) {
2056 ast_xml_free_attr(paramname);
2057 }
2058 ast_free(internaltabs);
2059}
static int xmldoc_has_nodes(struct ast_xml_node *fixnode)
Definition: xmldoc.c:588
static void xmldoc_parse_optionlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
Definition: xmldoc.c:1939

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

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

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

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

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(), 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 1582 of file xmldoc.c.

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

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(), 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 119 of file xmldoc.c.

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

Referenced by xmldoc_string_wrap().

◆ xmldoc_purge_documentation()

static void xmldoc_purge_documentation ( void  )
static
Note
Must be called with xmldoc_tree locked

Definition at line 2990 of file xmldoc.c.

2991{
2992 struct documentation_tree *doctree;
2993
2994 while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
2995 ast_free(doctree->filename);
2996 ast_xml_close(doctree->doc);
2997 ast_free(doctree);
2998 }
2999}
#define AST_RWLIST_REMOVE_HEAD
Definition: linkedlists.h:844

References ast_free, AST_RWLIST_REMOVE_HEAD, ast_xml_close(), documentation_tree::doc, and documentation_tree::filename.

Referenced by xmldoc_load_documentation(), and xmldoc_unload_documentation().

◆ xmldoc_reload_documentation()

static int xmldoc_reload_documentation ( void  )
static

Definition at line 3146 of file xmldoc.c.

3147{
3148 return xmldoc_load_documentation(0);
3149}

References xmldoc_load_documentation().

Referenced by handle_reload_docs().

◆ xmldoc_reverse_helper()

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

Definition at line 515 of file xmldoc.c.

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

Referenced by xmldoc_get_syntax_fun().

◆ xmldoc_setpostbr()

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

Definition at line 147 of file xmldoc.c.

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

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

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

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

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

References ast_free, ast_log, ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_truncate(), ast_strdup, ESC, LOG_WARNING, NULL, text, 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 3002 of file xmldoc.c.

3003{
3006
3010
3012}
int ast_cli_unregister(struct ast_cli_entry *e)
Unregisters a command or an array of commands.
Definition: main/cli.c:2439
int ast_xml_finish(void)
Cleanup library allocated global data.
Definition: xml.c:57

References ast_cli_unregister(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_xml_finish(), cli_dump_xmldocs, cli_reload_xmldocs, and xmldoc_purge_documentation().

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

Referenced by xmldoc_load_documentation(), and xmldoc_unload_documentation().

◆ cli_reload_xmldocs

struct ast_cli_entry cli_reload_xmldocs = { .handler = handle_reload_docs , .summary = "Reload the XML docs" ,}
static

Definition at line 2987 of file xmldoc.c.

Referenced by 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 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

Referenced by xmldoc_get_syntax_type().

◆ 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