Asterisk - The Open Source Telephony Project
21.4.1
|
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"
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. | |
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. | |
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. | |
static char | documentation_language [6] |
XML documentation language. | |
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. | |
static struct xmldoc_tree | xmldoc_tree = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , } |
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.
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) |
NULL | on error. |
Output | buffer with the [arguments] tag content. |
Definition at line 2084 of file xmldoc.c.
References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.
Referenced by ast_manager_register2(), and ast_register_application2().
char* ast_xmldoc_build_description | ( | const char * | type, |
const char * | name, | ||
const char * | module | ||
) |
Generate description documentation from XML.
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) |
NULL | on error. |
A | malloc'ed string with the formatted description. |
Definition at line 2271 of file xmldoc.c.
Referenced by ast_manager_register2(), and ast_register_application2().
struct ao2_container* ast_xmldoc_build_documentation | ( | const char * | type | ) |
Build the documentation for a particular source type.
type | The source of the documentation items (application, function, etc.) |
NULL | on error |
An | ao2_container populated with ast_xml_doc instances for each item that exists for the specified source type |
Definition at line 2684 of file xmldoc.c.
References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_link, AST_LIST_FIRST, AST_LIST_HEAD_INIT, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, 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(), documentation_tree::doc, and RAII_VAR.
Referenced by aco_init().
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.
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) |
Definition at line 2554 of file xmldoc.c.
References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.
Referenced by ast_manager_register2().
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.
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) |
Definition at line 2484 of file xmldoc.c.
References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.
Referenced by ast_manager_register2().
char* ast_xmldoc_build_seealso | ( | const char * | type, |
const char * | name, | ||
const char * | module | ||
) |
Parse the <see-also> node content.
type | 'application', 'function' or 'agi'. |
name | Application or functions name. |
module | The module the item is in (optional, can be NULL) |
NULL | on error. |
Content | of the see-also node. |
Definition at line 1702 of file xmldoc.c.
References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.
Referenced by ast_manager_register2(), and ast_register_application2().
char* ast_xmldoc_build_synopsis | ( | const char * | type, |
const char * | name, | ||
const char * | module | ||
) |
Generate synopsis documentation from XML.
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) |
NULL | on error. |
A | malloc'ed string with the synopsis. |
Definition at line 2248 of file xmldoc.c.
Referenced by ast_manager_register2(), and ast_register_application2().
char* ast_xmldoc_build_syntax | ( | const char * | type, |
const char * | name, | ||
const char * | module | ||
) |
Get the syntax for a specified application or function.
type | Application, Function or AGI ? |
name | Name of the application or function. |
module | The module the item is in (optional, can be NULL) |
NULL | on error. |
The | generated syntax in a ast_malloc'ed string. |
Definition at line 1252 of file xmldoc.c.
References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and documentation_language.
Referenced by ast_manager_register2(), and ast_register_application2().
int ast_xmldoc_load_documentation | ( | void | ) |
char* ast_xmldoc_printable | ( | const char * | bwinput, |
int | withcolors | ||
) |
Colorize and put delimiters (instead of tags) to the xmldoc output.
bwinput | Not colorized input with tags. |
withcolors | Result output with colors. |
NULL | on error. |
New | malloced buffer colorized and with delimiters. |
Definition at line 241 of file xmldoc.c.
References ast_copy_string(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_term_color_code(), ast_term_reset(), and xmldoc_text_columns.
struct ast_xml_xpath_results* ast_xmldoc_query | ( | const char * | fmt, |
... | |||
) |
Execute an XPath query on the loaded XML documentation.
fmt | The XPath query string to execute |
... | Variable printf style format arguments |
An | XPath results object on success |
NULL | if no match found |
Definition at line 2576 of file xmldoc.c.
References AST_DYNSTR_BUILD_FAILED, 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, and RAII_VAR.
Referenced by load_modules().
int ast_xmldoc_regenerate_doc_item | ( | struct ast_xml_doc_item * | item | ) |
Regenerate the documentation for a particular item.
item | The documentation item to regenerate |
-1 | on error |
0 | on success |
Definition at line 2635 of file xmldoc.c.
References ast_xml_doc_item::arguments, ast_str_set(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_doc_item::description, ast_xml_doc_item::name, ast_xml_doc_item::node, ast_xml_doc_item::seealso, ast_xml_doc_item::synopsis, ast_xml_doc_item::syntax, and ast_xml_doc_item::type.
|
static |
Definition at line 2896 of file xmldoc.c.
References ast_xml_close(), documentation_tree::doc, and documentation_tree::filename.
Referenced by xmldoc_unload_documentation().
|
static |