xmldoc.c File Reference

XML Documentation API. More...

#include "asterisk.h"
#include "asterisk/_private.h"
#include "asterisk/paths.h"
#include "asterisk/linkedlists.h"
#include "asterisk/config.h"
#include "asterisk/term.h"
#include "asterisk/astobj2.h"
#include "asterisk/xmldoc.h"
#include "asterisk/cli.h"

Include dependency graph for xmldoc.c:

Go to the source code of this file.

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

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

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

Functions
static char *	_ast_xmldoc_build_arguments (struct ast_xml_node *node)
static char *	_ast_xmldoc_build_description (struct ast_xml_node *node)
static char *	_ast_xmldoc_build_seealso (struct ast_xml_node *node)
static char *	_ast_xmldoc_build_synopsis (struct ast_xml_node *node)
static char *	_ast_xmldoc_build_syntax (struct ast_xml_node *root_node, const char *type, const char *name)
static char *	_xmldoc_build_field (struct ast_xml_node *node, const char *var, int raw)
static struct ast_xml_doc_item *	ast_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_container *	ast_xmldoc_build_documentation (const char *type)
	Build the documentation for a particular source type. More...
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. More...
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. More...
char *	ast_xmldoc_build_seealso (const char *type, const char *name, const char *module)
	Parse the <see-also> node content. More...
char *	ast_xmldoc_build_synopsis (const char *type, const char *name, const char *module)
	Generate synopsis documentation from XML. More...
char *	ast_xmldoc_build_syntax (const char *type, const char *name, const char *module)
	Get the syntax for a specified application or function. More...
int	ast_xmldoc_load_documentation (void)
	Load XML documentation. Provided by xmldoc.c. More...
char *	ast_xmldoc_printable (const char *bwinput, int withcolors)
	Colorize and put delimiters (instead of tags) to the xmldoc output. More...
struct ast_xml_xpath_results *	ast_xmldoc_query (const char *fmt,...)
	Execute an XPath query on the loaded XML documentation. More...
int	ast_xmldoc_regenerate_doc_item (struct ast_xml_doc_item *item)
	Regenerate the documentation for a particular item. More...
static void	build_config_docs (struct ast_xml_node *cur, struct ast_xml_doc_item_list *root)
static char *	handle_dump_docs (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
static 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_item *	xmldoc_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_item *	xmldoc_build_final_response (struct ast_xml_node *manager_action)
static struct ast_xml_doc_item *	xmldoc_build_list_responses (struct ast_xml_node *manager_action)
static struct ast_str *	xmldoc_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.

                {
    FUNCTION_SYNTAX,
    MANAGER_SYNTAX,
    MANAGER_EVENT_SYNTAX,
    CONFIG_INFO_SYNTAX,
    CONFIG_FILE_SYNTAX,
    CONFIG_OPTION_SYNTAX,
    CONFIG_OBJECT_SYNTAX,
    COMMAND_SYNTAX
};

Function Documentation

_ast_xmldoc_build_arguments()

static char * _ast_xmldoc_build_arguments ( struct ast_xml_node *  node )

static

Definition at line 2044 of file xmldoc.c.

{
    char *retstr = NULL;
    struct ast_str *ret;
 
    ret = ast_str_create(128);
    if (!ret) {
        return NULL;
    }
 
    /* Find the syntax field. */
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
            break;
        }
    }
 
    if (!node || !ast_xml_node_get_children(node)) {
        /* We couldn't find the syntax node. */
        ast_free(ret);
        return NULL;
    }
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        xmldoc_parse_parameter(node, "", &ret);
    }
 
    if (ast_str_strlen(ret) > 0) {
        /* remove last '\n' */
        char *buf = ast_str_buffer(ret);
        if (buf[ast_str_strlen(ret) - 1] == '\n') {
            ast_str_truncate(ret, -1);
        }
        retstr = ast_strdup(ast_str_buffer(ret));
    }
    ast_free(ret);
 
    return retstr;
}

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

{
    return _xmldoc_build_field(node, "description", 0);
}

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.

{
    char *output;
    struct ast_str *outputstr;
    const char *typename;
    const char *content;
    int first = 1;
 
    /* Find the <see-also> node. */
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
            break;
        }
    }
 
    if (!node || !ast_xml_node_get_children(node)) {
        /* we couldnt find a <see-also> node. */
        return NULL;
    }
 
    /* prepare the output string. */
    outputstr = ast_str_create(128);
    if (!outputstr) {
        return NULL;
    }
 
    /* get into the <see-also> node. */
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
            continue;
        }
 
        /* parse the <ref> node. 'type' attribute is required. */
        typename = ast_xml_get_attribute(node, "type");
        if (!typename) {
            continue;
        }
        content = ast_xml_get_text(node);
        if (!content) {
            ast_xml_free_attr(typename);
            continue;
        }
        if (!strcasecmp(typename, "application")) {
            ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
        } else if (!strcasecmp(typename, "function")) {
            ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
        } else if (!strcasecmp(typename, "astcli")) {
            ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
        } else {
            ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
        }
        first = 0;
        ast_xml_free_text(content);
        ast_xml_free_attr(typename);
    }
 
    output = ast_strdup(ast_str_buffer(outputstr));
    ast_free(outputstr);
 
    return output;
}

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

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

_ast_xmldoc_build_synopsis()

static char * _ast_xmldoc_build_synopsis ( struct ast_xml_node *  node )

static

Definition at line 2243 of file xmldoc.c.

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

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.

{
    char *syntax = NULL;
    struct ast_xml_node *node = root_node;
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
            break;
        }
    }
 
    switch (xmldoc_get_syntax_type(type)) {
    case FUNCTION_SYNTAX:
        syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
        break;
    case COMMAND_SYNTAX:
        syntax = xmldoc_get_syntax_cmd(node, name, 1);
        break;
    case MANAGER_SYNTAX:
        syntax = xmldoc_get_syntax_manager(node, name, "Action");
        break;
    case MANAGER_EVENT_SYNTAX:
        syntax = xmldoc_get_syntax_manager(node, name, "Event");
        break;
    case CONFIG_OPTION_SYNTAX:
        syntax = xmldoc_get_syntax_config_option(root_node, name);
        break;
    case CONFIG_OBJECT_SYNTAX:
        syntax = xmldoc_get_syntax_config_object(node, name);
        break;
    default:
        syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
    }
 
    return syntax;
}

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

{
    char *ret = NULL;
    struct ast_str *formatted;
 
    node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
 
    if (!node || !ast_xml_node_get_children(node)) {
        return ret;
    }
 
    formatted = xmldoc_get_formatted(node, raw, raw);
    if (formatted && ast_str_strlen(formatted) > 0) {
        ret = ast_strdup(ast_str_buffer(formatted));
    }
    ast_free(formatted);
 
    return ret;
}

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

{
    struct ast_xml_doc_item *item;
 
    item = ao2_alloc_options(sizeof(*item), ast_xml_doc_item_destructor,
        AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!item) {
        ast_log(AST_LOG_ERROR, "Failed to allocate memory for ast_xml_doc_item instance\n");
        return NULL;
    }
 
    if (   !(item->syntax = ast_str_create(128))
        || !(item->seealso = ast_str_create(128))
        || !(item->arguments = ast_str_create(128))
        || !(item->synopsis = ast_str_create(128))
        || !(item->description = ast_str_create(128))) {
        ast_log(AST_LOG_ERROR, "Failed to allocate strings for ast_xml_doc_item instance\n");
        goto ast_xml_doc_item_failure;
    }
 
    if (ast_string_field_init(item, 64)) {
        ast_log(AST_LOG_ERROR, "Failed to initialize string field for ast_xml_doc_item instance\n");
        goto ast_xml_doc_item_failure;
    }
    ast_string_field_set(item, name, name);
    ast_string_field_set(item, type, type);
 
    return item;
 
ast_xml_doc_item_failure:
    ao2_ref(item, -1);
    return NULL;
}

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

{
    struct ast_xml_doc_item *left = obj;
    struct ast_xml_doc_item *right = arg;
    const char *match = (flags & OBJ_KEY) ? arg : right->name;
    return strcasecmp(left->name, match) ? 0 : (CMP_MATCH | CMP_STOP);
}

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

{
    struct ast_xml_doc_item *doc = obj;
 
    if (!doc) {
        return;
    }
 
    ast_free(doc->syntax);
    ast_free(doc->seealso);
    ast_free(doc->arguments);
    ast_free(doc->synopsis);
    ast_free(doc->description);
    ast_string_field_free_memory(doc);
 
    if (AST_LIST_NEXT(doc, next)) {
        ao2_ref(AST_LIST_NEXT(doc, next), -1);
        AST_LIST_NEXT(doc, next) = NULL;
    }
}

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

