xmldoc.h File Reference

Asterisk XML Documentation API. More...

#include "asterisk/xml.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.

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

References ast_free, ast_str_buffer(), ast_str_create(), ast_str_strlen(), ast_str_truncate(), ast_strdup, ast_strlen_zero(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_get_node(), and xmldoc_parse_parameter().

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

{
   struct ast_xml_node *node;
   struct ast_str *ret = ast_str_create(128);
   char *retstr = NULL;

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

   /* 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. */
      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;
}

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

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

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_strdup, ast_strlen_zero(), 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 xmldoc_get_node().

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

{
   struct ast_str *outputstr;
   char *output;
   struct ast_xml_node *node;
   const char *typename;
   const char *content;
   int first = 1;

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

   /* 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;
}

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

References ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), COMMAND_SYNTAX, FUNCTION_SYNTAX, MANAGER_SYNTAX, xmldoc_get_node(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_fun(), xmldoc_get_syntax_manager(), and xmldoc_get_syntax_type().

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

{
   struct ast_xml_node *node;
   char *syntax = NULL;

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

   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) {
      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);
         break;
      default:
         syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
      }
   }
   return syntax;
}

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

References ARRAY_LEN, ast_copy_string(), ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_term_color_code(), COLOR_CYAN, colorized_tags, len(), strcasestr(), term_end(), and xmldoc_string_wrap().

Referenced by handle_cli_agi_show(), 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) {
            ast_term_color_code(&colorized, colorized_tags[c].colorfg, 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;
}