xmldoc.h File Reference

Asterisk XML Documentation API. More...

#include "asterisk/xml.h"
#include "asterisk/stringfields.h"
#include "asterisk/strings.h"

Include dependency graph for xmldoc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_xml_doc_item
	Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counted object. More...
struct	ast_xml_doc_item_list
	The struct to be used as the head of an ast_xml_doc_item list when being manipulated. More...

Enumerations
enum	ast_doc_src { AST_XML_DOC, AST_STATIC_DOC }
	From where the documentation come from, this structure is useful for use it inside application/functions/manager actions structure. More...

Functions
char *	ast_xmldoc_build_arguments (const char *type, const char *name, const char *module)
	Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name. More...
char *	ast_xmldoc_build_description (const char *type, const char *name, const char *module)
	Generate description documentation from XML. More...
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...
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...

Detailed Description

Asterisk XML Documentation API.

Definition in file xmldoc.h.

Enumeration Type Documentation

ast_doc_src

enum ast_doc_src

From where the documentation come from, this structure is useful for use it inside application/functions/manager actions structure.

Enumerator
AST_XML_DOC	From XML documentation
AST_STATIC_DOC	From application/function registration

Definition at line 30 of file xmldoc.h.

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

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

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

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

{
   struct ast_xml_node *node;

   if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
      return NULL;
   }

   node = xmldoc_get_node(type, name, module, documentation_language);

   if (!node || !ast_xml_node_get_children(node)) {
      return NULL;
   }

   return _ast_xmldoc_build_arguments(node);
}

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

References xmldoc_build_field().

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

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

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

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

Referenced by __init_manager(), and aco_init().

{
   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;
}

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

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

Referenced by ast_manager_register2().

{
   struct ast_xml_node *node;

   if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
      return NULL;
   }

   node = xmldoc_get_node(type, name, module, documentation_language);

   if (!node || !ast_xml_node_get_children(node)) {
      return NULL;
   }

   return xmldoc_build_final_response(node);
}

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

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

Referenced by ast_manager_register2().

{
   struct ast_xml_node *node;

   if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
      return NULL;
   }

   node = xmldoc_get_node(type, name, module, documentation_language);

   if (!node || !ast_xml_node_get_children(node)) {
      return NULL;
   }

   return xmldoc_build_list_responses(node);
}

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

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

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

{
   char *output;
   struct ast_xml_node *node;

   if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
      return NULL;
   }

   /* get the application/function root node. */
   node = xmldoc_get_node(type, name, module, documentation_language);
   if (!node || !ast_xml_node_get_children(node)) {
      return NULL;
   }

   output = _ast_xmldoc_build_seealso(node);

   return output;
}

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

References xmldoc_build_field().

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

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

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

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

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

{
   struct ast_xml_node *node;

   node = xmldoc_get_node(type, name, module, documentation_language);
   if (!node) {
      return NULL;
   }

   return _ast_xmldoc_build_syntax(node, type, name);
}

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

References ARRAY_LEN, ast_copy_string(), ast_free, ast_opt_light_background, ast_str_append(), ast_str_buffer(), ast_str_create, ast_term_color_code(), 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().

{
   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;
}

ast_xmldoc_query()

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

Execute an XPath query on the loaded XML documentation.

Parameters

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

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

{
   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;
}

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

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

Referenced by ast_xmldoc_build_documentation(), xmldoc_update_config_option(), and xmldoc_update_config_type().

{
   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;
}