Referenced by ast_xml_doc_item_alloc().

ast_xml_doc_item_hash()

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

static

Definition at line 2349 of file xmldoc.c.

{
    const struct ast_xml_doc_item *item = obj;
    const char *name = (flags & OBJ_KEY) ? obj : item->name;
    return ast_str_case_hash(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' ?
name	Name of the application or function to build the 'arguments' tag.
module	The module the item is in (optional, can be NULL)

Return values

NULL	on error.
Output	buffer with the [arguments] tag content.

Definition at line 2084 of file xmldoc.c.

{
    struct ast_xml_node *node;
    char *arguments;
 
    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    node = xmldoc_get_node(type, name, module, documentation_language);
 
    if (!node || !ast_xml_node_get_children(node)) {
        AST_RWLIST_UNLOCK(&xmldoc_tree);
        return NULL;
    }
 
    arguments = _ast_xmldoc_build_arguments(node);
    AST_RWLIST_UNLOCK(&xmldoc_tree);
    return arguments;
}

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

type	The source of documentation (application, function, etc).
name	The name of the application, function, etc.
module	The module the item is in (optional, can be NULL)

Return values

NULL	on error.
A	malloc'ed string with the formatted description.

Definition at line 2271 of file xmldoc.c.

{
    return xmldoc_build_field(type, name, module, "description", 0);
}

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

type	The source of the documentation items (application, function, etc.)

Return values

NULL	on error
An	ao2_container populated with ast_xml_doc instances for each item that exists for the specified source type

Since

11

Definition at line 2684 of file xmldoc.c.

{
    struct ao2_container *docs;
    struct ast_xml_node *node = NULL, *instance = NULL;
    struct documentation_tree *doctree;
    const char *name;
 
    docs = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, 127,
        ast_xml_doc_item_hash, NULL, ast_xml_doc_item_cmp);
    if (!docs) {
        ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
        /* the core xml documents have priority over thirdparty document. */
        node = ast_xml_get_root(doctree->doc);
        if (!node) {
            break;
        }
 
        for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
            struct ast_xml_doc_item *item = NULL;
 
            /* Ignore empty nodes or nodes that aren't of the type requested */
            if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), type)) {
                continue;
            }
            name = ast_xml_get_attribute(node, "name");
            if (!name) {
                continue;
            }
 
            switch (xmldoc_get_syntax_type(type)) {
            case MANAGER_EVENT_SYNTAX:
            {
                struct ast_xml_doc_item_list root;
 
                AST_LIST_HEAD_INIT(&root);
                for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
                    struct ast_xml_doc_item *temp;
                    if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
                        continue;
                    }
                    temp = xmldoc_build_documentation_item(instance, name, type);
                    if (!temp) {
                        break;
                    }
                    AST_LIST_INSERT_TAIL(&root, temp, next);
                }
                item = AST_LIST_FIRST(&root);
                break;
            }
            case CONFIG_INFO_SYNTAX:
            {
                RAII_VAR(const char *, name, ast_xml_get_attribute(node, "name"), ast_xml_free_attr);
 
                if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), "configInfo")) {
                    break;
                }
 
                item = xmldoc_build_documentation_item(node, name, "configInfo");
                if (item) {
                    struct ast_xml_doc_item_list root;
 
                    AST_LIST_HEAD_INIT(&root);
                    AST_LIST_INSERT_TAIL(&root, item, next);
                    build_config_docs(node, &root);
                }
                break;
            }
            default:
                item = xmldoc_build_documentation_item(node, name, type);
            }
            ast_xml_free_attr(name);
 
            if (item) {
                ao2_link(docs, item);
                ao2_t_ref(item, -1, "Dispose of creation ref");
            }
        }
    }
    AST_RWLIST_UNLOCK(&xmldoc_tree);
 
    return docs;
}

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'
name	Name of the application or function to build the 'responses' tag.
module	The module the item is in (optional, can be NULL)

Returns

An XMLDoc item list with the [final response] tag content.

Since

13.0.0

Definition at line 2554 of file xmldoc.c.

{
    struct ast_xml_node *node;
    static struct ast_xml_doc_item *response;
 
    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    node = xmldoc_get_node(type, name, module, documentation_language);
 
    if (!node || !ast_xml_node_get_children(node)) {
        AST_RWLIST_UNLOCK(&xmldoc_tree);
        return NULL;
    }
 
    response = xmldoc_build_final_response(node);
    AST_RWLIST_UNLOCK(&xmldoc_tree);
    return response;
}

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'
name	Name of the application or function to build the 'responses' tag.
module	The module the item is in (optional, can be NULL)

Returns

An XMLDoc item list with the [list responses] tag content.

Since

13.0.0

Definition at line 2484 of file xmldoc.c.

{
    struct ast_xml_node *node;
    struct ast_xml_doc_item *responses;
 
    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    node = xmldoc_get_node(type, name, module, documentation_language);
 
    if (!node || !ast_xml_node_get_children(node)) {
        AST_RWLIST_UNLOCK(&xmldoc_tree);
        return NULL;
    }
 
    responses = xmldoc_build_list_responses(node);
    AST_RWLIST_UNLOCK(&xmldoc_tree);
    return responses;
}

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'.
name	Application or functions name.
module	The module the item is in (optional, can be NULL)

Return values

NULL	on error.
Content	of the see-also node.

Definition at line 1702 of file xmldoc.c.

{
    char *output;
    struct ast_xml_node *node;
 
    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
        return NULL;
    }
 
    /* get the application/function root node. */
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    node = xmldoc_get_node(type, name, module, documentation_language);
    if (!node || !ast_xml_node_get_children(node)) {
        AST_RWLIST_UNLOCK(&xmldoc_tree);
        return NULL;
    }
 
    output = _ast_xmldoc_build_seealso(node);
    AST_RWLIST_UNLOCK(&xmldoc_tree);
 
    return output;
}

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

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

Generate synopsis documentation from XML.

Parameters

type	The source of documentation (application, function, etc).
name	The name of the application, function, etc.
module	The module the item is in (optional, can be NULL)

Return values

NULL	on error.
A	malloc'ed string with the synopsis.

Definition at line 2248 of file xmldoc.c.

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

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

type	Application, Function or AGI ?
name	Name of the application or function.
module	The module the item is in (optional, can be NULL)

Return values

NULL	on error.
The	generated syntax in a ast_malloc'ed string.

Definition at line 1252 of file xmldoc.c.

{
    struct ast_xml_node *node;
    char *syntax;
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    node = xmldoc_get_node(type, name, module, documentation_language);
    if (!node) {
        AST_RWLIST_UNLOCK(&xmldoc_tree);
        return NULL;
    }
 
    syntax = _ast_xmldoc_build_syntax(node, type, name);
    AST_RWLIST_UNLOCK(&xmldoc_tree);
    return syntax;
}

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

1	on error.
0	on success.

Definition at line 3047 of file xmldoc.c.

{
    return xmldoc_load_documentation(1);
}

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

bwinput	Not colorized input with tags.
withcolors	Result output with colors.

Return values

NULL	on error.
New	malloced buffer colorized and with delimiters.

Definition at line 241 of file xmldoc.c.

{
    struct ast_str *colorized;
    char *wrapped = NULL;
    int i, c, len, colorsection;
    char *tmp;
    size_t bwinputlen;
    static const int base_fg = COLOR_CYAN;
 
    if (!bwinput) {
        return NULL;
    }
 
    bwinputlen = strlen(bwinput);
 
    if (!(colorized = ast_str_create(256))) {
        return NULL;
    }
 
    if (withcolors) {
        ast_term_color_code(&colorized, base_fg, 0);
        if (!colorized) {
            return NULL;
        }
    }
 
    for (i = 0; i < bwinputlen; i++) {
        colorsection = 0;
        /* Check if we are at the beginning of a tag to be colorized. */
        for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
            if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
                continue;
            }
 
            if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
                continue;
            }
 
            len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
 
            /* Setup color */
            if (withcolors) {
                if (ast_opt_light_background) {
                    /* Turn off *bright* colors */
                    ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
                } else {
                    /* Turn on *bright* colors */
                    ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
                }
                if (!colorized) {
                    return NULL;
                }
            }
 
            /* copy initial string replace */
            ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
            if (!colorized) {
                return NULL;
            }
            {
                char buf[len + 1];
                ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
                ast_str_append(&colorized, 0, "%s", buf);
            }
            if (!colorized) {
                return NULL;
            }
 
            /* copy the ending string replace */
            ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
            if (!colorized) {
                return NULL;
            }
 
            /* Continue with the last color. */
            if (withcolors) {
                ast_term_color_code(&colorized, base_fg, 0);
                if (!colorized) {
                    return NULL;
                }
            }
 
            i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
            colorsection = 1;
            break;
        }
 
        if (!colorsection) {
            ast_str_append(&colorized, 0, "%c", bwinput[i]);
            if (!colorized) {
                return NULL;
            }
        }
    }
 
    if (withcolors) {
        ast_str_append(&colorized, 0, "%s", ast_term_reset());
        if (!colorized) {
            return NULL;
        }
    }
 
    /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
    wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns);
 
    ast_free(colorized);
 
    return wrapped;
}

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

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

