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:

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...
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.
char *	ast_xmldoc_build_description (const char type, const char name, const char *module)
	Generate description documentation from XML.
struct ao2_container *	ast_xmldoc_build_documentation (const char *type)
	Build the documentation for a particular source type.
char *	ast_xmldoc_build_seealso (const char type, const char name, const char *module)
	Parse the <see-also> node content.
char *	ast_xmldoc_build_synopsis (const char type, const char name, const char *module)
	Generate synopsis documentation from XML.
char *	ast_xmldoc_build_syntax (const char type, const char name, const char *module)
	Get the syntax for a specified application or function.
char *	ast_xmldoc_printable (const char *bwinput, int withcolors)
	Colorize and put delimiters (instead of tags) to the xmldoc output.

Detailed Description

Asterisk XML Documentation API.

Definition in file xmldoc.h.

Enumeration Type Documentation

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

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

References _ast_xmldoc_build_arguments(), ast_strlen_zero(), ast_xml_node_get_children(), 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);
}

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 2091 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);
}

struct ao2_container* ast_xmldoc_build_documentation ( const char * type ) [read]

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

References ao2_container_alloc, ao2_link, ao2_t_ref, 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(), documentation_tree::doc, MANAGER_EVENT_SYNTAX, name, ast_xml_doc_item::next, xmldoc_build_documentation_item(), and xmldoc_get_syntax_type().

Referenced by __init_manager().

{
   struct ao2_container *docs;
   struct ast_xml_doc_item *item = NULL, *root = NULL;
   struct ast_xml_node *node = NULL, *instance = NULL;
   struct documentation_tree *doctree;
   const char *name;

   if (!(docs = ao2_container_alloc(127, ast_xml_doc_item_hash, ast_xml_doc_item_cmp))) {
      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)) {
         /* 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:
            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;
               }
               if (!item) {
                  item = temp;
                  root = item;
               } else {
                  item->next = temp;
                  item = temp;
               }
            }
            item = 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");
            item = NULL;
         }
      }
   }
   AST_RWLIST_UNLOCK(&xmldoc_tree);

   return docs;
}

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

References _ast_xmldoc_build_seealso(), ast_strlen_zero(), ast_xml_node_get_children(), 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;
}

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 2069 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);
}

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

References _ast_xmldoc_build_syntax(), 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);
}

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 319 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(), COLOR_CYAN, colorized_tags, len(), term_end(), and xmldoc_string_wrap().

Referenced by handle_cli_agi_show(), handle_manager_show_event(), handle_show_function(), handle_showmancmd(), print_app_docs(), 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", term_end());
      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, xmldoc_max_diff);

   ast_free(colorized);

   return wrapped;
}

Asterisk developer's documentation

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation