Tue Aug 20 16:35:17 2013

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

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

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

References xmldoc_build_field().

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

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

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

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

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

References xmldoc_build_field().

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

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

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

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

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 20 Aug 2013 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1