ast_xmldoc_query()

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

Execute an XPath query on the loaded XML documentation.

Parameters

fmt	The XPath query string to execute
...	Variable printf style format arguments

Return values

An	XPath results object on success
NULL	if no match found

Since

12

Definition at line 2576 of file xmldoc.c.

{
    struct ast_xml_xpath_results *results = NULL;
    struct documentation_tree *doctree;
    RAII_VAR(struct ast_str *, xpath_str, ast_str_create(128), ast_free);
    va_list ap;
    int res;
 
    if (!xpath_str) {
        return NULL;
    }
 
    va_start(ap, fmt);
    res = ast_str_set_va(&xpath_str, 0, fmt, ap);
    va_end(ap);
    if (res == AST_DYNSTR_BUILD_FAILED) {
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
        if (!(results = ast_xml_query(doctree->doc, ast_str_buffer(xpath_str)))) {
            continue;
        }
        break;
    }
    AST_RWLIST_UNLOCK(&xmldoc_tree);
 
    return results;
}

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

item	The documentation item to regenerate

Return values

-1	on error
0	on success

Since

12

Definition at line 2635 of file xmldoc.c.

{
    const char *name;
    char *syntax;
    char *seealso;
    char *arguments;
    char *synopsis;
    char *description;
 
    if (!item || !item->node) {
        return -1;
    }
 
    name = ast_xml_get_attribute(item->node, "name");
    if (!name) {
        return -1;
    }
 
    syntax = _ast_xmldoc_build_syntax(item->node, item->type, name);
    seealso = _ast_xmldoc_build_seealso(item->node);
    arguments = _ast_xmldoc_build_arguments(item->node);
    synopsis = _ast_xmldoc_build_synopsis(item->node);
    description = _ast_xmldoc_build_description(item->node);
 
    if (syntax) {
        ast_str_set(&item->syntax, 0, "%s", syntax);
    }
    if (seealso) {
        ast_str_set(&item->seealso, 0, "%s", seealso);
    }
    if (arguments) {
        ast_str_set(&item->arguments, 0, "%s", arguments);
    }
    if (synopsis) {
        ast_str_set(&item->synopsis, 0, "%s", synopsis);
    }
    if (description) {
        ast_str_set(&item->description, 0, "%s", description);
    }
 
    ast_free(syntax);
    ast_free(seealso);
    ast_free(arguments);
    ast_free(synopsis);
    ast_free(description);
    ast_xml_free_attr(name);
    return 0;
}

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

{
    struct ast_xml_node *iter;
    struct ast_xml_doc_item *item;
 
    for (iter = ast_xml_node_get_children(cur); iter; iter = ast_xml_node_get_next(iter)) {
        const char *iter_name;
        if (strncasecmp(ast_xml_node_get_name(iter), "config", 6)) {
            continue;
        }
        iter_name = ast_xml_get_attribute(iter, "name");
        /* Now add all of the child config-related items to the list */
        if (!(item = xmldoc_build_documentation_item(iter, iter_name, ast_xml_node_get_name(iter)))) {
            ast_log(LOG_ERROR, "Could not build documentation for '%s:%s'\n", ast_xml_node_get_name(iter), iter_name);
            ast_xml_free_attr(iter_name);
            break;
        }
        ast_xml_free_attr(iter_name);
        if (!strcasecmp(ast_xml_node_get_name(iter), "configOption")) {
            const char *name = ast_xml_get_attribute(cur, "name");
            ast_string_field_set(item, ref, name);
            ast_xml_free_attr(name);
        }
        AST_LIST_INSERT_TAIL(root, item, next);
        build_config_docs(iter, root);
    }
}

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

{
    struct documentation_tree *doctree;
    struct ast_xml_doc *dumpdoc;
    struct ast_xml_node *dumproot;
    FILE *f;
 
    switch (cmd) {
    case CLI_INIT:
        e->command = "xmldoc dump";
        e->usage =
            "Usage: xmldoc dump <filename>\n"
            "  Dump XML documentation to a file\n";
        return NULL;
    case CLI_GENERATE:
        return NULL;
    }
 
    if (a->argc != 3) {
        return CLI_SHOWUSAGE;
    }
 
    dumpdoc = ast_xml_new();
    if (!dumpdoc) {
        ast_log(LOG_ERROR, "Could not create new XML document\n");
        return CLI_FAILURE;
    }
 
    dumproot = ast_xml_new_node("docs");
    if (!dumproot) {
        ast_xml_close(dumpdoc);
        ast_log(LOG_ERROR, "Could not create new XML root node\n");
        return CLI_FAILURE;
    }
 
    ast_xml_set_root(dumpdoc, dumproot);
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
        struct ast_xml_node *root_node = ast_xml_get_root(doctree->doc);
        struct ast_xml_node *kids = ast_xml_node_get_children(root_node);
        struct ast_xml_node *kids_copy;
 
        /* If there are no kids someone screwed up, but we check anyway. */
        if (!kids) {
            continue;
        }
 
        kids_copy = ast_xml_copy_node_list(kids);
        if (!kids_copy) {
            ast_xml_close(dumpdoc);
            ast_log(LOG_ERROR, "Could not create copy of XML node list\n");
            return CLI_FAILURE;
        }
 
        ast_xml_add_child_list(dumproot, kids_copy);
    }
    AST_RWLIST_UNLOCK(&xmldoc_tree);
 
    if (!(f = fopen(a->argv[2], "w"))) {
        ast_xml_close(dumpdoc);
        ast_log(LOG_ERROR, "Could not open file '%s': %s\n", a->argv[2], strerror(errno));
        return CLI_FAILURE;
    }
 
    ast_xml_doc_dump_file(f, dumpdoc);
    ast_xml_close(dumpdoc);
 
    fclose(f);
    return CLI_SUCCESS;
}

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

{
    switch (cmd) {
    case CLI_INIT:
        e->command = "xmldoc reload";
        e->usage =
            "Usage: xmldoc reload\n"
            "  Reload XML documentation\n";
        return NULL;
    case CLI_GENERATE:
        return NULL;
    }
 
    xmldoc_reload_documentation();
    return CLI_SUCCESS;
}

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.

{
    const char *attr_value = ast_xml_get_attribute(node, attr);
    int match = attr_value && !strcmp(attr_value, value);
    ast_xml_free_attr(attr_value);
    return match;
}

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

{
    struct ast_xml_doc_item *item;
    char *syntax;
    char *seealso;
    char *arguments;
    char *synopsis;
    char *description;
 
    if (!(item = ast_xml_doc_item_alloc(name, type))) {
        return NULL;
    }
    item->node = node;
 
    syntax = _ast_xmldoc_build_syntax(node, type, name);
    seealso = _ast_xmldoc_build_seealso(node);
    arguments = _ast_xmldoc_build_arguments(node);
    synopsis = _ast_xmldoc_build_synopsis(node);
    description = _ast_xmldoc_build_description(node);
 
    if (syntax) {
        ast_str_set(&item->syntax, 0, "%s", syntax);
    }
    if (seealso) {
        ast_str_set(&item->seealso, 0, "%s", seealso);
    }
    if (arguments) {
        ast_str_set(&item->arguments, 0, "%s", arguments);
    }
    if (synopsis) {
        ast_str_set(&item->synopsis, 0, "%s", synopsis);
    }
    if (description) {
        ast_str_set(&item->description, 0, "%s", description);
    }
 
    ast_free(syntax);
    ast_free(seealso);
    ast_free(arguments);
    ast_free(synopsis);
    ast_free(description);
 
    return item;
}

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

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

xmldoc_build_field()

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

static

Definition at line 2204 of file xmldoc.c.

