Wed Jan 27 20:02:51 2016

Asterisk developer's documentation


xmldoc.h File Reference

Asterisk XML Documentation API. More...

#include "asterisk/xml.h"

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

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.

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


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

01762 {
01763    struct ast_xml_node *node;
01764    struct ast_str *ret = ast_str_create(128);
01765    char *retstr = NULL;
01766 
01767    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
01768       ast_free(ret);
01769       return NULL;
01770    }
01771 
01772    node = xmldoc_get_node(type, name, module, documentation_language);
01773 
01774    if (!node || !ast_xml_node_get_children(node)) {
01775       ast_free(ret);
01776       return NULL;
01777    }
01778 
01779    /* Find the syntax field. */
01780    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01781       if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
01782          break;
01783       }
01784    }
01785 
01786    if (!node || !ast_xml_node_get_children(node)) {
01787       /* We couldn't find the syntax node. */
01788       ast_free(ret);
01789       return NULL;
01790    }
01791 
01792    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01793       xmldoc_parse_parameter(node, "", &ret);
01794    }
01795 
01796    if (ast_str_strlen(ret) > 0) {
01797       /* remove last '\n' */
01798       char *buf = ast_str_buffer(ret);
01799       if (buf[ast_str_strlen(ret) - 1] == '\n') {
01800          ast_str_truncate(ret, -1);
01801       }
01802       retstr = ast_strdup(ast_str_buffer(ret));
01803    }
01804    ast_free(ret);
01805 
01806    return retstr;
01807 }

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

References xmldoc_build_field().

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

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

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

01462 {
01463    struct ast_str *outputstr;
01464    char *output;
01465    struct ast_xml_node *node;
01466    const char *typename;
01467    const char *content;
01468    int first = 1;
01469 
01470    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
01471       return NULL;
01472    }
01473 
01474    /* get the application/function root node. */
01475    node = xmldoc_get_node(type, name, module, documentation_language);
01476    if (!node || !ast_xml_node_get_children(node)) {
01477       return NULL;
01478    }
01479 
01480    /* Find the <see-also> node. */
01481    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01482       if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
01483          break;
01484       }
01485    }
01486 
01487    if (!node || !ast_xml_node_get_children(node)) {
01488       /* we couldnt find a <see-also> node. */
01489       return NULL;
01490    }
01491 
01492    /* prepare the output string. */
01493    outputstr = ast_str_create(128);
01494    if (!outputstr) {
01495       return NULL;
01496    }
01497 
01498    /* get into the <see-also> node. */
01499    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01500       if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
01501          continue;
01502       }
01503 
01504       /* parse the <ref> node. 'type' attribute is required. */
01505       typename = ast_xml_get_attribute(node, "type");
01506       if (!typename) {
01507          continue;
01508       }
01509       content = ast_xml_get_text(node);
01510       if (!content) {
01511          ast_xml_free_attr(typename);
01512          continue;
01513       }
01514       if (!strcasecmp(typename, "application")) {
01515          ast_str_append(&outputstr, 0, "%s%s()",   (first ? "" : ", "), content);
01516       } else if (!strcasecmp(typename, "function")) {
01517          ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
01518       } else if (!strcasecmp(typename, "astcli")) {
01519          ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
01520       } else {
01521          ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
01522       }
01523       first = 0;
01524       ast_xml_free_text(content);
01525       ast_xml_free_attr(typename);
01526    }
01527 
01528    output = ast_strdup(ast_str_buffer(outputstr));
01529    ast_free(outputstr);
01530 
01531    return output;
01532 }

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

References xmldoc_build_field().

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

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

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

01157 {
01158    struct ast_xml_node *node;
01159    char *syntax = NULL;
01160 
01161    node = xmldoc_get_node(type, name, module, documentation_language);
01162    if (!node) {
01163       return NULL;
01164    }
01165 
01166    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01167       if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
01168          break;
01169       }
01170    }
01171 
01172    if (node) {
01173       switch (xmldoc_get_syntax_type(type)) {
01174       case FUNCTION_SYNTAX:
01175          syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
01176          break;
01177       case COMMAND_SYNTAX:
01178          syntax = xmldoc_get_syntax_cmd(node, name, 1);
01179          break;
01180       case MANAGER_SYNTAX:
01181          syntax = xmldoc_get_syntax_manager(node, name);
01182          break;
01183       default:
01184          syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
01185       }
01186    }
01187    return syntax;
01188 }

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 315 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_show_function(), handle_showmancmd(), print_app_docs(), and write_htmldump().

00316 {
00317    struct ast_str *colorized;
00318    char *wrapped = NULL;
00319    int i, c, len, colorsection;
00320    char *tmp;
00321    size_t bwinputlen;
00322    static const int base_fg = COLOR_CYAN;
00323 
00324    if (!bwinput) {
00325       return NULL;
00326    }
00327 
00328    bwinputlen = strlen(bwinput);
00329 
00330    if (!(colorized = ast_str_create(256))) {
00331       return NULL;
00332    }
00333 
00334    if (withcolors) {
00335       ast_term_color_code(&colorized, base_fg, 0);
00336       if (!colorized) {
00337          return NULL;
00338       }
00339    }
00340 
00341    for (i = 0; i < bwinputlen; i++) {
00342       colorsection = 0;
00343       /* Check if we are at the beginning of a tag to be colorized. */
00344       for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
00345          if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
00346             continue;
00347          }
00348 
00349          if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
00350             continue;
00351          }
00352 
00353          len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
00354 
00355          /* Setup color */
00356          if (withcolors) {
00357             if (ast_opt_light_background) {
00358                /* Turn off *bright* colors */
00359                ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
00360             } else {
00361                /* Turn on *bright* colors */
00362                ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
00363             }
00364             if (!colorized) {
00365                return NULL;
00366             }
00367          }
00368 
00369          /* copy initial string replace */
00370          ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
00371          if (!colorized) {
00372             return NULL;
00373          }
00374          {
00375             char buf[len + 1];
00376             ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
00377             ast_str_append(&colorized, 0, "%s", buf);
00378          }
00379          if (!colorized) {
00380             return NULL;
00381          }
00382 
00383          /* copy the ending string replace */
00384          ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
00385          if (!colorized) {
00386             return NULL;
00387          }
00388 
00389          /* Continue with the last color. */
00390          if (withcolors) {
00391             ast_term_color_code(&colorized, base_fg, 0);
00392             if (!colorized) {
00393                return NULL;
00394             }
00395          }
00396 
00397          i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
00398          colorsection = 1;
00399          break;
00400       }
00401 
00402       if (!colorsection) {
00403          ast_str_append(&colorized, 0, "%c", bwinput[i]);
00404          if (!colorized) {
00405             return NULL;
00406          }
00407       }
00408    }
00409 
00410    if (withcolors) {
00411       ast_str_append(&colorized, 0, "%s", term_end());
00412       if (!colorized) {
00413          return NULL;
00414       }
00415    }
00416 
00417    /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
00418    wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns, xmldoc_max_diff);
00419 
00420    ast_free(colorized);
00421 
00422    return wrapped;
00423 }


Generated on 27 Jan 2016 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1