Tue Aug 20 16:34:39 2013

Asterisk developer's documentation


xmldoc.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
00005  *
00006  * See http://www.asterisk.org for more information about
00007  * the Asterisk project. Please do not directly contact
00008  * any of the maintainers of this project for assistance;
00009  * the project provides a web site, mailing lists and IRC
00010  * channels for your use.
00011  *
00012  * This program is free software, distributed under the terms of
00013  * the GNU General Public License Version 2. See the LICENSE file
00014  * at the top of the source tree.
00015  */
00016 
00017 /*! \file
00018  *
00019  * \brief XML Documentation API
00020  *
00021  * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
00022  *
00023  * \extref libxml2 http://www.xmlsoft.org/
00024  */
00025 
00026 /*** MODULEINFO
00027    <support_level>core</support_level>
00028  ***/
00029 
00030 #include "asterisk.h"
00031 
00032 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 377509 $")
00033 
00034 #include "asterisk/_private.h"
00035 #include "asterisk/paths.h"
00036 #include "asterisk/linkedlists.h"
00037 #include "asterisk/strings.h"
00038 #include "asterisk/config.h"
00039 #include "asterisk/term.h"
00040 #include "asterisk/xmldoc.h"
00041 
00042 #ifdef AST_XML_DOCS
00043 
00044 /*! \brief Default documentation language. */
00045 static const char default_documentation_language[] = "en_US";
00046 
00047 /*! \brief Number of columns to print when showing the XML documentation with a
00048  *         'core show application/function *' CLI command. Used in text wrapping.*/
00049 static const int xmldoc_text_columns = 74;
00050 
00051 /*! \brief This is a value that we will use to let the wrapping mechanism move the cursor
00052  *         backward and forward xmldoc_max_diff positions before cutting the middle of a
00053  *         word, trying to find a space or a \n. */
00054 static const int xmldoc_max_diff = 5;
00055 
00056 /*! \brief XML documentation language. */
00057 static char documentation_language[6];
00058 
00059 /*! \brief XML documentation tree */
00060 struct documentation_tree {
00061    char *filename;               /*!< XML document filename. */
00062    struct ast_xml_doc *doc;         /*!< Open document pointer. */
00063    AST_RWLIST_ENTRY(documentation_tree) entry;
00064 };
00065 
00066 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname);
00067 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer);
00068 
00069 /*!
00070  * \brief Container of documentation trees
00071  *
00072  * \note A RWLIST is a sufficient container type to use here for now.
00073  *       However, some changes will need to be made to implement ref counting
00074  *       if reload support is added in the future.
00075  */
00076 static AST_RWLIST_HEAD_STATIC(xmldoc_tree, documentation_tree);
00077 
00078 static const struct strcolorized_tags {
00079    const char *init;      /*!< Replace initial tag with this string. */
00080    const char *end;       /*!< Replace end tag with this string. */
00081    const int colorfg;     /*!< Foreground color. */
00082    const char *inittag;   /*!< Initial tag description. */
00083    const char *endtag;    /*!< Ending tag description. */
00084 } colorized_tags[] = {
00085    { "<",  ">",  COLOR_GREEN,  "<replaceable>", "</replaceable>" },
00086    { "\'", "\'", COLOR_BLUE,   "<literal>",     "</literal>" },
00087    { "*",  "*",  COLOR_RED,    "<emphasis>",    "</emphasis>" },
00088    { "\"", "\"", COLOR_YELLOW, "<filename>",    "</filename>" },
00089    { "\"", "\"", COLOR_CYAN,   "<directory>",   "</directory>" },
00090    { "${", "}",  COLOR_GREEN,  "<variable>",    "</variable>" },
00091    { "",   "",   COLOR_BLUE,   "<value>",       "</value>" },
00092    { "",   "",   COLOR_BLUE,   "<enum>",        "</enum>" },
00093    { "\'", "\'", COLOR_GRAY,   "<astcli>",      "</astcli>" },
00094 
00095    /* Special tags */
00096    { "", "", COLOR_YELLOW, "<note>",   "</note>" },
00097    { "", "", COLOR_RED,   "<warning>", "</warning>" }
00098 };
00099 
00100 static const struct strspecial_tags {
00101    const char *tagname;    /*!< Special tag name. */
00102    const char *init;    /*!< Print this at the beginning. */
00103    const char *end;     /*!< Print this at the end. */
00104 } special_tags[] = {
00105    { "note",    "<note>NOTE:</note> ",             "" },
00106    { "warning", "<warning>WARNING!!!:</warning> ", "" }
00107 };
00108 
00109 /*! \internal
00110  *  \brief Calculate the space in bytes used by a format string
00111  *         that will be passed to a sprintf function.
00112  *  \param postbr The format string to use to calculate the length.
00113  *  \retval The postbr length.
00114  */
00115 static int xmldoc_postbrlen(const char *postbr)
00116 {
00117    int postbrreallen = 0, i;
00118    size_t postbrlen;
00119 
00120    if (!postbr) {
00121       return 0;
00122    }
00123    postbrlen = strlen(postbr);
00124    for (i = 0; i < postbrlen; i++) {
00125       if (postbr[i] == '\t') {
00126          postbrreallen += 8 - (postbrreallen % 8);
00127       } else {
00128          postbrreallen++;
00129       }
00130    }
00131    return postbrreallen;
00132 }
00133 
00134 /*! \internal
00135  *  \brief Setup postbr to be used while wrapping the text.
00136  *         Add to postbr array all the spaces and tabs at the beginning of text.
00137  *  \param postbr output array.
00138  *  \param len text array length.
00139  *  \param text Text with format string before the actual string.
00140  */
00141 static void xmldoc_setpostbr(char *postbr, size_t len, const char *text)
00142 {
00143    int c, postbrlen = 0;
00144 
00145    if (!text) {
00146       return;
00147    }
00148 
00149    for (c = 0; c < len; c++) {
00150       if (text[c] == '\t' || text[c] == ' ') {
00151          postbr[postbrlen++] = text[c];
00152       } else {
00153          break;
00154       }
00155    }
00156    postbr[postbrlen] = '\0';
00157 }
00158 
00159 /*! \internal
00160  *  \brief Try to find a space or a break in text starting at currentpost
00161  *         and moving at most maxdiff positions.
00162  *         Helper for xmldoc_string_wrap().
00163  *  \param text Input string where it will search.
00164  *  \param currentpos Current position within text.
00165  *  \param maxdiff Not move more than maxdiff inside text.
00166  *  \retval 1 if a space or break is found inside text while moving.
00167  *  \retval 0 if no space or break is found.
00168  */
00169 static int xmldoc_wait_nextspace(const char *text, int currentpos, int maxdiff)
00170 {
00171    int i, textlen;
00172 
00173    if (!text) {
00174       return 0;
00175    }
00176 
00177    textlen = strlen(text);
00178    for (i = currentpos; i < textlen; i++) {
00179       if (text[i] == ESC) {
00180          /* Move to the end of the escape sequence */
00181          while (i < textlen && text[i] != 'm') {
00182             i++;
00183          }
00184       } else if (text[i] == ' ' || text[i] == '\n') {
00185          /* Found the next space or linefeed */
00186          return 1;
00187       } else if (i - currentpos > maxdiff) {
00188          /* We have looked the max distance and didn't find it */
00189          return 0;
00190       }
00191    }
00192 
00193    /* Reached the end and did not find it */
00194 
00195    return 0;
00196 }
00197 
00198 /*! \internal
00199  *  \brief Helper function for xmldoc_string_wrap().
00200  *    Try to found a space or a break inside text moving backward
00201  *    not more than maxdiff positions.
00202  *  \param text The input string where to search for a space.
00203  *  \param currentpos The current cursor position.
00204  *  \param maxdiff The max number of positions to move within text.
00205  *  \retval 0 If no space is found (Notice that text[currentpos] is not a space or a break)
00206  *  \retval > 0 If a space or a break is found, and the result is the position relative to
00207  *    currentpos.
00208  */
00209 static int xmldoc_foundspace_backward(const char *text, int currentpos, int maxdiff)
00210 {
00211    int i;
00212 
00213    for (i = currentpos; i > 0; i--) {
00214       if (text[i] == ' ' || text[i] == '\n') {
00215          return (currentpos - i);
00216       } else if (text[i] == 'm' && (text[i - 1] >= '0' || text[i - 1] <= '9')) {
00217          /* give up, we found the end of a possible ESC sequence. */
00218          return 0;
00219       } else if (currentpos - i > maxdiff) {
00220          /* give up, we can't move anymore. */
00221          return 0;
00222       }
00223    }
00224 
00225    /* we found the beginning of the text */
00226 
00227    return 0;
00228 }
00229 
00230 /*! \internal
00231  *  \brief Justify a text to a number of columns.
00232  *  \param text Input text to be justified.
00233  *  \param columns Number of columns to preserve in the text.
00234  *  \param maxdiff Try to not cut a word when goinf down.
00235  *  \retval NULL on error.
00236  *  \retval The wrapped text.
00237  */
00238 static char *xmldoc_string_wrap(const char *text, int columns, int maxdiff)
00239 {
00240    struct ast_str *tmp;
00241    char *ret, postbr[160];
00242    int count = 1, i, backspace, needtobreak = 0, colmax, textlen;
00243 
00244    /* sanity check */
00245    if (!text || columns <= 0 || maxdiff < 0) {
00246       ast_log(LOG_WARNING, "Passing wrong arguments while trying to wrap the text\n");
00247       return NULL;
00248    }
00249 
00250    tmp = ast_str_create(strlen(text) * 3);
00251 
00252    if (!tmp) {
00253       return NULL;
00254    }
00255 
00256    /* Check for blanks and tabs and put them in postbr. */
00257    xmldoc_setpostbr(postbr, sizeof(postbr), text);
00258    colmax = columns - xmldoc_postbrlen(postbr);
00259 
00260    textlen = strlen(text);
00261    for (i = 0; i < textlen; i++) {
00262       if (needtobreak || !(count % colmax)) {
00263          if (text[i] == ' ') {
00264             ast_str_append(&tmp, 0, "\n%s", postbr);
00265             needtobreak = 0;
00266             count = 1;
00267          } else if (text[i] != '\n') {
00268             needtobreak = 1;
00269             if (xmldoc_wait_nextspace(text, i, maxdiff)) {
00270                /* wait for the next space */
00271                ast_str_append(&tmp, 0, "%c", text[i]);
00272                continue;
00273             }
00274             /* Try to look backwards */
00275             backspace = xmldoc_foundspace_backward(text, i, maxdiff);
00276             if (backspace) {
00277                needtobreak = 1;
00278                ast_str_truncate(tmp, -backspace);
00279                i -= backspace + 1;
00280                continue;
00281             }
00282             ast_str_append(&tmp, 0, "\n%s", postbr);
00283             needtobreak = 0;
00284             count = 1;
00285          }
00286          /* skip blanks after a \n */
00287          while (text[i] == ' ') {
00288             i++;
00289          }
00290       }
00291       if (text[i] == '\n') {
00292          xmldoc_setpostbr(postbr, sizeof(postbr), &text[i] + 1);
00293          colmax = columns - xmldoc_postbrlen(postbr);
00294          needtobreak = 0;
00295          count = 1;
00296       }
00297       if (text[i] == ESC) {
00298          /* Ignore Escape sequences. */
00299          do {
00300             ast_str_append(&tmp, 0, "%c", text[i]);
00301             i++;
00302          } while (i < textlen && text[i] != 'm');
00303       } else {
00304          count++;
00305       }
00306       ast_str_append(&tmp, 0, "%c", text[i]);
00307    }
00308 
00309    ret = ast_strdup(ast_str_buffer(tmp));
00310    ast_free(tmp);
00311 
00312    return ret;
00313 }
00314 
00315 char *ast_xmldoc_printable(const char *bwinput, int withcolors)
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 }
00424 
00425 /*! \internal
00426  *  \brief Cleanup spaces and tabs after a \n
00427  *  \param text String to be cleaned up.
00428  *  \param output buffer (not already allocated).
00429  *  \param lastspaces Remove last spaces in the string.
00430  */
00431 static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces)
00432 {
00433    int i;
00434    size_t textlen;
00435 
00436    if (!text) {
00437       *output = NULL;
00438       return;
00439    }
00440 
00441    textlen = strlen(text);
00442 
00443    *output = ast_str_create(textlen);
00444    if (!(*output)) {
00445       ast_log(LOG_ERROR, "Problem allocating output buffer\n");
00446       return;
00447    }
00448 
00449    for (i = 0; i < textlen; i++) {
00450       if (text[i] == '\n' || text[i] == '\r') {
00451          /* remove spaces/tabs/\n after a \n. */
00452          while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') {
00453             i++;
00454          }
00455          ast_str_append(output, 0, " ");
00456          continue;
00457       } else {
00458          ast_str_append(output, 0, "%c", text[i]);
00459       }
00460    }
00461 
00462    /* remove last spaces (we don't want always to remove the trailing spaces). */
00463    if (lastspaces) {
00464       ast_str_trim_blanks(*output);
00465    }
00466 }
00467 
00468 /*! \internal
00469  * \brief Check if the given attribute on the given node matches the given value.
00470  * \param node the node to match
00471  * \param attr the name of the attribute
00472  * \param value the expected value of the attribute
00473  * \retval true if the given attribute contains the given value
00474  * \retval false if the given attribute does not exist or does not contain the given value
00475  */
00476 static int xmldoc_attribute_match(struct ast_xml_node *node, const char *attr, const char *value)
00477 {
00478    const char *attr_value = ast_xml_get_attribute(node, attr);
00479    int match = attr_value && !strcmp(attr_value, value);
00480    ast_xml_free_attr(attr_value);
00481    return match;
00482 }
00483 
00484 /*! \internal
00485  *  \brief Get the application/function node for 'name' application/function with language 'language'
00486  *         and module 'module' if we don't find any, get the first application
00487  *         with 'name' no matter which language or module.
00488  *  \param type 'application', 'function', ...
00489  *  \param name Application or Function name.
00490  *  \param module Module item is in.
00491  *  \param language Try to get this language (if not found try with en_US)
00492  *  \retval NULL on error.
00493  *  \retval A node of type ast_xml_node.
00494  */
00495 static struct ast_xml_node *xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
00496 {
00497    struct ast_xml_node *node = NULL;
00498    struct ast_xml_node *first_match = NULL;
00499    struct ast_xml_node *lang_match = NULL;
00500    struct documentation_tree *doctree;
00501 
00502    AST_RWLIST_RDLOCK(&xmldoc_tree);
00503    AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
00504       /* the core xml documents have priority over thirdparty document. */
00505       node = ast_xml_get_root(doctree->doc);
00506       if (!node) {
00507          break;
00508       }
00509 
00510       node = ast_xml_node_get_children(node);
00511       while ((node = ast_xml_find_element(node, type, "name", name))) {
00512          if (!ast_xml_node_get_children(node)) {
00513             /* ignore empty nodes */
00514             node = ast_xml_node_get_next(node);
00515             continue;
00516          }
00517 
00518          if (!first_match) {
00519             first_match = node;
00520          }
00521 
00522          /* Check language */
00523          if (xmldoc_attribute_match(node, "language", language)) {
00524             if (!lang_match) {
00525                lang_match = node;
00526             }
00527 
00528             /* if module is empty we have a match */
00529             if (ast_strlen_zero(module)) {
00530                break;
00531             }
00532 
00533             /* Check module */
00534             if (xmldoc_attribute_match(node, "module", module)) {
00535                break;
00536             }
00537          }
00538 
00539          node = ast_xml_node_get_next(node);
00540       }
00541 
00542       /* if we matched lang and module return this match */
00543       if (node) {
00544          break;
00545       }
00546 
00547       /* we didn't match lang and module, just return the first
00548        * result with a matching language if we have one */
00549       if (lang_match) {
00550          node = lang_match;
00551          break;
00552       }
00553 
00554       /* we didn't match with only the language, just return the
00555        * first match */
00556       if (first_match) {
00557          node = first_match;
00558          break;
00559       }
00560    }
00561    AST_RWLIST_UNLOCK(&xmldoc_tree);
00562 
00563    return node;
00564 }
00565 
00566 /*! \internal
00567  *  \brief Helper function used to build the syntax, it allocates the needed buffer (or reallocates it),
00568  *         and based on the reverse value it makes use of fmt to print the parameter list inside the
00569  *         realloced buffer (syntax).
00570  *  \param reverse We are going backwards while generating the syntax?
00571  *  \param len Current length of 'syntax' buffer.
00572  *  \param syntax Output buffer for the concatenated values.
00573  *  \param fmt A format string that will be used in a sprintf call.
00574  */
00575 static void __attribute__((format(printf, 4, 5))) xmldoc_reverse_helper(int reverse, int *len, char **syntax, const char *fmt, ...)
00576 {
00577    int totlen, tmpfmtlen;
00578    char *tmpfmt, tmp;
00579    va_list ap;
00580 
00581    va_start(ap, fmt);
00582    if (ast_vasprintf(&tmpfmt, fmt, ap) < 0) {
00583       va_end(ap);
00584       return;
00585    }
00586    va_end(ap);
00587 
00588    tmpfmtlen = strlen(tmpfmt);
00589    totlen = *len + tmpfmtlen + 1;
00590 
00591    *syntax = ast_realloc(*syntax, totlen);
00592 
00593    if (!*syntax) {
00594       ast_free(tmpfmt);
00595       return;
00596    }
00597 
00598    if (reverse) {
00599       memmove(*syntax + tmpfmtlen, *syntax, *len);
00600       /* Save this char, it will be overwritten by the \0 of strcpy. */
00601       tmp = (*syntax)[0];
00602       strcpy(*syntax, tmpfmt);
00603       /* Restore the already saved char. */
00604       (*syntax)[tmpfmtlen] = tmp;
00605       (*syntax)[totlen - 1] = '\0';
00606    } else {
00607       strcpy(*syntax + *len, tmpfmt);
00608    }
00609 
00610    *len = totlen - 1;
00611    ast_free(tmpfmt);
00612 }
00613 
00614 /*! \internal
00615  *  \brief Check if the passed node has 'what' tags inside it.
00616  *  \param node Root node to search 'what' elements.
00617  *  \param what node name to search inside node.
00618  *  \retval 1 If a 'what' element is found inside 'node'.
00619  *  \retval 0 If no 'what' is found inside 'node'.
00620  */
00621 static int xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
00622 {
00623    struct ast_xml_node *node = fixnode;
00624 
00625    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
00626       if (!strcasecmp(ast_xml_node_get_name(node), what)) {
00627          return 1;
00628       }
00629    }
00630    return 0;
00631 }
00632 
00633 /*! \internal
00634  *  \brief Check if the passed node has at least one node inside it.
00635  *  \param node Root node to search node elements.
00636  *  \retval 1 If a node element is found inside 'node'.
00637  *  \retval 0 If no node is found inside 'node'.
00638  */
00639 static int xmldoc_has_nodes(struct ast_xml_node *fixnode)
00640 {
00641    struct ast_xml_node *node = fixnode;
00642 
00643    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
00644       if (strcasecmp(ast_xml_node_get_name(node), "text")) {
00645          return 1;
00646       }
00647    }
00648    return 0;
00649 }
00650 
00651 /*! \internal
00652  *  \brief Check if the passed node has at least one specialtag.
00653  *  \param node Root node to search "specialtags" elements.
00654  *  \retval 1 If a "specialtag" element is found inside 'node'.
00655  *  \retval 0 If no "specialtag" is found inside 'node'.
00656  */
00657 static int xmldoc_has_specialtags(struct ast_xml_node *fixnode)
00658 {
00659    struct ast_xml_node *node = fixnode;
00660    int i;
00661 
00662    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
00663       for (i = 0; i < ARRAY_LEN(special_tags); i++) {
00664          if (!strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
00665             return 1;
00666          }
00667       }
00668    }
00669    return 0;
00670 }
00671 
00672 /*! \internal
00673  *  \brief Build the syntax for a specified starting node.
00674  *  \param rootnode A pointer to the ast_xml root node.
00675  *  \param rootname Name of the application, function, option, etc. to build the syntax.
00676  *  \param childname The name of each parameter node.
00677  *  \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
00678  *  \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
00679  *  \retval NULL on error.
00680  *  \retval An ast_malloc'ed string with the syntax generated.
00681  */
00682 static char *xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
00683 {
00684 #define GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
00685 #define ISLAST(__rev, __a)  (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
00686 #define MP(__a) ((multiple ? __a : ""))
00687    struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
00688    const char *paramtype, *multipletype, *paramnameattr, *attrargsep, *parenthesis, *argname;
00689    int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
00690    int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis, multiple;
00691    char *syntax = NULL, *argsep, *paramname;
00692 
00693    if (ast_strlen_zero(rootname) || ast_strlen_zero(childname)) {
00694       ast_log(LOG_WARNING, "Tried to look in XML tree with faulty rootname or childname while creating a syntax.\n");
00695       return NULL;
00696    }
00697 
00698    if (!rootnode || !ast_xml_node_get_children(rootnode)) {
00699       /* If the rootnode field is not found, at least print name. */
00700       if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
00701          syntax = NULL;
00702       }
00703       return syntax;
00704    }
00705 
00706    /* Get the argument separator from the root node attribute name 'argsep', if not found
00707    defaults to ','. */
00708    attrargsep = ast_xml_get_attribute(rootnode, "argsep");
00709    if (attrargsep) {
00710       argsep = ast_strdupa(attrargsep);
00711       ast_xml_free_attr(attrargsep);
00712    } else {
00713       argsep = ast_strdupa(",");
00714    }
00715 
00716    /* Get order of evaluation. */
00717    for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
00718       if (strcasecmp(ast_xml_node_get_name(node), childname)) {
00719          continue;
00720       }
00721       required = 0;
00722       hasparams = 1;
00723       if ((paramtype = ast_xml_get_attribute(node, "required"))) {
00724          if (ast_true(paramtype)) {
00725             required = 1;
00726          }
00727          ast_xml_free_attr(paramtype);
00728       }
00729 
00730       lastparam = node;
00731       reqlanode = required;
00732 
00733       if (!firstparam) {
00734          /* first parameter node */
00735          firstparam = node;
00736          reqfinode = required;
00737       }
00738    }
00739 
00740    if (!hasparams) {
00741       /* This application, function, option, etc, doesn't have any params. */
00742       if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
00743          syntax = NULL;
00744       }
00745       return syntax;
00746    }
00747 
00748    if (reqfinode && reqlanode) {
00749       /* check midnode */
00750       for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
00751          if (strcasecmp(ast_xml_node_get_name(node), childname)) {
00752             continue;
00753          }
00754          if (node != firstparam && node != lastparam) {
00755             if ((paramtype = ast_xml_get_attribute(node, "required"))) {
00756                if (!ast_true(paramtype)) {
00757                   optmidnode = 1;
00758                   break;
00759                }
00760                ast_xml_free_attr(paramtype);
00761             }
00762          }
00763       }
00764    }
00765 
00766    if ((!reqfinode && reqlanode) || (reqfinode && reqlanode && optmidnode)) {
00767       reverse = 1;
00768       node = lastparam;
00769    } else {
00770       reverse = 0;
00771       node = firstparam;
00772    }
00773 
00774    /* init syntax string. */
00775    if (reverse) {
00776       xmldoc_reverse_helper(reverse, &len, &syntax,
00777          (printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
00778    } else {
00779       xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
00780          (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
00781    }
00782 
00783    for (; node; node = GOTONEXT(reverse, node)) {
00784       if (strcasecmp(ast_xml_node_get_name(node), childname)) {
00785          continue;
00786       }
00787 
00788       /* Get the argument name, if it is not the leaf, go inside that parameter. */
00789       if (xmldoc_has_inside(node, "argument")) {
00790          parenthesis = ast_xml_get_attribute(node, "hasparams");
00791          prnparenthesis = 0;
00792          if (parenthesis) {
00793             prnparenthesis = ast_true(parenthesis);
00794             if (!strcasecmp(parenthesis, "optional")) {
00795                prnparenthesis = 2;
00796             }
00797             ast_xml_free_attr(parenthesis);
00798          }
00799          argname = ast_xml_get_attribute(node, "name");
00800          if (argname) {
00801             paramname = xmldoc_get_syntax_fun(node, argname, "argument", prnparenthesis, prnparenthesis);
00802             ast_xml_free_attr(argname);
00803          } else {
00804             /* Malformed XML, print **UNKOWN** */
00805             paramname = ast_strdup("**unknown**");
00806          }
00807       } else {
00808          paramnameattr = ast_xml_get_attribute(node, "name");
00809          if (!paramnameattr) {
00810             ast_log(LOG_WARNING, "Malformed XML %s: no %s name\n", rootname, childname);
00811             if (syntax) {
00812                /* Free already allocated syntax */
00813                ast_free(syntax);
00814             }
00815             /* to give up is ok? */
00816             if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
00817                syntax = NULL;
00818             }
00819             return syntax;
00820          }
00821          paramname = ast_strdup(paramnameattr);
00822          ast_xml_free_attr(paramnameattr);
00823       }
00824 
00825       if (!paramname) {
00826          return NULL;
00827       }
00828 
00829       /* Defaults to 'false'. */
00830       multiple = 0;
00831       if ((multipletype = ast_xml_get_attribute(node, "multiple"))) {
00832          if (ast_true(multipletype)) {
00833             multiple = 1;
00834          }
00835          ast_xml_free_attr(multipletype);
00836       }
00837 
00838       required = 0;  /* Defaults to 'false'. */
00839       if ((paramtype = ast_xml_get_attribute(node, "required"))) {
00840          if (ast_true(paramtype)) {
00841             required = 1;
00842          }
00843          ast_xml_free_attr(paramtype);
00844       }
00845 
00846       /* build syntax core. */
00847 
00848       if (required) {
00849          /* First parameter */
00850          if (!paramcount) {
00851             xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
00852          } else {
00853             /* Time to close open brackets. */
00854             while (openbrackets > 0) {
00855                xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
00856                openbrackets--;
00857             }
00858             if (reverse) {
00859                xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", paramname, argsep);
00860             } else {
00861                xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", argsep, paramname);
00862             }
00863             xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s", MP("["), MP(argsep), MP("...]"));
00864          }
00865       } else {
00866          /* First parameter */
00867          if (!paramcount) {
00868             xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]", paramname, MP("["), MP(argsep), MP("...]"));
00869          } else {
00870             if (ISLAST(reverse, node)) {
00871                /* This is the last parameter. */
00872                if (reverse) {
00873                   xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]%s", paramname,
00874                            MP("["), MP(argsep), MP("...]"), argsep);
00875                } else {
00876                   xmldoc_reverse_helper(reverse, &len, &syntax, "%s[%s%s%s%s]", argsep, paramname,
00877                            MP("["), MP(argsep), MP("...]"));
00878                }
00879             } else {
00880                if (reverse) {
00881                   xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s%s]", paramname, argsep,
00882                            MP("["), MP(argsep), MP("...]"));
00883                } else {
00884                   xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s%s", argsep, paramname,
00885                            MP("["), MP(argsep), MP("...]"));
00886                }
00887                openbrackets++;
00888             }
00889          }
00890       }
00891       ast_free(paramname);
00892 
00893       paramcount++;
00894    }
00895 
00896    /* Time to close open brackets. */
00897    while (openbrackets > 0) {
00898       xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
00899       openbrackets--;
00900    }
00901 
00902    /* close syntax string. */
00903    if (reverse) {
00904       xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
00905          (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
00906    } else {
00907       xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
00908    }
00909 
00910    return syntax;
00911 #undef ISLAST
00912 #undef GOTONEXT
00913 #undef MP
00914 }
00915 
00916 /*! \internal
00917  *  \brief Parse an enumlist inside a <parameter> to generate a COMMAND
00918  *         syntax.
00919  *  \param fixnode A pointer to the <enumlist> node.
00920  *  \retval {<unknown>} on error.
00921  *  \retval A string inside brackets {} with the enum's separated by pipes |.
00922  */
00923 static char *xmldoc_parse_cmd_enumlist(struct ast_xml_node *fixnode)
00924 {
00925    struct ast_xml_node *node = fixnode;
00926    struct ast_str *paramname;
00927    char *enumname, *ret;
00928    int first = 1;
00929 
00930    paramname = ast_str_create(128);
00931    if (!paramname) {
00932       return ast_strdup("{<unkown>}");
00933    }
00934 
00935    ast_str_append(&paramname, 0, "{");
00936 
00937    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
00938       if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
00939          continue;
00940       }
00941 
00942       enumname = xmldoc_get_syntax_cmd(node, "", 0);
00943       if (!enumname) {
00944          continue;
00945       }
00946       if (!first) {
00947          ast_str_append(&paramname, 0, "|");
00948       }
00949       ast_str_append(&paramname, 0, "%s", enumname);
00950       first = 0;
00951       ast_free(enumname);
00952    }
00953 
00954    ast_str_append(&paramname, 0, "}");
00955 
00956    ret = ast_strdup(ast_str_buffer(paramname));
00957    ast_free(paramname);
00958 
00959    return ret;
00960 }
00961 
00962 /*! \internal
00963  *  \brief Generate a syntax of COMMAND type.
00964  *  \param fixnode The <syntax> node pointer.
00965  *  \param name The name of the 'command'.
00966  *  \param printname Print the name of the command before the paramters?
00967  *  \retval On error, return just 'name'.
00968  *  \retval On success return the generated syntax.
00969  */
00970 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
00971 {
00972    struct ast_str *syntax;
00973    struct ast_xml_node *tmpnode, *node = fixnode;
00974    char *ret, *paramname;
00975    const char *paramtype, *attrname, *literal;
00976    int required, isenum, first = 1, isliteral;
00977 
00978    syntax = ast_str_create(128);
00979    if (!syntax) {
00980       /* at least try to return something... */
00981       return ast_strdup(name);
00982    }
00983 
00984    /* append name to output string. */
00985    if (printname) {
00986       ast_str_append(&syntax, 0, "%s", name);
00987       first = 0;
00988    }
00989 
00990    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
00991       if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
00992          continue;
00993       }
00994 
00995       if (xmldoc_has_inside(node, "parameter")) {
00996          /* is this a recursive parameter. */
00997          paramname = xmldoc_get_syntax_cmd(node, "", 0);
00998          isenum = 1;
00999       } else {
01000          for (tmpnode = ast_xml_node_get_children(node); tmpnode; tmpnode = ast_xml_node_get_next(tmpnode)) {
01001             if (!strcasecmp(ast_xml_node_get_name(tmpnode), "enumlist")) {
01002                break;
01003             }
01004          }
01005          if (tmpnode) {
01006             /* parse enumlist (note that this is a special enumlist
01007             that is used to describe a syntax like {<param1>|<param2>|...} */
01008             paramname = xmldoc_parse_cmd_enumlist(tmpnode);
01009             isenum = 1;
01010          } else {
01011             /* this is a simple parameter. */
01012             attrname = ast_xml_get_attribute(node, "name");
01013             if (!attrname) {
01014                /* ignore this bogus parameter and continue. */
01015                continue;
01016             }
01017             paramname = ast_strdup(attrname);
01018             ast_xml_free_attr(attrname);
01019             isenum = 0;
01020          }
01021       }
01022 
01023       /* Is this parameter required? */
01024       required = 0;
01025       paramtype = ast_xml_get_attribute(node, "required");
01026       if (paramtype) {
01027          required = ast_true(paramtype);
01028          ast_xml_free_attr(paramtype);
01029       }
01030 
01031       /* Is this a replaceable value or a fixed parameter value? */
01032       isliteral = 0;
01033       literal = ast_xml_get_attribute(node, "literal");
01034       if (literal) {
01035          isliteral = ast_true(literal);
01036          ast_xml_free_attr(literal);
01037       }
01038 
01039       /* if required="false" print with [...].
01040        * if literal="true" or is enum print without <..>.
01041        * if not first print a space at the beginning.
01042        */
01043       ast_str_append(&syntax, 0, "%s%s%s%s%s%s",
01044             (first ? "" : " "),
01045             (required ? "" : "["),
01046             (isenum || isliteral ? "" : "<"),
01047             paramname,
01048             (isenum || isliteral ? "" : ">"),
01049             (required ? "" : "]"));
01050       first = 0;
01051       ast_free(paramname);
01052    }
01053 
01054    /* return a common string. */
01055    ret = ast_strdup(ast_str_buffer(syntax));
01056    ast_free(syntax);
01057 
01058    return ret;
01059 }
01060 
01061 /*! \internal
01062  *  \brief Generate an AMI action syntax.
01063  *  \param fixnode The manager action node pointer.
01064  *  \param name The name of the manager action.
01065  *  \retval The generated syntax.
01066  *  \retval NULL on error.
01067  */
01068 static char *xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name)
01069 {
01070    struct ast_str *syntax;
01071    struct ast_xml_node *node = fixnode;
01072    const char *paramtype, *attrname;
01073    int required;
01074    char *ret;
01075 
01076    syntax = ast_str_create(128);
01077    if (!syntax) {
01078       return ast_strdup(name);
01079    }
01080 
01081    ast_str_append(&syntax, 0, "Action: %s", name);
01082 
01083    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01084       if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
01085          continue;
01086       }
01087 
01088       /* Is this parameter required? */
01089       required = 0;
01090       paramtype = ast_xml_get_attribute(node, "required");
01091       if (paramtype) {
01092          required = ast_true(paramtype);
01093          ast_xml_free_attr(paramtype);
01094       }
01095 
01096       attrname = ast_xml_get_attribute(node, "name");
01097       if (!attrname) {
01098          /* ignore this bogus parameter and continue. */
01099          continue;
01100       }
01101 
01102       ast_str_append(&syntax, 0, "\n%s%s:%s <value>",
01103          (required ? "" : "["),
01104          attrname,
01105          (required ? "" : "]"));
01106 
01107       ast_xml_free_attr(attrname);
01108    }
01109 
01110    /* return a common string. */
01111    ret = ast_strdup(ast_str_buffer(syntax));
01112    ast_free(syntax);
01113 
01114    return ret;
01115 }
01116 
01117 /*! \brief Types of syntax that we are able to generate. */
01118 enum syntaxtype {
01119    FUNCTION_SYNTAX,
01120    MANAGER_SYNTAX,
01121    COMMAND_SYNTAX
01122 };
01123 
01124 /*! \brief Mapping between type of node and type of syntax to generate. */
01125 static struct strsyntaxtype {
01126    const char *type;
01127    enum syntaxtype stxtype;
01128 } stxtype[] = {
01129    { "function",     FUNCTION_SYNTAX   },
01130    { "application",  FUNCTION_SYNTAX   },
01131    { "manager",      MANAGER_SYNTAX  },
01132    { "agi",    COMMAND_SYNTAX }
01133 };
01134 
01135 /*! \internal
01136  *  \brief Get syntax type based on type of node.
01137  *  \param type Type of node.
01138  *  \retval The type of syntax to generate based on the type of node.
01139  */
01140 static enum syntaxtype xmldoc_get_syntax_type(const char *type)
01141 {
01142    int i;
01143    for (i=0; i < ARRAY_LEN(stxtype); i++) {
01144       if (!strcasecmp(stxtype[i].type, type)) {
01145          return stxtype[i].stxtype;
01146       }
01147    }
01148 
01149    return FUNCTION_SYNTAX;
01150 }
01151 
01152 char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)
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 }
01185 
01186 /*! \internal
01187  *  \brief Parse a <para> element.
01188  *  \param node The <para> element pointer.
01189  *  \param tabs Added this string before the content of the <para> element.
01190  *  \param posttabs Added this string after the content of the <para> element.
01191  *  \param buffer This must be an already allocated ast_str. It will be used
01192  *         to store the result (if already has something it will be appended to the current
01193  *         string).
01194  *  \retval 1 If 'node' is a named 'para'.
01195  *  \retval 2 If data is appended in buffer.
01196  *  \retval 0 on error.
01197  */
01198 static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
01199 {
01200    const char *tmptext;
01201    struct ast_xml_node *tmp;
01202    int ret = 0;
01203    struct ast_str *tmpstr;
01204 
01205    if (!node || !ast_xml_node_get_children(node)) {
01206       return ret;
01207    }
01208 
01209    if (strcasecmp(ast_xml_node_get_name(node), "para")) {
01210       return ret;
01211    }
01212 
01213    ast_str_append(buffer, 0, "%s", tabs);
01214 
01215    ret = 1;
01216 
01217    for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
01218       /* Get the text inside the <para> element and append it to buffer. */
01219       tmptext = ast_xml_get_text(tmp);
01220       if (tmptext) {
01221          /* Strip \n etc. */
01222          xmldoc_string_cleanup(tmptext, &tmpstr, 0);
01223          ast_xml_free_text(tmptext);
01224          if (tmpstr) {
01225             if (strcasecmp(ast_xml_node_get_name(tmp), "text")) {
01226                ast_str_append(buffer, 0, "<%s>%s</%s>", ast_xml_node_get_name(tmp),
01227                      ast_str_buffer(tmpstr), ast_xml_node_get_name(tmp));
01228             } else {
01229                ast_str_append(buffer, 0, "%s", ast_str_buffer(tmpstr));
01230             }
01231             ast_free(tmpstr);
01232             ret = 2;
01233          }
01234       }
01235    }
01236 
01237    ast_str_append(buffer, 0, "%s", posttabs);
01238 
01239    return ret;
01240 }
01241 
01242 /*! \internal
01243  *  \brief Parse special elements defined in 'struct special_tags' special elements must have a <para> element inside them.
01244  *  \param fixnode special tag node pointer.
01245  *  \param tabs put tabs before printing the node content.
01246  *  \param posttabs put posttabs after printing node content.
01247  *  \param buffer Output buffer, the special tags will be appended here.
01248  *  \retval 0 if no special element is parsed.
01249  *  \retval 1 if a special element is parsed (data is appended to buffer).
01250  *  \retval 2 if a special element is parsed and also a <para> element is parsed inside the specialtag.
01251  */
01252 static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
01253 {
01254    struct ast_xml_node *node = fixnode;
01255    int ret = 0, i, count = 0;
01256 
01257    if (!node || !ast_xml_node_get_children(node)) {
01258       return ret;
01259    }
01260 
01261    for (i = 0; i < ARRAY_LEN(special_tags); i++) {
01262       if (strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
01263          continue;
01264       }
01265 
01266       ret = 1;
01267       /* This is a special tag. */
01268 
01269       /* concat data */
01270       if (!ast_strlen_zero(special_tags[i].init)) {
01271          ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init);
01272       }
01273 
01274       /* parse <para> elements inside special tags. */
01275       for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01276          /* first <para> just print it without tabs at the begining. */
01277          if (xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2) {
01278             ret = 2;
01279          }
01280       }
01281 
01282       if (!ast_strlen_zero(special_tags[i].end)) {
01283          ast_str_append(buffer, 0, "%s%s", special_tags[i].end, posttabs);
01284       }
01285 
01286       break;
01287    }
01288 
01289    return ret;
01290 }
01291 
01292 /*! \internal
01293  *  \brief Parse an <argument> element from the xml documentation.
01294  *  \param fixnode Pointer to the 'argument' xml node.
01295  *  \param insideparameter If we are parsing an <argument> inside a <parameter>.
01296  *  \param paramtabs pre tabs if we are inside a parameter element.
01297  *  \param tabs What to be printed before the argument name.
01298  *  \param buffer Output buffer to put values found inside the <argument> element.
01299  *  \retval 1 If there is content inside the argument.
01300  *  \retval 0 If the argument element is not parsed, or there is no content inside it.
01301  */
01302 static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer)
01303 {
01304    struct ast_xml_node *node = fixnode;
01305    const char *argname;
01306    int count = 0, ret = 0;
01307 
01308    if (!node || !ast_xml_node_get_children(node)) {
01309       return ret;
01310    }
01311 
01312    /* Print the argument names */
01313    argname = ast_xml_get_attribute(node, "name");
01314    if (!argname) {
01315       return 0;
01316    }
01317    if (xmldoc_has_inside(node, "para") || xmldoc_has_specialtags(node)) {
01318       ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
01319       ast_xml_free_attr(argname);
01320    } else {
01321       ast_xml_free_attr(argname);
01322       return 0;
01323    }
01324 
01325    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01326       if (xmldoc_parse_para(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
01327          count++;
01328          ret = 1;
01329       } else if (xmldoc_parse_specialtags(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
01330          count++;
01331          ret = 1;
01332       }
01333    }
01334 
01335    return ret;
01336 }
01337 
01338 /*! \internal
01339  *  \brief Parse a <variable> node inside a <variablelist> node.
01340  *  \param node The variable node to parse.
01341  *  \param tabs A string to be appended at the begining of the output that will be stored
01342  *         in buffer.
01343  *  \param buffer This must be an already created ast_str. It will be used
01344  *         to store the result (if already has something it will be appended to the current
01345  *         string).
01346  *  \retval 0 if no data is appended.
01347  *  \retval 1 if data is appended.
01348  */
01349 static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
01350 {
01351    struct ast_xml_node *tmp;
01352    const char *valname;
01353    const char *tmptext;
01354    struct ast_str *cleanstr;
01355    int ret = 0, printedpara=0;
01356 
01357    for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
01358       if (xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer)) {
01359          printedpara = 1;
01360          continue;
01361       } else if (xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer)) {
01362          printedpara = 1;
01363          continue;
01364       }
01365 
01366       if (strcasecmp(ast_xml_node_get_name(tmp), "value")) {
01367          continue;
01368       }
01369 
01370       /* Parse a <value> tag only. */
01371       if (!printedpara) {
01372          ast_str_append(buffer, 0, "\n");
01373          printedpara = 1;
01374       }
01375       /* Parse each <value name='valuename'>desciption</value> */
01376       valname = ast_xml_get_attribute(tmp, "name");
01377       if (valname) {
01378          ret = 1;
01379          ast_str_append(buffer, 0, "%s<value>%s</value>", tabs, valname);
01380          ast_xml_free_attr(valname);
01381       }
01382       tmptext = ast_xml_get_text(tmp);
01383       /* Check inside this node for any explanation about its meaning. */
01384       if (tmptext) {
01385          /* Cleanup text. */
01386          xmldoc_string_cleanup(tmptext, &cleanstr, 1);
01387          ast_xml_free_text(tmptext);
01388          if (cleanstr && ast_str_strlen(cleanstr) > 0) {
01389             ast_str_append(buffer, 0, ":%s", ast_str_buffer(cleanstr));
01390          }
01391          ast_free(cleanstr);
01392       }
01393       ast_str_append(buffer, 0, "\n");
01394    }
01395 
01396    return ret;
01397 }
01398 
01399 /*! \internal
01400  *  \brief Parse a <variablelist> node and put all the output inside 'buffer'.
01401  *  \param node The variablelist node pointer.
01402  *  \param tabs A string to be appended at the begining of the output that will be stored
01403  *         in buffer.
01404  *  \param buffer This must be an already created ast_str. It will be used
01405  *         to store the result (if already has something it will be appended to the current
01406  *         string).
01407  *  \retval 1 If a <variablelist> element is parsed.
01408  *  \retval 0 On error.
01409  */
01410 static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
01411 {
01412    struct ast_xml_node *tmp;
01413    const char *varname;
01414    char *vartabs;
01415    int ret = 0;
01416 
01417    if (!node || !ast_xml_node_get_children(node)) {
01418       return ret;
01419    }
01420 
01421    if (strcasecmp(ast_xml_node_get_name(node), "variablelist")) {
01422       return ret;
01423    }
01424 
01425    /* use this spacing (add 4 spaces) inside a variablelist node. */
01426    if (ast_asprintf(&vartabs, "%s    ", tabs) < 0) {
01427       return ret;
01428    }
01429    for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
01430       /* We can have a <para> element inside the variable list */
01431       if ((xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer))) {
01432          ret = 1;
01433          continue;
01434       } else if ((xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer))) {
01435          ret = 1;
01436          continue;
01437       }
01438 
01439       if (!strcasecmp(ast_xml_node_get_name(tmp), "variable")) {
01440          /* Store the variable name in buffer. */
01441          varname = ast_xml_get_attribute(tmp, "name");
01442          if (varname) {
01443             ast_str_append(buffer, 0, "%s<variable>%s</variable>: ", tabs, varname);
01444             ast_xml_free_attr(varname);
01445             /* Parse the <variable> possible values. */
01446             xmldoc_parse_variable(tmp, vartabs, buffer);
01447             ret = 1;
01448          }
01449       }
01450    }
01451 
01452    ast_free(vartabs);
01453 
01454    return ret;
01455 }
01456 
01457 char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
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 }
01529 
01530 /*! \internal
01531  *  \brief Parse a <enum> node.
01532  *  \brief fixnode An ast_xml_node pointer to the <enum> node.
01533  *  \bried buffer The output buffer.
01534  *  \retval 0 if content is not found inside the enum element (data is not appended to buffer).
01535  *  \retval 1 if content is found and data is appended to buffer.
01536  */
01537 static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
01538 {
01539    struct ast_xml_node *node = fixnode;
01540    int ret = 0;
01541    char *optiontabs;
01542 
01543    if (ast_asprintf(&optiontabs, "%s    ", tabs) < 0) {
01544       return ret;
01545    }
01546 
01547    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01548       if ((xmldoc_parse_para(node, (ret ? tabs : " - "), "\n", buffer))) {
01549          ret = 1;
01550       } else if ((xmldoc_parse_specialtags(node, (ret ? tabs : " - "), "\n", buffer))) {
01551          ret = 1;
01552       }
01553 
01554       xmldoc_parse_enumlist(node, optiontabs, buffer);
01555    }
01556 
01557    ast_free(optiontabs);
01558 
01559    return ret;
01560 }
01561 
01562 /*! \internal
01563  *  \brief Parse a <enumlist> node.
01564  *  \param fixnode As ast_xml pointer to the <enumlist> node.
01565  *  \param buffer The ast_str output buffer.
01566  *  \retval 0 if no <enumlist> node was parsed.
01567  *  \retval 1 if a <enumlist> node was parsed.
01568  */
01569 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
01570 {
01571    struct ast_xml_node *node = fixnode;
01572    const char *enumname;
01573    int ret = 0;
01574 
01575    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01576       if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
01577          continue;
01578       }
01579 
01580       enumname = ast_xml_get_attribute(node, "name");
01581       if (enumname) {
01582          ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
01583          ast_xml_free_attr(enumname);
01584 
01585          /* parse only enum elements inside a enumlist node. */
01586          if ((xmldoc_parse_enum(node, tabs, buffer))) {
01587             ret = 1;
01588          } else {
01589             ast_str_append(buffer, 0, "\n");
01590          }
01591       }
01592    }
01593    return ret;
01594 }
01595 
01596 /*! \internal
01597  *  \brief Parse an <option> node.
01598  *  \param fixnode An ast_xml pointer to the <option> node.
01599  *  \param tabs A string to be appended at the begining of each line being added to the
01600  *              buffer string.
01601  *  \param buffer The output buffer.
01602  *  \retval 0 if no option node is parsed.
01603  *  \retval 1 if an option node is parsed.
01604  */
01605 static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
01606 {
01607    struct ast_xml_node *node;
01608    int ret = 0;
01609    char *optiontabs;
01610 
01611    if (ast_asprintf(&optiontabs, "%s    ", tabs) < 0) {
01612       return ret;
01613    }
01614    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
01615       if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
01616          /* if this is the first data appended to buffer, print a \n*/
01617          if (!ret && ast_xml_node_get_children(node)) {
01618             /* print \n */
01619             ast_str_append(buffer, 0, "\n");
01620          }
01621          if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
01622             ret = 1;
01623          }
01624          continue;
01625       }
01626 
01627       if (xmldoc_parse_para(node, (ret ? tabs :  ""), "\n", buffer)) {
01628          ret = 1;
01629       } else if (xmldoc_parse_specialtags(node, (ret ? tabs :  ""), "\n", buffer)) {
01630          ret = 1;
01631       }
01632 
01633       xmldoc_parse_variablelist(node, optiontabs, buffer);
01634 
01635       xmldoc_parse_enumlist(node, optiontabs, buffer);
01636    }
01637    ast_free(optiontabs);
01638 
01639    return ret;
01640 }
01641 
01642 /*! \internal
01643  *  \brief Parse an <optionlist> element from the xml documentation.
01644  *  \param fixnode Pointer to the optionlist xml node.
01645  *  \param tabs A string to be appended at the begining of each line being added to the
01646  *              buffer string.
01647  *  \param buffer Output buffer to put what is inside the optionlist tag.
01648  */
01649 static void xmldoc_parse_optionlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
01650 {
01651    struct ast_xml_node *node;
01652    const char *optname, *hasparams;
01653    char *optionsyntax;
01654    int optparams;
01655 
01656    for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
01657       /* Start appending every option tag. */
01658       if (strcasecmp(ast_xml_node_get_name(node), "option")) {
01659          continue;
01660       }
01661 
01662       /* Get the option name. */
01663       optname = ast_xml_get_attribute(node, "name");
01664       if (!optname) {
01665          continue;
01666       }
01667 
01668       optparams = 1;
01669       hasparams = ast_xml_get_attribute(node, "hasparams");
01670       if (hasparams && !strcasecmp(hasparams, "optional")) {
01671          optparams = 2;
01672       }
01673 
01674       optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
01675       if (!optionsyntax) {
01676          ast_xml_free_attr(optname);
01677          ast_xml_free_attr(hasparams);
01678          continue;
01679       }
01680 
01681       ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
01682 
01683       if (!xmldoc_parse_option(node, tabs, buffer)) {
01684          ast_str_append(buffer, 0, "\n");
01685       }
01686       ast_str_append(buffer, 0, "\n");
01687       ast_xml_free_attr(optname);
01688       ast_xml_free_attr(hasparams);
01689       ast_free(optionsyntax);
01690    }
01691 }
01692 
01693 /*! \internal
01694  *  \brief Parse a 'parameter' tag inside a syntax element.
01695  *  \param fixnode A pointer to the 'parameter' xml node.
01696  *  \param tabs A string to be appended at the beginning of each line being printed inside
01697  *              'buffer'.
01698  *  \param buffer String buffer to put values found inside the parameter element.
01699  */
01700 static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
01701 {
01702    const char *paramname;
01703    struct ast_xml_node *node = fixnode;
01704    int hasarguments, printed = 0;
01705    char *internaltabs;
01706 
01707    if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
01708       return;
01709    }
01710 
01711    hasarguments = xmldoc_has_inside(node, "argument");
01712    if (!(paramname = ast_xml_get_attribute(node, "name"))) {
01713       /* parameter MUST have an attribute name. */
01714       return;
01715    }
01716 
01717    if (ast_asprintf(&internaltabs, "%s    ", tabs) < 0) {
01718       ast_xml_free_attr(paramname);
01719       return;
01720    }
01721 
01722    if (!hasarguments && xmldoc_has_nodes(node)) {
01723       ast_str_append(buffer, 0, "%s\n", paramname);
01724       ast_xml_free_attr(paramname);
01725       printed = 1;
01726    }
01727 
01728    for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
01729       if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
01730          xmldoc_parse_optionlist(node, internaltabs, buffer);
01731       } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
01732          xmldoc_parse_enumlist(node, internaltabs, buffer);
01733       } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
01734          xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? "        " : ""), buffer);
01735       } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
01736          if (!printed) {
01737             ast_str_append(buffer, 0, "%s\n", paramname);
01738             ast_xml_free_attr(paramname);
01739             printed = 1;
01740          }
01741          if (xmldoc_parse_para(node, internaltabs, "\n", buffer)) {
01742             /* If anything ever goes in below this condition before the continue below,
01743              * we should probably continue immediately. */
01744             continue;
01745          }
01746          continue;
01747       } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
01748          continue;
01749       }
01750    }
01751    if (!printed) {
01752       ast_xml_free_attr(paramname);
01753    }
01754    ast_free(internaltabs);
01755 }
01756 
01757 char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module)
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 }
01804 
01805 /*! \internal
01806  *  \brief Return the string within a node formatted with <para> and <variablelist> elements.
01807  *  \param node Parent node where content resides.
01808  *  \param raw If set, return the node's content without further processing.
01809  *  \param raw_wrap Wrap raw text.
01810  *  \retval NULL on error
01811  *  \retval Node content on success.
01812  */
01813 static struct ast_str *xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
01814 {
01815    struct ast_xml_node *tmp;
01816    const char *notcleanret, *tmpstr;
01817    struct ast_str *ret;
01818 
01819    if (raw_output) {
01820       /* xmldoc_string_cleanup will allocate the ret object */
01821       notcleanret = ast_xml_get_text(node);
01822       tmpstr = notcleanret;
01823       xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0);
01824       ast_xml_free_text(tmpstr);
01825    } else {
01826       ret = ast_str_create(128);
01827       for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
01828          /* if found, parse a <para> element. */
01829          if (xmldoc_parse_para(tmp, "", "\n", &ret)) {
01830             continue;
01831          } else if (xmldoc_parse_specialtags(tmp, "", "\n", &ret)) {
01832             continue;
01833          }
01834          /* if found, parse a <variablelist> element. */
01835          xmldoc_parse_variablelist(tmp, "", &ret);
01836          xmldoc_parse_enumlist(tmp, "    ", &ret);
01837       }
01838       /* remove last '\n' */
01839       /* XXX Don't modify ast_str internals manually */
01840       tmpstr = ast_str_buffer(ret);
01841       if (tmpstr[ast_str_strlen(ret) - 1] == '\n') {
01842          ast_str_truncate(ret, -1);
01843       }
01844    }
01845    return ret;
01846 }
01847 
01848 /*!
01849  *  \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
01850  *  \param type Type of element (application, function, ...).
01851  *  \param name Name of element (Dial, Echo, Playback, ...).
01852  *  \param var Name of field to return (synopsis, description, etc).
01853  *  \param raw Field only contains text, no other elements inside it.
01854  *  \retval NULL On error.
01855  *  \retval Field text content on success.
01856  */
01857 static char *xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
01858 {
01859    struct ast_xml_node *node;
01860    char *ret = NULL;
01861    struct ast_str *formatted;
01862 
01863    if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
01864       ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
01865       return ret;
01866    }
01867 
01868    node = xmldoc_get_node(type, name, module, documentation_language);
01869 
01870    if (!node) {
01871       ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation\n", type, name);
01872       return ret;
01873    }
01874 
01875    node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
01876 
01877    if (!node || !ast_xml_node_get_children(node)) {
01878       ast_log(LOG_DEBUG, "Cannot find variable '%s' in tree '%s'\n", var, name);
01879       return ret;
01880    }
01881 
01882    formatted = xmldoc_get_formatted(node, raw, raw);
01883    if (ast_str_strlen(formatted) > 0) {
01884       ret = ast_strdup(ast_str_buffer(formatted));
01885    }
01886    ast_free(formatted);
01887 
01888    return ret;
01889 }
01890 
01891 char *ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
01892 {
01893    return xmldoc_build_field(type, name, module, "synopsis", 1);
01894 }
01895 
01896 char *ast_xmldoc_build_description(const char *type, const char *name, const char *module)
01897 {
01898    return xmldoc_build_field(type, name, module, "description", 0);
01899 }
01900 
01901 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
01902 static int xml_pathmatch(char *xmlpattern, int xmlpattern_maxlen, glob_t *globbuf)
01903 {
01904    int globret;
01905 
01906    snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/thirdparty/*-%s.xml",
01907       ast_config_AST_DATA_DIR, documentation_language);
01908    if((globret = glob(xmlpattern, GLOB_NOCHECK, NULL, globbuf))) {
01909       return globret;
01910    }
01911 
01912    snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/thirdparty/*-%.2s_??.xml",
01913       ast_config_AST_DATA_DIR, documentation_language);
01914    if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
01915       return globret;
01916    }
01917 
01918    snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/thirdparty/*-%s.xml",
01919       ast_config_AST_DATA_DIR, default_documentation_language);
01920    if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
01921       return globret;
01922    }
01923 
01924    snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/*-%s.xml",
01925       ast_config_AST_DATA_DIR, documentation_language);
01926    if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
01927       return globret;
01928    }
01929 
01930    snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/*-%.2s_??.xml",
01931       ast_config_AST_DATA_DIR, documentation_language);
01932    if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
01933       return globret;
01934    }
01935 
01936    snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/*-%s.xml",
01937       ast_config_AST_DATA_DIR, default_documentation_language);
01938    globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf);
01939 
01940    return globret;
01941 }
01942 #endif
01943 
01944 /*! \brief Close and unload XML documentation. */
01945 static void xmldoc_unload_documentation(void)
01946 {
01947         struct documentation_tree *doctree;
01948 
01949    AST_RWLIST_WRLOCK(&xmldoc_tree);
01950    while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
01951       ast_free(doctree->filename);
01952       ast_xml_close(doctree->doc);
01953       ast_free(doctree);
01954    }
01955    AST_RWLIST_UNLOCK(&xmldoc_tree);
01956 
01957    ast_xml_finish();
01958 }
01959 
01960 int ast_xmldoc_load_documentation(void)
01961 {
01962    struct ast_xml_node *root_node;
01963    struct ast_xml_doc *tmpdoc;
01964    struct documentation_tree *doc_tree;
01965    char *xmlpattern;
01966    struct ast_config *cfg = NULL;
01967    struct ast_variable *var = NULL;
01968    struct ast_flags cnfflags = { 0 };
01969    int globret, i, dup, duplicate;
01970    glob_t globbuf;
01971 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
01972    int xmlpattern_maxlen;
01973 #endif
01974 
01975    /* setup default XML documentation language */
01976    snprintf(documentation_language, sizeof(documentation_language), default_documentation_language);
01977 
01978    if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
01979       for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
01980          if (!strcasecmp(var->name, "documentation_language")) {
01981             if (!ast_strlen_zero(var->value)) {
01982                snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
01983             }
01984          }
01985       }
01986       ast_config_destroy(cfg);
01987    }
01988 
01989    /* initialize the XML library. */
01990    ast_xml_init();
01991 
01992    /* register function to be run when asterisk finish. */
01993    ast_register_atexit(xmldoc_unload_documentation);
01994 
01995    globbuf.gl_offs = 0;    /* slots to reserve in gl_pathv */
01996 
01997 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
01998    xmlpattern_maxlen = strlen(ast_config_AST_DATA_DIR) + strlen("/documentation/thirdparty") + strlen("/*-??_??.xml") + 1;
01999    xmlpattern = ast_malloc(xmlpattern_maxlen);
02000    globret = xml_pathmatch(xmlpattern, xmlpattern_maxlen, &globbuf);
02001 #else
02002    /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
02003    if (ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
02004       documentation_language, documentation_language, default_documentation_language) < 0) {
02005       return 1;
02006    }
02007    globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
02008 #endif
02009 
02010    ast_debug(3, "gl_pathc %zd\n", globbuf.gl_pathc);
02011    if (globret == GLOB_NOSPACE) {
02012       ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
02013       ast_free(xmlpattern);
02014       return 1;
02015    } else if (globret  == GLOB_ABORTED) {
02016       ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Read error\n", xmlpattern);
02017       ast_free(xmlpattern);
02018       return 1;
02019    }
02020    ast_free(xmlpattern);
02021 
02022    AST_RWLIST_WRLOCK(&xmldoc_tree);
02023    /* loop over expanded files */
02024    for (i = 0; i < globbuf.gl_pathc; i++) {
02025       /* check for duplicates (if we already [try to] open the same file. */
02026       duplicate = 0;
02027       for (dup = 0; dup < i; dup++) {
02028          if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
02029             duplicate = 1;
02030             break;
02031          }
02032       }
02033       if (duplicate || strchr(globbuf.gl_pathv[i], '*')) {
02034       /* skip duplicates as well as pathnames not found 
02035        * (due to use of GLOB_NOCHECK in xml_pathmatch) */
02036          continue;
02037       }
02038       tmpdoc = NULL;
02039       tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
02040       if (!tmpdoc) {
02041          ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
02042          continue;
02043       }
02044       /* Get doc root node and check if it starts with '<docs>' */
02045       root_node = ast_xml_get_root(tmpdoc);
02046       if (!root_node) {
02047          ast_log(LOG_ERROR, "Error getting documentation root node\n");
02048          ast_xml_close(tmpdoc);
02049          continue;
02050       }
02051       /* Check root node name for malformed xmls. */
02052       if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
02053          ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
02054          ast_xml_close(tmpdoc);
02055          continue;
02056       }
02057       doc_tree = ast_calloc(1, sizeof(*doc_tree));
02058       if (!doc_tree) {
02059          ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
02060          ast_xml_close(tmpdoc);
02061          continue;
02062       }
02063       doc_tree->doc = tmpdoc;
02064       doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
02065       AST_RWLIST_INSERT_TAIL(&xmldoc_tree, doc_tree, entry);
02066    }
02067    AST_RWLIST_UNLOCK(&xmldoc_tree);
02068 
02069    globfree(&globbuf);
02070 
02071    return 0;
02072 }
02073 
02074 #endif /* AST_XML_DOCS */
02075 
02076 

Generated on 20 Aug 2013 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1