{
    struct ast_xml_node *node;
    char *field;
 
    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
        ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&xmldoc_tree);
    node = xmldoc_get_node(type, name, module, documentation_language);
 
    if (!node) {
        AST_RWLIST_UNLOCK(&xmldoc_tree);
        ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation"
            " If this module was recently built, run 'xmldoc reload' to refresh documentation\n",
            type, name);
        return NULL;
    }
 
    field = _xmldoc_build_field(node, var, raw);
    AST_RWLIST_UNLOCK(&xmldoc_tree);
    return field;
}

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

{
    struct ast_xml_node *responses;
    struct ast_xml_node *final_response_event;
    struct ast_xml_node *event_instance;
 
    responses = ast_xml_find_element(ast_xml_node_get_children(manager_action),
        "responses", NULL, NULL);
    if (!responses) {
        return NULL;
    }
 
    final_response_event = ast_xml_find_element(ast_xml_node_get_children(responses),
        "managerEvent", NULL, NULL);
    if (!final_response_event) {
        return NULL;
    }
 
    event_instance = ast_xml_find_element(ast_xml_node_get_children(final_response_event),
        "managerEventInstance", NULL, NULL);
    if (!event_instance) {
        return NULL;
    } else {
        const char *name;
        struct ast_xml_doc_item *res;
 
        name = ast_xml_get_attribute(final_response_event, "name");
        res = xmldoc_build_documentation_item(event_instance, name, "managerEvent");
        ast_xml_free_attr(name);
        return res;
    }
 
}

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

{
    struct ast_xml_node *event;
    struct ast_xml_node *responses;
    struct ast_xml_node *list_elements;
    struct ast_xml_doc_item_list root;
 
    AST_LIST_HEAD_INIT(&root);
 
    responses = ast_xml_find_element(ast_xml_node_get_children(manager_action), "responses", NULL, NULL);
    if (!responses) {
        return NULL;
    }
 
    list_elements = ast_xml_find_element(ast_xml_node_get_children(responses), "list-elements", NULL, NULL);
    if (!list_elements) {
        return NULL;
    }
 
    /* Iterate over managerEvent nodes */
    for (event = ast_xml_node_get_children(list_elements); event; event = ast_xml_node_get_next(event)) {
        struct ast_xml_node *event_instance;
        RAII_VAR(const char *, name, ast_xml_get_attribute(event, "name"),
            ast_xml_free_attr);
        struct ast_xml_doc_item *new_item;
 
        if (!name || strcmp(ast_xml_node_get_name(event), "managerEvent")) {
            continue;
        }
 
        event_instance = ast_xml_find_element(ast_xml_node_get_children(event),
            "managerEventInstance", NULL, NULL);
        new_item = xmldoc_build_documentation_item(event_instance, name, "managerEvent");
        if (!new_item) {
            ao2_cleanup(AST_LIST_FIRST(&root));
            return NULL;
        }
 
        AST_LIST_INSERT_TAIL(&root, new_item, next);
    }
 
    return AST_LIST_FIRST(&root);
}

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

{
    struct ast_xml_node *tmp;
    const char *notcleanret, *tmpstr;
    struct ast_str *ret;
 
    if (raw_output) {
        /* xmldoc_string_cleanup will allocate the ret object */
        notcleanret = ast_xml_get_text(node);
        tmpstr = notcleanret;
        xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0, 0);
        ast_xml_free_text(tmpstr);
    } else {
        ret = ast_str_create(128);
        if (!ret) {
            return NULL;
        }
        for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
            /* if found, parse children elements. */
            if (xmldoc_parse_common_elements(tmp, "", "\n", &ret)) {
                continue;
            }
            if (xmldoc_parse_variablelist(tmp, "", &ret)) {
                continue;
            }
            if (xmldoc_parse_enumlist(tmp, "    ", &ret)) {
                continue;
            }
            if (xmldoc_parse_specialtags(tmp, "", "", &ret)) {
                continue;
            }
        }
        /* remove last '\n' */
        /* XXX Don't modify ast_str internals manually */
        tmpstr = ast_str_buffer(ret);
        if (tmpstr[ast_str_strlen(ret) - 1] == '\n') {
            ast_str_truncate(ret, -1);
        }
    }
    return ret;
}

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

Referenced by _xmldoc_build_field().

xmldoc_get_node()

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

static

Definition at line 435 of file xmldoc.c.

{
    struct ast_xml_node *node = NULL;
    struct ast_xml_node *first_match = NULL;
    struct ast_xml_node *lang_match = NULL;
    struct documentation_tree *doctree;
 
    AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
        /* the core xml documents have priority over thirdparty document. */
        node = ast_xml_get_root(doctree->doc);
        if (!node) {
            break;
        }
 
        node = ast_xml_node_get_children(node);
        while ((node = ast_xml_find_element(node, type, "name", name))) {
            if (!ast_xml_node_get_children(node)) {
                /* ignore empty nodes */
                node = ast_xml_node_get_next(node);
                continue;
            }
 
            if (!first_match) {
                first_match = node;
            }
 
            /* Check language */
            if (xmldoc_attribute_match(node, "language", language)) {
                if (!lang_match) {
                    lang_match = node;
                }
 
                /* if module is empty we have a match */
                if (ast_strlen_zero(module)) {
                    break;
                }
 
                /* Check module */
                if (xmldoc_attribute_match(node, "module", module)) {
                    break;
                }
            }
 
            node = ast_xml_node_get_next(node);
        }
 
        /* if we matched lang and module return this match */
        if (node) {
            break;
        }
 
        /* we didn't match lang and module, just return the first
         * result with a matching language if we have one */
        if (lang_match) {
            node = lang_match;
            break;
        }
 
        /* we didn't match with only the language, just return the
         * first match */
        if (first_match) {
            node = first_match;
            break;
        }
    }
 
    return node;
}

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

{
    struct ast_str *syntax;
    struct ast_xml_node *tmpnode, *node = fixnode;
    char *ret, *paramname;
    const char *paramtype, *attrname, *literal;
    int required, isenum, first = 1, isliteral;
 
    if (!fixnode) {
        return NULL;
    }
 
    syntax = ast_str_create(128);
    if (!syntax) {
        /* at least try to return something... */
        return ast_strdup(name);
    }
 
    /* append name to output string. */
    if (printname) {
        ast_str_append(&syntax, 0, "%s", name);
        first = 0;
    }
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
            continue;
        }
 
        if (xmldoc_has_inside(node, "parameter")) {
            /* is this a recursive parameter. */
            paramname = xmldoc_get_syntax_cmd(node, "", 0);
            isenum = 1;
        } else {
            for (tmpnode = ast_xml_node_get_children(node); tmpnode; tmpnode = ast_xml_node_get_next(tmpnode)) {
                if (!strcasecmp(ast_xml_node_get_name(tmpnode), "enumlist")) {
                    break;
                }
            }
            if (tmpnode) {
                /* parse enumlist (note that this is a special enumlist
                that is used to describe a syntax like {<param1>|<param2>|...} */
                paramname = xmldoc_parse_cmd_enumlist(tmpnode);
                isenum = 1;
            } else {
                /* this is a simple parameter. */
                attrname = ast_xml_get_attribute(node, "name");
                if (!attrname) {
                    /* ignore this bogus parameter and continue. */
                    continue;
                }
                paramname = ast_strdup(attrname);
                ast_xml_free_attr(attrname);
                isenum = 0;
            }
        }
 
        /* Is this parameter required? */
        required = 0;
        paramtype = ast_xml_get_attribute(node, "required");
        if (paramtype) {
            required = ast_true(paramtype);
            ast_xml_free_attr(paramtype);
        }
 
        /* Is this a replaceable value or a fixed parameter value? */
        isliteral = 0;
        literal = ast_xml_get_attribute(node, "literal");
        if (literal) {
            isliteral = ast_true(literal);
            ast_xml_free_attr(literal);
        }
 
        /* if required="false" print with [...].
         * if literal="true" or is enum print without <..>.
         * if not first print a space at the beginning.
         */
        ast_str_append(&syntax, 0, "%s%s%s%s%s%s",
                (first ? "" : " "),
                (required ? "" : "["),
                (isenum || isliteral ? "" : "<"),
                paramname,
                (isenum || isliteral ? "" : ">"),
                (required ? "" : "]"));
        first = 0;
        ast_free(paramname);
    }
 
    /* return a common string. */
    ret = ast_strdup(ast_str_buffer(syntax));
    ast_free(syntax);
 
    return ret;
}

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.

{
    struct ast_xml_node *matchinfo, *tmp;
    int match;
    const char *attr_value;
    const char *text;
    RAII_VAR(struct ast_str *, syntax, ast_str_create(128), ast_free);
 
    if (!syntax || !fixnode) {
        return NULL;
    }
    if (!(matchinfo = ast_xml_find_element(ast_xml_node_get_children(fixnode), "matchInfo", NULL, NULL))) {
        return NULL;
    }
    if (!(tmp  = ast_xml_find_element(ast_xml_node_get_children(matchinfo), "category", NULL, NULL))) {
        return NULL;
    }
    attr_value = ast_xml_get_attribute(tmp, "match");
    if (attr_value) {
        match = ast_true(attr_value);
        text = ast_xml_get_text(tmp);
        ast_str_set(&syntax, 0, "category %s /%s/", match ? "=~" : "!~", text);
        ast_xml_free_attr(attr_value);
        ast_xml_free_text(text);
    }
 
    if ((tmp = ast_xml_find_element(ast_xml_node_get_children(matchinfo), "field", NULL, NULL))) {
        text = ast_xml_get_text(tmp);
        attr_value = ast_xml_get_attribute(tmp, "name");
        ast_str_append(&syntax, 0, " matchfield: %s = %s", S_OR(attr_value, "Unknown"), text);
        ast_xml_free_attr(attr_value);
        ast_xml_free_text(text);
    }
    return ast_strdup(ast_str_buffer(syntax));
}

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

Referenced by _ast_xmldoc_build_syntax().

xmldoc_get_syntax_config_option()

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

static

Definition at line 1125 of file xmldoc.c.

{
    const char *type;
    const char *default_value;
    const char *regex;
    RAII_VAR(struct ast_str *, syntax, ast_str_create(128), ast_free);
 
    if (!syntax || !fixnode) {
        return NULL;
    }
    type = ast_xml_get_attribute(fixnode, "type");
    default_value = ast_xml_get_attribute(fixnode, "default");
 
    regex = ast_xml_get_attribute(fixnode, "regex");
    ast_str_set(&syntax, 0, "%s = [%s] (Default: %s) (Regex: %s)\n",
        name,
        type ?: "",
        default_value ?: "n/a",
        regex ?: "False");
 
    ast_xml_free_attr(type);
    ast_xml_free_attr(default_value);
    ast_xml_free_attr(regex);
 
    return ast_strdup(ast_str_buffer(syntax));
}

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.

{
#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 : ""))
    struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
    const char *paramtype, *multipletype, *paramnameattr, *attrargsep, *parenthesis, *argname;
    int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
    int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis, multiple;
    char *syntax = NULL, *argsep, *paramname;
 
    if (ast_strlen_zero(rootname) || ast_strlen_zero(childname)) {
        ast_log(LOG_WARNING, "Tried to look in XML tree with faulty rootname or childname while creating a syntax.\n");
        return NULL;
    }
 
    if (!rootnode || !ast_xml_node_get_children(rootnode)) {
        /* If the rootnode field is not found, at least print name. */
        if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
            syntax = NULL;
        }
        return syntax;
    }
 
    /* Get the argument separator from the root node attribute name 'argsep', if not found
    defaults to ','. */
    attrargsep = ast_xml_get_attribute(rootnode, "argsep");
    if (attrargsep) {
        argsep = ast_strdupa(attrargsep);
        ast_xml_free_attr(attrargsep);
    } else {
        argsep = ast_strdupa(",");
    }
 
    /* Get order of evaluation. */
    for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), childname)) {
            continue;
        }
        required = 0;
        hasparams = 1;
        if ((paramtype = ast_xml_get_attribute(node, "required"))) {
            if (ast_true(paramtype)) {
                required = 1;
            }
            ast_xml_free_attr(paramtype);
        }
 
        lastparam = node;
        reqlanode = required;
 
        if (!firstparam) {
            /* first parameter node */
            firstparam = node;
            reqfinode = required;
        }
    }
 
    if (!hasparams) {
        /* This application, function, option, etc, doesn't have any params. */
        if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
            syntax = NULL;
        }
        return syntax;
    }
 
    if (reqfinode && reqlanode) {
        /* check midnode */
        for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
            if (strcasecmp(ast_xml_node_get_name(node), childname)) {
                continue;
            }
            if (node != firstparam && node != lastparam) {
                if ((paramtype = ast_xml_get_attribute(node, "required"))) {
                    if (!ast_true(paramtype)) {
                        optmidnode = 1;
                        ast_xml_free_attr(paramtype);
                        break;
                    }
                    ast_xml_free_attr(paramtype);
                }
            }
        }
    }
 
    if ((!reqfinode && reqlanode) || (reqfinode && reqlanode && optmidnode)) {
        reverse = 1;
        node = lastparam;
    } else {
        reverse = 0;
        node = firstparam;
    }
 
    /* init syntax string. */
    if (reverse) {
        xmldoc_reverse_helper(reverse, &len, &syntax,
            (printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
    } else {
        xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
            (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
    }
 
    for (; node; node = GOTONEXT(reverse, node)) {
        if (strcasecmp(ast_xml_node_get_name(node), childname)) {
            continue;
        }
 
        /* Get the argument name, if it is not the leaf, go inside that parameter. */
        if (xmldoc_has_inside(node, "argument")) {
            parenthesis = ast_xml_get_attribute(node, "hasparams");
            prnparenthesis = 0;
            if (parenthesis) {
                prnparenthesis = ast_true(parenthesis);
                if (!strcasecmp(parenthesis, "optional")) {
                    prnparenthesis = 2;
                }
                ast_xml_free_attr(parenthesis);
            }
            argname = ast_xml_get_attribute(node, "name");
            if (argname) {
                paramname = xmldoc_get_syntax_fun(node, argname, "argument", prnparenthesis, prnparenthesis);
                ast_xml_free_attr(argname);
            } else {
                /* Malformed XML, print **UNKOWN** */
                paramname = ast_strdup("**unknown**");
            }
        } else {
            paramnameattr = ast_xml_get_attribute(node, "name");
            if (!paramnameattr) {
                ast_log(LOG_WARNING, "Malformed XML %s: no %s name\n", rootname, childname);
                if (syntax) {
                    /* Free already allocated syntax */
                    ast_free(syntax);
                }
                /* to give up is ok? */
                if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
                    syntax = NULL;
                }
                return syntax;
            }
            paramname = ast_strdup(paramnameattr);
            ast_xml_free_attr(paramnameattr);
        }
 
        if (!paramname) {
            return NULL;
        }
 
        /* Defaults to 'false'. */
        multiple = 0;
        if ((multipletype = ast_xml_get_attribute(node, "multiple"))) {
            if (ast_true(multipletype)) {
                multiple = 1;
            }
            ast_xml_free_attr(multipletype);
        }
 
        required = 0;   /* Defaults to 'false'. */
        if ((paramtype = ast_xml_get_attribute(node, "required"))) {
            if (ast_true(paramtype)) {
                required = 1;
            }
            ast_xml_free_attr(paramtype);
        }
 
        /* build syntax core. */
 
        if (required) {
            /* First parameter */
            if (!paramcount) {
                xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
            } else {
                /* Time to close open brackets. */
                while (openbrackets > 0) {
                    xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
                    openbrackets--;
                }
                if (reverse) {
                    xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", paramname, argsep);
                } else {
                    xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", argsep, paramname);
                }
                xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s", MP("["), MP(argsep), MP("...]"));
            }
        } else {
            /* First parameter */
            if (!paramcount) {
                xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]", paramname, MP("["), MP(argsep), MP("...]"));
            } else {
                if (ISLAST(reverse, node)) {
                    /* This is the last parameter. */
                    if (reverse) {
                        xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]%s", paramname,
                                    MP("["), MP(argsep), MP("...]"), argsep);
                    } else {
                        xmldoc_reverse_helper(reverse, &len, &syntax, "%s[%s%s%s%s]", argsep, paramname,
                                    MP("["), MP(argsep), MP("...]"));
                    }
                } else {
                    if (reverse) {
                        xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s%s]", paramname, argsep,
                                    MP("["), MP(argsep), MP("...]"));
                    } else {
                        xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s%s", argsep, paramname,
                                    MP("["), MP(argsep), MP("...]"));
                    }
                    openbrackets++;
                }
            }
        }
        ast_free(paramname);
 
        paramcount++;
    }
 
    /* Time to close open brackets. */
    while (openbrackets > 0) {
        xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
        openbrackets--;
    }
 
    /* close syntax string. */
    if (reverse) {
        xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
            (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
    } else {
        xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
    }
 
    return syntax;
#undef ISLAST
#undef GOTONEXT
#undef MP
}

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.

{
    struct ast_str *syntax;
    struct ast_xml_node *node = fixnode;
    const char *paramtype, *attrname;
    int required;
    char *ret;
 
    if (!fixnode) {
        return NULL;
    }
 
    syntax = ast_str_create(128);
    if (!syntax) {
        return ast_strdup(name);
    }
 
    ast_str_append(&syntax, 0, "%s: %s", manager_type, name);
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
            continue;
        }
 
        /* Is this parameter required? */
        required = !strcasecmp(manager_type, "event") ? 1 : 0;
        paramtype = ast_xml_get_attribute(node, "required");
        if (paramtype) {
            required = ast_true(paramtype);
            ast_xml_free_attr(paramtype);
        }
 
        attrname = ast_xml_get_attribute(node, "name");
        if (!attrname) {
            /* ignore this bogus parameter and continue. */
            continue;
        }
 
        ast_str_append(&syntax, 0, "\n%s%s:%s <value>",
            (required ? "" : "["),
            attrname,
            (required ? "" : "]"));
        ast_xml_free_attr(attrname);
    }
 
    /* return a common string. */
    ret = ast_strdup(ast_str_buffer(syntax));
    ast_free(syntax);
 
    return ret;
}

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.

{
    int i;
    for (i=0; i < ARRAY_LEN(stxtype); i++) {
        if (!strcasecmp(stxtype[i].type, type)) {
            return stxtype[i].stxtype;
        }
    }
 
    return FUNCTION_SYNTAX;
}

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.

{
    struct ast_xml_node *node = fixnode;
 
    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), what)) {
            return 1;
        }
    }
    return 0;
}

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.

{
    struct ast_xml_node *node = fixnode;
 
    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), "text")) {
            return 1;
        }
    }
    return 0;
}

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.

{
    struct ast_xml_node *node = fixnode;
    int i;
 
    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
        for (i = 0; i < ARRAY_LEN(special_tags); i++) {
            if (!strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
                return 1;
            }
        }
    }
    return 0;
}

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

{
    struct ast_xml_node *root_node;
    struct ast_xml_doc *tmpdoc;
    struct documentation_tree *doc_tree;
    char *xmlpattern;
    struct ast_config *cfg = NULL;
    struct ast_variable *var = NULL;
    struct ast_flags cnfflags = { 0 };
    int globret, i, dup, duplicate;
    glob_t globbuf;
#if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
    int xmlpattern_maxlen;
#endif
 
    /* setup default XML documentation language */
    snprintf(documentation_language, sizeof(documentation_language), default_documentation_language);
 
    if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
        for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
            if (!strcasecmp(var->name, "documentation_language")) {
                if (!ast_strlen_zero(var->value)) {
                    snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
                }
            }
        }
        ast_config_destroy(cfg);
    }
 
    if (first_time) {
        /* initialize the XML library. */
        ast_xml_init();
        ast_cli_register(&cli_dump_xmldocs);
        ast_cli_register(&cli_reload_xmldocs);
        /* register function to be run when asterisk finish. */
        ast_register_cleanup(xmldoc_unload_documentation);
    }
 
    globbuf.gl_offs = 0;    /* slots to reserve in gl_pathv */
 
#if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
    xmlpattern_maxlen = strlen(ast_config_AST_DATA_DIR) + strlen("/documentation/thirdparty") + strlen("/*-??_??.xml") + 1;
    xmlpattern = ast_malloc(xmlpattern_maxlen);
    globret = xml_pathmatch(xmlpattern, xmlpattern_maxlen, &globbuf);
#else
    /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
    if (ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
        documentation_language, documentation_language, default_documentation_language) < 0) {
        return 1;
    }
    globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
#endif
 
    ast_debug(3, "gl_pathc %zu\n", (size_t)globbuf.gl_pathc);
    if (globret == GLOB_NOSPACE) {
        ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
        ast_free(xmlpattern);
        return 1;
    } else if (globret  == GLOB_ABORTED) {
        ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Read error\n", xmlpattern);
        ast_free(xmlpattern);
        return 1;
    }
    ast_free(xmlpattern);
 
    AST_RWLIST_WRLOCK(&xmldoc_tree);
 
    if (!first_time) {
        /* If we're reloading, purge the existing documentation.
         * We do this with the lock held so that if somebody
         * else tries to get documentation, there's no chance
         * of retrieiving it after we purged the old docs
         * but before we loaded the new ones. */
        xmldoc_purge_documentation();
    }
 
    /* loop over expanded files */
    for (i = 0; i < globbuf.gl_pathc; i++) {
        /* check for duplicates (if we already [try to] open the same file. */
        duplicate = 0;
        for (dup = 0; dup < i; dup++) {
            if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
                duplicate = 1;
                break;
            }
        }
        if (duplicate || strchr(globbuf.gl_pathv[i], '*')) {
        /* skip duplicates as well as pathnames not found
         * (due to use of GLOB_NOCHECK in xml_pathmatch) */
            continue;
        }
        tmpdoc = NULL;
        tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
        if (!tmpdoc) {
            ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
            continue;
        }
        /* Get doc root node and check if it starts with '<docs>' */
        root_node = ast_xml_get_root(tmpdoc);
        if (!root_node) {
            ast_log(LOG_ERROR, "Error getting documentation root node\n");
            ast_xml_close(tmpdoc);
            continue;
        }
        /* Check root node name for malformed xmls. */
        if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
            ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
            ast_xml_close(tmpdoc);
            continue;
        }
        doc_tree = ast_calloc(1, sizeof(*doc_tree));
        if (!doc_tree) {
            ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
            ast_xml_close(tmpdoc);
            continue;
        }
        doc_tree->doc = tmpdoc;
        doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
        AST_RWLIST_INSERT_TAIL(&xmldoc_tree, doc_tree, entry);
    }
    AST_RWLIST_UNLOCK(&xmldoc_tree);
 
    globfree(&globbuf);
 
    return 0;
}

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.

{
    struct ast_xml_node *node = fixnode;
    const char *argname;
    int count = 0, ret = 0;
 
    if (!node || !ast_xml_node_get_children(node)) {
        return ret;
    }
 
    /* Print the argument names */
    argname = ast_xml_get_attribute(node, "name");
    if (!argname) {
        return 0;
    }
    if (xmldoc_has_inside(node, "para") || xmldoc_has_inside(node, "info") || xmldoc_has_specialtags(node)) {
        ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
        ast_xml_free_attr(argname);
    } else {
        ast_xml_free_attr(argname);
        return 0;
    }
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (xmldoc_parse_common_elements(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
            count++;
            ret = 1;
        }
    }
 
    return ret;
}

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.

{
    struct ast_xml_node *node = fixnode;
    struct ast_str *paramname;
    char *enumname, *ret;
    int first = 1;
 
    paramname = ast_str_create(128);
    if (!paramname) {
        return ast_strdup("{<unkown>}");
    }
 
    ast_str_append(&paramname, 0, "{");
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
            continue;
        }
 
        enumname = xmldoc_get_syntax_cmd(node, "", 0);
        if (!enumname) {
            continue;
        }
        if (!first) {
            ast_str_append(&paramname, 0, "|");
        }
        ast_str_append(&paramname, 0, "%s", enumname);
        first = 0;
        ast_free(enumname);
    }
 
    ast_str_append(&paramname, 0, "}");
 
    ret = ast_strdup(ast_str_buffer(paramname));
    ast_free(paramname);
 
    return ret;
}

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.

{
    return (xmldoc_parse_para(node, tabs, posttabs, buffer)
        || xmldoc_parse_specialtags(node, tabs, posttabs, buffer)
        || xmldoc_parse_info(node, tabs, posttabs, buffer));
}

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

{
    struct ast_xml_node *node = fixnode;
    int ret = 0;
    char *optiontabs;
 
    if (ast_asprintf(&optiontabs, "%s    ", tabs) < 0) {
        return ret;
    }
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (xmldoc_parse_common_elements(node, (ret ? tabs : " - "), "\n", buffer)) {
            ret = 1;
        }
 
        xmldoc_parse_enumlist(node, optiontabs, buffer);
        xmldoc_parse_parameter(node, optiontabs, buffer);
    }
 
    ast_free(optiontabs);
 
    return ret;
}

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

{
    struct ast_xml_node *node = fixnode;
    const char *enumname;
    int ret = 0;
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
            continue;
        }
 
        enumname = ast_xml_get_attribute(node, "name");
        if (enumname) {
            ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
            ast_xml_free_attr(enumname);
 
            /* parse only enum elements inside a enumlist node. */
            if ((xmldoc_parse_enum(node, tabs, buffer))) {
                ret = 1;
            } else {
                ast_str_append(buffer, 0, "\n");
            }
        }
    }
    return ret;
}

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.

{
    struct ast_xml_node *node = fixnode;
    const char *tmptext;
    const char *title;
    struct ast_str *stripped_text;
    int ret = 0;
 
    if (!node || !ast_xml_node_get_children(node)) {
        return ret;
    }
 
    if (strcasecmp(ast_xml_node_get_name(node), "example")) {
        return ret;
    }
 
    ret = 1;
 
    title = ast_xml_get_attribute(node, "title");
    if (title) {
        ast_str_append(buffer, 0, "%s", title);
        ast_xml_free_attr(title);
    }
    ast_str_append(buffer, 0, "\n");
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        tmptext = ast_xml_get_text(node);
        if (tmptext) {
            xmldoc_string_cleanup(tmptext, &stripped_text, 0, 1);
            if (stripped_text) {
                ast_str_append(buffer, 0, "<exampletext>%s</exampletext>\n", ast_str_buffer(stripped_text));
                ast_xml_free_text(tmptext);
                ast_free(stripped_text);
            }
        }
    }
 
    return ret;
}

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

{
    const char *tech;
    char *internaltabs;
    int internal_ret;
    int ret = 0;
 
    if (strcasecmp(ast_xml_node_get_name(node), "info")) {
        return ret;
    }
 
    ast_asprintf(&internaltabs, "%s    ", tabs);
    if (!internaltabs) {
        return ret;
    }
 
    tech = ast_xml_get_attribute(node, "tech");
    if (tech) {
        ast_str_append(buffer, 0, "%s<note>Technology: %s</note>\n", internaltabs, tech);
        ast_xml_free_attr(tech);
    }
 
    ret = 1;
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
            xmldoc_parse_enumlist(node, internaltabs, buffer);
        } else if (!strcasecmp(ast_xml_node_get_name(node), "parameter")) {
            xmldoc_parse_parameter(node, internaltabs, buffer);
        } else if ((internal_ret = xmldoc_parse_common_elements(node, internaltabs, posttabs, buffer))) {
            if (internal_ret > ret) {
                ret = internal_ret;
            }
        }
    }
    ast_free(internaltabs);
 
    return ret;
}

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

{
    struct ast_xml_node *node;
    int ret = 0;
    char *optiontabs;
 
    if (ast_asprintf(&optiontabs, "%s    ", tabs) < 0) {
        return ret;
    }
    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
            /* if this is the first data appended to buffer, print a \n*/
            if (!ret && ast_xml_node_get_children(node)) {
                /* print \n */
                ast_str_append(buffer, 0, "\n");
            }
            if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
                ret = 1;
            }
            continue;
        }
 
        if (xmldoc_parse_common_elements(node, (ret ? tabs :  ""), "\n", buffer)) {
            ret = 1;
        }
 
        xmldoc_parse_variablelist(node, optiontabs, buffer);
 
        xmldoc_parse_enumlist(node, optiontabs, buffer);
    }
    ast_free(optiontabs);
 
    return ret;
}

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

{
    struct ast_xml_node *node;
    const char *optname, *hasparams;
    char *optionsyntax;
    int optparams;
 
    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
        /* Start appending every option tag. */
        if (strcasecmp(ast_xml_node_get_name(node), "option")) {
            continue;
        }
 
        /* Get the option name. */
        optname = ast_xml_get_attribute(node, "name");
        if (!optname) {
            continue;
        }
 
        optparams = 1;
        hasparams = ast_xml_get_attribute(node, "hasparams");
        if (hasparams && !strcasecmp(hasparams, "optional")) {
            optparams = 2;
        }
 
        optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
        if (!optionsyntax) {
            ast_xml_free_attr(optname);
            ast_xml_free_attr(hasparams);
            continue;
        }
 
        ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
 
        if (!xmldoc_parse_option(node, tabs, buffer)) {
            ast_str_append(buffer, 0, "\n");
        }
        ast_str_append(buffer, 0, "\n");
        ast_xml_free_attr(optname);
        ast_xml_free_attr(hasparams);
        ast_free(optionsyntax);
    }
}

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.

{
    const char *tmptext;
    struct ast_xml_node *tmp;
    int ret = 0;
    struct ast_str *tmpstr;
 
    if (!node || !ast_xml_node_get_children(node)) {
        return ret;
    }
 
    if (strcasecmp(ast_xml_node_get_name(node), "para")) {
        return ret;
    }
 
    ast_str_append(buffer, 0, "%s", tabs);
 
    ret = 1;
 
    for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
        /* Get the text inside the <para> element and append it to buffer. */
        tmptext = ast_xml_get_text(tmp);
        if (tmptext) {
            /* Strip \n etc. */
            xmldoc_string_cleanup(tmptext, &tmpstr, 0, 0);
            ast_xml_free_text(tmptext);
            if (tmpstr) {
                if (strcasecmp(ast_xml_node_get_name(tmp), "text")) {
                    ast_str_append(buffer, 0, "<%s>%s</%s>", ast_xml_node_get_name(tmp),
                            ast_str_buffer(tmpstr), ast_xml_node_get_name(tmp));
                } else {
                    ast_str_append(buffer, 0, "%s", ast_str_buffer(tmpstr));
                }
                ast_free(tmpstr);
                ret = 2;
            }
        }
    }
 
    ast_str_append(buffer, 0, "%s", posttabs);
 
    return ret;
}

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

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

xmldoc_parse_parameter()

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

static

Definition at line 1907 of file xmldoc.c.

{
    const char *paramname;
    struct ast_xml_node *node = fixnode;
    int hasarguments, printed = 0;
    char *internaltabs;
 
    if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
        return;
    }
 
    hasarguments = xmldoc_has_inside(node, "argument");
    if (!(paramname = ast_xml_get_attribute(node, "name"))) {
        /* parameter MUST have an attribute name. */
        return;
    }
 
    if (ast_asprintf(&internaltabs, "%s    ", tabs) < 0) {
        ast_xml_free_attr(paramname);
        return;
    }
 
    if (!hasarguments && xmldoc_has_nodes(node)) {
        ast_str_append(buffer, 0, "%s\n", paramname);
        ast_xml_free_attr(paramname);
        printed = 1;
    }
 
    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
        if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
            xmldoc_parse_optionlist(node, internaltabs, buffer);
        } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
            xmldoc_parse_enumlist(node, internaltabs, buffer);
        } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
            xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? "        " : ""), buffer);
        } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
            if (!printed) {
                ast_str_append(buffer, 0, "%s\n", paramname);
                ast_xml_free_attr(paramname);
                printed = 1;
            }
            if (xmldoc_parse_para(node, internaltabs, "\n", buffer)) {
                /* If anything ever goes in below this condition before the continue below,
                 * we should probably continue immediately. */
                continue;
            }
            continue;
        } else if (!strcasecmp(ast_xml_node_get_name(node), "info")) {
            if (!printed) {
                ast_str_append(buffer, 0, "%s\n", paramname);
                ast_xml_free_attr(paramname);
                printed = 1;
            }
            if (xmldoc_parse_info(node, internaltabs, "\n", buffer)) {
                /* If anything ever goes in below this condition before the continue below,
                 * we should probably continue immediately. */
                continue;
            }
            continue;
        } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
            continue;
        }
    }
    if (!printed) {
        ast_xml_free_attr(paramname);
    }
    ast_free(internaltabs);
}

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.

{
    struct ast_xml_node *node = fixnode;
    int ret = 0, i;
 
    if (!node || !ast_xml_node_get_children(node)) {
        return ret;
    }
 
    for (i = 0; i < ARRAY_LEN(special_tags); i++) {
        if (strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
            continue;
        }
 
        ret = 1;
        /* This is a special tag. */
 
        /* concat data */
        if (!ast_strlen_zero(special_tags[i].init)) {
            ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init);
        }
 
        if (xmldoc_parse_example(node, buffer)) {
            ret = 1;
            break;
        }
 
        /* parse <para> elements inside special tags. */
        for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
            /* first <para> just print it without tabs at the begining. */
            if ((xmldoc_parse_para(node, "", posttabs, buffer) == 2)
                || (xmldoc_parse_info(node, "", posttabs, buffer) == 2)) {
                ret = 2;
            }
        }
 
        if (!ast_strlen_zero(special_tags[i].end)) {
            ast_str_append(buffer, 0, "%s%s", special_tags[i].end, posttabs);
        }
 
        break;
    }
 
    return ret;
}

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.

{
    struct ast_xml_node *tmp;
    const char *valname;
    const char *tmptext;
    struct ast_str *cleanstr;
    int ret = 0, printedpara=0;
 
    for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
        if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
            printedpara = 1;
            continue;
        }
 
        if (strcasecmp(ast_xml_node_get_name(tmp), "value")) {
            continue;
        }
 
        /* Parse a <value> tag only. */
        if (!printedpara) {
            ast_str_append(buffer, 0, "\n");
            printedpara = 1;
        }
        /* Parse each <value name='valuename'>desciption</value> */
        valname = ast_xml_get_attribute(tmp, "name");
        if (valname) {
            ret = 1;
            ast_str_append(buffer, 0, "%s<value>%s</value>", tabs, valname);
            ast_xml_free_attr(valname);
        }
        tmptext = ast_xml_get_text(tmp);
        /* Check inside this node for any explanation about its meaning. */
        if (tmptext) {
            /* Cleanup text. */
            xmldoc_string_cleanup(tmptext, &cleanstr, 1, 0);
            ast_xml_free_text(tmptext);
            if (cleanstr && ast_str_strlen(cleanstr) > 0) {
                ast_str_append(buffer, 0, ":%s", ast_str_buffer(cleanstr));
            }
            ast_free(cleanstr);
        }
        ast_str_append(buffer, 0, "\n");
    }
 
    return ret;
}

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

Referenced by xmldoc_parse_variablelist().

xmldoc_parse_variablelist()

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

static

Definition at line 1582 of file xmldoc.c.

{
    struct ast_xml_node *tmp;
    const char *varname;
    char *vartabs;
    int ret = 0;
 
    if (!node || !ast_xml_node_get_children(node)) {
        return ret;
    }
 
    if (strcasecmp(ast_xml_node_get_name(node), "variablelist")) {
        return ret;
    }
 
    /* use this spacing (add 4 spaces) inside a variablelist node. */
    if (ast_asprintf(&vartabs, "%s    ", tabs) < 0) {
        return ret;
    }
    for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
        /* We can have a <para> element inside the variable list */
        if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
            ret = 1;
            continue;
        }
 
        if (!strcasecmp(ast_xml_node_get_name(tmp), "variable")) {
            /* Store the variable name in buffer. */
            varname = ast_xml_get_attribute(tmp, "name");
            if (varname) {
                ast_str_append(buffer, 0, "%s<variable>%s</variable>: ", tabs, varname);
                ast_xml_free_attr(varname);
                /* Parse the <variable> possible values. */
                xmldoc_parse_variable(tmp, vartabs, buffer);
                ret = 1;
            }
        }
    }
 
    ast_free(vartabs);
 
    return ret;
}

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

Referenced by xmldoc_get_formatted(), and xmldoc_parse_option().

xmldoc_postbrlen()

static int xmldoc_postbrlen ( const char *  postbr )

static

Definition at line 119 of file xmldoc.c.

{
    int postbrreallen = 0, i;
    size_t postbrlen;
 
    if (!postbr) {
        return 0;
    }
    postbrlen = strlen(postbr);
    for (i = 0; i < postbrlen; i++) {
        if (postbr[i] == '\t') {
            postbrreallen += 8 - (postbrreallen % 8);
        } else {
            postbrreallen++;
        }
    }
    return postbrreallen;
}

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

{
    struct documentation_tree *doctree;
 
    while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
        ast_free(doctree->filename);
        ast_xml_close(doctree->doc);
        ast_free(doctree);
    }
}

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

{
    return xmldoc_load_documentation(0);
}

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.

{
    int totlen;
    int tmpfmtlen;
    char *tmpfmt;
    char *new_syntax;
    char tmp;
    va_list ap;
 
    va_start(ap, fmt);
    if (ast_vasprintf(&tmpfmt, fmt, ap) < 0) {
        va_end(ap);
        return;
    }
    va_end(ap);
 
    tmpfmtlen = strlen(tmpfmt);
    totlen = *len + tmpfmtlen + 1;
 
    new_syntax = ast_realloc(*syntax, totlen);
    if (!new_syntax) {
        ast_free(tmpfmt);
        return;
    }
    *syntax = new_syntax;
 
    if (reverse) {
        memmove(*syntax + tmpfmtlen, *syntax, *len);
        /* Save this char, it will be overwritten by the \0 of strcpy. */
        tmp = (*syntax)[0];
        strcpy(*syntax, tmpfmt);
        /* Restore the already saved char. */
        (*syntax)[tmpfmtlen] = tmp;
        (*syntax)[totlen - 1] = '\0';
    } else {
        strcpy(*syntax + *len, tmpfmt);
    }
 
    *len = totlen - 1;
    ast_free(tmpfmt);
}

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

Referenced by xmldoc_get_syntax_fun().

xmldoc_setpostbr()

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

static

Definition at line 147 of file xmldoc.c.

{
    int c, postbrlen = 0;
 
    if (!text) {
        return;
    }
 
    for (c = 0; c < len; c++) {
        if (text[c] == '\t' || text[c] == ' ') {
            postbr[postbrlen++] = text[c];
        } else {
            break;
        }
    }
    postbr[postbrlen] = '\0';
}

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.

{
    int i;
    size_t textlen;
 
    if (!text) {
        *output = NULL;
        return;
    }
 
    textlen = strlen(text);
 
    *output = ast_str_create(textlen);
    if (!(*output)) {
        ast_log(LOG_ERROR, "Problem allocating output buffer\n");
        return;
    }
 
    for (i = 0; i < textlen; i++) {
        if (text[i] == '\n' || text[i] == '\r') {
            if (maintain_newlines) {
                ast_str_append(output, 0, "%c", text[i]);
            }
            /* remove spaces/tabs/\n after a \n. */
            while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') {
                i++;
            }
            ast_str_append(output, 0, " ");
            continue;
        } else {
            ast_str_append(output, 0, "%c", text[i]);
        }
    }
 
    /* remove last spaces (we don't want always to remove the trailing spaces). */
    if (lastspaces) {
        ast_str_trim_blanks(*output);
    }
}

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.

{
    struct ast_str *tmp;
    char *ret, postbr[160];
    int count, i, textlen, postbrlen, lastbreak;
 
    /* sanity check */
    if (!text || columns <= 0) {
        ast_log(LOG_WARNING, "Passing wrong arguments while trying to wrap the text\n");
        return NULL;
    }
 
    tmp = ast_str_create(strlen(text) * 3);
 
    if (!tmp) {
        return NULL;
    }
 
    /* Check for blanks and tabs and put them in postbr. */
    xmldoc_setpostbr(postbr, sizeof(postbr), text);
    postbrlen = xmldoc_postbrlen(postbr);
 
    count = 0;
    lastbreak = 0;
 
    textlen = strlen(text);
    for (i = 0; i < textlen; i++) {
        if (text[i] == '\n') {
            xmldoc_setpostbr(postbr, sizeof(postbr), &text[i] + 1);
            postbrlen = xmldoc_postbrlen(postbr);
            count = 0;
            lastbreak = 0;
        } else if (text[i] == ESC) {
            /* Walk over escape sequences without counting them. */
            do {
                ast_str_append(&tmp, 0, "%c", text[i]);
                i++;
            } while (i < textlen && text[i] != 'm');
        } else {
            if (text[i] == ' ') {
                lastbreak = i;
            }
            count++;
        }
 
        if (count > columns) {
            /* Seek backwards if it was at most 30 characters ago. */
            int back = i - lastbreak;
            if (lastbreak && back > 0 && back < 30) {
                ast_str_truncate(tmp, -back);
                i = lastbreak; /* go back a bit */
            }
            ast_str_append(&tmp, 0, "\n%s", postbr);
            count = postbrlen;
            lastbreak = 0;
        } else {
            ast_str_append(&tmp, 0, "%c", text[i]);
        }
    }
 
    ret = ast_strdup(ast_str_buffer(tmp));
    ast_free(tmp);
 
    return ret;
}

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

Referenced by ast_xmldoc_printable().

xmldoc_unload_documentation()

static void xmldoc_unload_documentation ( void  )

static

Close and unload XML documentation.

Definition at line 2908 of file xmldoc.c.

{
    ast_cli_unregister(&cli_reload_xmldocs);
    ast_cli_unregister(&cli_dump_xmldocs);
 
    AST_RWLIST_WRLOCK(&xmldoc_tree);
    xmldoc_purge_documentation();
    AST_RWLIST_UNLOCK(&xmldoc_tree);
 
    ast_xml_finish();
}

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 2890 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 2893 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

XML documentation language.

Definition at line 51 of file xmldoc.c.

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

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