main/xmldoc.c

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
   5  *
   6  * See http://www.asterisk.org for more information about
   7  * the Asterisk project. Please do not directly contact
   8  * any of the maintainers of this project for assistance;
   9  * the project provides a web site, mailing lists and IRC
  10  * channels for your use.
  11  *
  12  * This program is free software, distributed under the terms of
  13  * the GNU General Public License Version 2. See the LICENSE file
  14  * at the top of the source tree.
  15  */
  16
  17 /*! \file
  18  *
  19  * \brief XML Documentation API
  20  *
  21  * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
  22  *
  23  * libxml2 http://www.xmlsoft.org/
  24  */
  25
  26 /*** MODULEINFO
  27         <support_level>core</support_level>
  28  ***/
  29
  30 #include "asterisk.h"
  31
  32 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
  33
  34 #include "asterisk/_private.h"
  35 #include "asterisk/paths.h"
  36 #include "asterisk/linkedlists.h"
  37 #include "asterisk/config.h"
  38 #include "asterisk/term.h"
  39 #include "asterisk/astobj2.h"
  40 #include "asterisk/xmldoc.h"
  41
  42 #ifdef AST_XML_DOCS
  43
  44 /*! \brief Default documentation language. */
  45 static const char default_documentation_language[] = "en_US";
  46
  47 /*! \brief Number of columns to print when showing the XML documentation with a
  48  *         'core show application/function *' CLI command. Used in text wrapping.*/
  49 static const int xmldoc_text_columns = 74;
  50
  51 /*! \brief This is a value that we will use to let the wrapping mechanism move the cursor
  52  *         backward and forward xmldoc_max_diff positions before cutting the middle of a
  53  *         word, trying to find a space or a \n. */
  54 static const int xmldoc_max_diff = 5;
  55
  56 /*! \brief XML documentation language. */
  57 static char documentation_language[6];
  58
  59 /*! \brief XML documentation tree */
  60 struct documentation_tree {
  61         char *filename;                                 /*!< XML document filename. */
  62         struct ast_xml_doc *doc;                        /*!< Open document pointer. */
  63         AST_RWLIST_ENTRY(documentation_tree) entry;
  64 };
  65
  66 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname);
  67 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer);
  68 static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer);
  69 static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer);
  70 static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer);
  71
  72
  73 /*!
  74  * \brief Container of documentation trees
  75  *
  76  * \note A RWLIST is a sufficient container type to use here for now.
  77  *       However, some changes will need to be made to implement ref counting
  78  *       if reload support is added in the future.
  79  */
  80 static AST_RWLIST_HEAD_STATIC(xmldoc_tree, documentation_tree);
  81
  82 static const struct strcolorized_tags {
  83         const char *init;      /*!< Replace initial tag with this string. */
  84         const char *end;       /*!< Replace end tag with this string. */
  85         const int colorfg;     /*!< Foreground color. */
  86         const char *inittag;   /*!< Initial tag description. */
  87         const char *endtag;    /*!< Ending tag description. */
  88 } colorized_tags[] = {
  89         { "<",  ">",  COLOR_GREEN,  "<replaceable>", "</replaceable>" },
  90         { "\'", "\'", COLOR_BLUE,   "<literal>",     "</literal>" },
  91         { "*",  "*",  COLOR_RED,    "<emphasis>",    "</emphasis>" },
  92         { "\"", "\"", COLOR_YELLOW, "<filename>",    "</filename>" },
  93         { "\"", "\"", COLOR_CYAN,   "<directory>",   "</directory>" },
  94         { "${", "}",  COLOR_GREEN,  "<variable>",    "</variable>" },
  95         { "",   "",   COLOR_BLUE,   "<value>",       "</value>" },
  96         { "",   "",   COLOR_BLUE,   "<enum>",        "</enum>" },
  97         { "\'", "\'", COLOR_GRAY,   "<astcli>",      "</astcli>" },
  98
  99         /* Special tags */
 100         { "", "", COLOR_YELLOW, "<note>",   "</note>" },
 101         { "", "", COLOR_RED,   "<warning>", "</warning>" }
 102 };
 103
 104 static const struct strspecial_tags {
 105         const char *tagname;            /*!< Special tag name. */
 106         const char *init;               /*!< Print this at the beginning. */
 107         const char *end;                /*!< Print this at the end. */
 108 } special_tags[] = {
 109         { "note",    "<note>NOTE:</note> ",             "" },
 110         { "warning", "<warning>WARNING!!!:</warning> ", "" }
 111 };
 112
 113 /*! \internal
 114  *  \brief Calculate the space in bytes used by a format string
 115  *         that will be passed to a sprintf function.
 116  *  \param postbr The format string to use to calculate the length.
 117  *  \retval The postbr length.
 118  */
 119 static int xmldoc_postbrlen(const char *postbr)
 120 {
 121         int postbrreallen = 0, i;
 122         size_t postbrlen;
 123
 124         if (!postbr) {
 125                 return 0;
 126         }
 127         postbrlen = strlen(postbr);
 128         for (i = 0; i < postbrlen; i++) {
 129                 if (postbr[i] == '\t') {
 130                         postbrreallen += 8 - (postbrreallen % 8);
 131                 } else {
 132                         postbrreallen++;
 133                 }
 134         }
 135         return postbrreallen;
 136 }
 137
 138 /*! \internal
 139  *  \brief Setup postbr to be used while wrapping the text.
 140  *         Add to postbr array all the spaces and tabs at the beginning of text.
 141  *  \param postbr output array.
 142  *  \param len text array length.
 143  *  \param text Text with format string before the actual string.
 144  */
 145 static void xmldoc_setpostbr(char *postbr, size_t len, const char *text)
 146 {
 147         int c, postbrlen = 0;
 148
 149         if (!text) {
 150                 return;
 151         }
 152
 153         for (c = 0; c < len; c++) {
 154                 if (text[c] == '\t' || text[c] == ' ') {
 155                         postbr[postbrlen++] = text[c];
 156                 } else {
 157                         break;
 158                 }
 159         }
 160         postbr[postbrlen] = '\0';
 161 }
 162
 163 /*! \internal
 164  *  \brief Try to find a space or a break in text starting at currentpost
 165  *         and moving at most maxdiff positions.
 166  *         Helper for xmldoc_string_wrap().
 167  *  \param text Input string where it will search.
 168  *  \param currentpos Current position within text.
 169  *  \param maxdiff Not move more than maxdiff inside text.
 170  *  \retval 1 if a space or break is found inside text while moving.
 171  *  \retval 0 if no space or break is found.
 172  */
 173 static int xmldoc_wait_nextspace(const char *text, int currentpos, int maxdiff)
 174 {
 175         int i, textlen;
 176
 177         if (!text) {
 178                 return 0;
 179         }
 180
 181         textlen = strlen(text);
 182         for (i = currentpos; i < textlen; i++) {
 183                 if (text[i] == ESC) {
 184                         /* Move to the end of the escape sequence */
 185                         while (i < textlen && text[i] != 'm') {
 186                                 i++;
 187                         }
 188                 } else if (text[i] == ' ' || text[i] == '\n') {
 189                         /* Found the next space or linefeed */
 190                         return 1;
 191                 } else if (i - currentpos > maxdiff) {
 192                         /* We have looked the max distance and didn't find it */
 193                         return 0;
 194                 }
 195         }
 196
 197         /* Reached the end and did not find it */
 198
 199         return 0;
 200 }
 201
 202 /*! \internal
 203  *  \brief Helper function for xmldoc_string_wrap().
 204  *         Try to found a space or a break inside text moving backward
 205  *         not more than maxdiff positions.
 206  *  \param text The input string where to search for a space.
 207  *  \param currentpos The current cursor position.
 208  *  \param maxdiff The max number of positions to move within text.
 209  *  \retval 0 If no space is found (Notice that text[currentpos] is not a space or a break)
 210  *  \retval > 0 If a space or a break is found, and the result is the position relative to
 211  *              currentpos.
 212  */
 213 static int xmldoc_foundspace_backward(const char *text, int currentpos, int maxdiff)
 214 {
 215         int i;
 216
 217         for (i = currentpos; i > 0; i--) {
 218                 if (text[i] == ' ' || text[i] == '\n') {
 219                         return (currentpos - i);
 220                 } else if (text[i] == 'm' && (text[i - 1] >= '0' || text[i - 1] <= '9')) {
 221                         /* give up, we found the end of a possible ESC sequence. */
 222                         return 0;
 223                 } else if (currentpos - i > maxdiff) {
 224                         /* give up, we can't move anymore. */
 225                         return 0;
 226                 }
 227         }
 228
 229         /* we found the beginning of the text */
 230
 231         return 0;
 232 }
 233
 234 /*! \internal
 235  *  \brief Justify a text to a number of columns.
 236  *  \param text Input text to be justified.
 237  *  \param columns Number of columns to preserve in the text.
 238  *  \param maxdiff Try to not cut a word when goinf down.
 239  *  \retval NULL on error.
 240  *  \retval The wrapped text.
 241  */
 242 static char *xmldoc_string_wrap(const char *text, int columns, int maxdiff)
 243 {
 244         struct ast_str *tmp;
 245         char *ret, postbr[160];
 246         int count = 1, i, backspace, needtobreak = 0, colmax, textlen;
 247
 248         /* sanity check */
 249         if (!text || columns <= 0 || maxdiff < 0) {
 250                 ast_log(LOG_WARNING, "Passing wrong arguments while trying to wrap the text\n");
 251                 return NULL;
 252         }
 253
 254         tmp = ast_str_create(strlen(text) * 3);
 255
 256         if (!tmp) {
 257                 return NULL;
 258         }
 259
 260         /* Check for blanks and tabs and put them in postbr. */
 261         xmldoc_setpostbr(postbr, sizeof(postbr), text);
 262         colmax = columns - xmldoc_postbrlen(postbr);
 263
 264         textlen = strlen(text);
 265         for (i = 0; i < textlen; i++) {
 266                 if (needtobreak || !(count % colmax)) {
 267                         if (text[i] == ' ') {
 268                                 ast_str_append(&tmp, 0, "\n%s", postbr);
 269                                 needtobreak = 0;
 270                                 count = 1;
 271                         } else if (text[i] != '\n') {
 272                                 needtobreak = 1;
 273                                 if (xmldoc_wait_nextspace(text, i, maxdiff)) {
 274                                         /* wait for the next space */
 275                                         ast_str_append(&tmp, 0, "%c", text[i]);
 276                                         continue;
 277                                 }
 278                                 /* Try to look backwards */
 279                                 backspace = xmldoc_foundspace_backward(text, i, maxdiff);
 280                                 if (backspace) {
 281                                         needtobreak = 1;
 282                                         ast_str_truncate(tmp, -backspace);
 283                                         i -= backspace + 1;
 284                                         continue;
 285                                 }
 286                                 ast_str_append(&tmp, 0, "\n%s", postbr);
 287                                 needtobreak = 0;
 288                                 count = 1;
 289                         }
 290                         /* skip blanks after a \n */
 291                         while (text[i] == ' ') {
 292                                 i++;
 293                         }
 294                 }
 295                 if (text[i] == '\n') {
 296                         xmldoc_setpostbr(postbr, sizeof(postbr), &text[i] + 1);
 297                         colmax = columns - xmldoc_postbrlen(postbr);
 298                         needtobreak = 0;
 299                         count = 1;
 300                 }
 301                 if (text[i] == ESC) {
 302                         /* Ignore Escape sequences. */
 303                         do {
 304                                 ast_str_append(&tmp, 0, "%c", text[i]);
 305                                 i++;
 306                         } while (i < textlen && text[i] != 'm');
 307                 } else {
 308                         count++;
 309                 }
 310                 ast_str_append(&tmp, 0, "%c", text[i]);
 311         }
 312
 313         ret = ast_strdup(ast_str_buffer(tmp));
 314         ast_free(tmp);
 315
 316         return ret;
 317 }
 318
 319 char *ast_xmldoc_printable(const char *bwinput, int withcolors)
 320 {
 321         struct ast_str *colorized;
 322         char *wrapped = NULL;
 323         int i, c, len, colorsection;
 324         char *tmp;
 325         size_t bwinputlen;
 326         static const int base_fg = COLOR_CYAN;
 327
 328         if (!bwinput) {
 329                 return NULL;
 330         }
 331
 332         bwinputlen = strlen(bwinput);
 333
 334         if (!(colorized = ast_str_create(256))) {
 335                 return NULL;
 336         }
 337
 338         if (withcolors) {
 339                 ast_term_color_code(&colorized, base_fg, 0);
 340                 if (!colorized) {
 341                         return NULL;
 342                 }
 343         }
 344
 345         for (i = 0; i < bwinputlen; i++) {
 346                 colorsection = 0;
 347                 /* Check if we are at the beginning of a tag to be colorized. */
 348                 for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
 349                         if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
 350                                 continue;
 351                         }
 352
 353                         if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
 354                                 continue;
 355                         }
 356
 357                         len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
 358
 359                         /* Setup color */
 360                         if (withcolors) {
 361                                 if (ast_opt_light_background) {
 362                                         /* Turn off *bright* colors */
 363                                         ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
 364                                 } else {
 365                                         /* Turn on *bright* colors */
 366                                         ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
 367                                 }
 368                                 if (!colorized) {
 369                                         return NULL;
 370                                 }
 371                         }
 372
 373                         /* copy initial string replace */
 374                         ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
 375                         if (!colorized) {
 376                                 return NULL;
 377                         }
 378                         {
 379                                 char buf[len + 1];
 380                                 ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
 381                                 ast_str_append(&colorized, 0, "%s", buf);
 382                         }
 383                         if (!colorized) {
 384                                 return NULL;
 385                         }
 386
 387                         /* copy the ending string replace */
 388                         ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
 389                         if (!colorized) {
 390                                 return NULL;
 391                         }
 392
 393                         /* Continue with the last color. */
 394                         if (withcolors) {
 395                                 ast_term_color_code(&colorized, base_fg, 0);
 396                                 if (!colorized) {
 397                                         return NULL;
 398                                 }
 399                         }
 400
 401                         i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
 402                         colorsection = 1;
 403                         break;
 404                 }
 405
 406                 if (!colorsection) {
 407                         ast_str_append(&colorized, 0, "%c", bwinput[i]);
 408                         if (!colorized) {
 409                                 return NULL;
 410                         }
 411                 }
 412         }
 413
 414         if (withcolors) {
 415                 ast_str_append(&colorized, 0, "%s", term_end());
 416                 if (!colorized) {
 417                         return NULL;
 418                 }
 419         }
 420
 421         /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
 422         wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns, xmldoc_max_diff);
 423
 424         ast_free(colorized);
 425
 426         return wrapped;
 427 }
 428
 429 /*! \internal
 430  *  \brief Cleanup spaces and tabs after a \n
 431  *  \param text String to be cleaned up.
 432  *  \param output buffer (not already allocated).
 433  *  \param lastspaces Remove last spaces in the string.
 434  */
 435 static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces)
 436 {
 437         int i;
 438         size_t textlen;
 439
 440         if (!text) {
 441                 *output = NULL;
 442                 return;
 443         }
 444
 445         textlen = strlen(text);
 446
 447         *output = ast_str_create(textlen);
 448         if (!(*output)) {
 449                 ast_log(LOG_ERROR, "Problem allocating output buffer\n");
 450                 return;
 451         }
 452
 453         for (i = 0; i < textlen; i++) {
 454                 if (text[i] == '\n' || text[i] == '\r') {
 455                         /* remove spaces/tabs/\n after a \n. */
 456                         while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') {
 457                                 i++;
 458                         }
 459                         ast_str_append(output, 0, " ");
 460                         continue;
 461                 } else {
 462                         ast_str_append(output, 0, "%c", text[i]);
 463                 }
 464         }
 465
 466         /* remove last spaces (we don't want always to remove the trailing spaces). */
 467         if (lastspaces) {
 468                 ast_str_trim_blanks(*output);
 469         }
 470 }
 471
 472 /*! \internal
 473  * \brief Check if the given attribute on the given node matches the given value.
 474  * \param node the node to match
 475  * \param attr the name of the attribute
 476  * \param value the expected value of the attribute
 477  * \retval true if the given attribute contains the given value
 478  * \retval false if the given attribute does not exist or does not contain the given value
 479  */
 480 static int xmldoc_attribute_match(struct ast_xml_node *node, const char *attr, const char *value)
 481 {
 482         const char *attr_value = ast_xml_get_attribute(node, attr);
 483         int match = attr_value && !strcmp(attr_value, value);
 484         ast_xml_free_attr(attr_value);
 485         return match;
 486 }
 487
 488 /*! \internal
 489  *  \brief Get the application/function node for 'name' application/function with language 'language'
 490  *         and module 'module' if we don't find any, get the first application
 491  *         with 'name' no matter which language or module.
 492  *  \param type 'application', 'function', ...
 493  *  \param name Application or Function name.
 494  *  \param module Module item is in.
 495  *  \param language Try to get this language (if not found try with en_US)
 496  *  \retval NULL on error.
 497  *  \retval A node of type ast_xml_node.
 498  */
 499 static struct ast_xml_node *xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
 500 {
 501         struct ast_xml_node *node = NULL;
 502         struct ast_xml_node *first_match = NULL;
 503         struct ast_xml_node *lang_match = NULL;
 504         struct documentation_tree *doctree;
 505
 506         AST_RWLIST_RDLOCK(&xmldoc_tree);
 507         AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
 508                 /* the core xml documents have priority over thirdparty document. */
 509                 node = ast_xml_get_root(doctree->doc);
 510                 if (!node) {
 511                         break;
 512                 }
 513
 514                 node = ast_xml_node_get_children(node);
 515                 while ((node = ast_xml_find_element(node, type, "name", name))) {
 516                         if (!ast_xml_node_get_children(node)) {
 517                                 /* ignore empty nodes */
 518                                 node = ast_xml_node_get_next(node);
 519                                 continue;
 520                         }
 521
 522                         if (!first_match) {
 523                                 first_match = node;
 524                         }
 525
 526                         /* Check language */
 527                         if (xmldoc_attribute_match(node, "language", language)) {
 528                                 if (!lang_match) {
 529                                         lang_match = node;
 530                                 }
 531
 532                                 /* if module is empty we have a match */
 533                                 if (ast_strlen_zero(module)) {
 534                                         break;
 535                                 }
 536
 537                                 /* Check module */
 538                                 if (xmldoc_attribute_match(node, "module", module)) {
 539                                         break;
 540                                 }
 541                         }
 542
 543                         node = ast_xml_node_get_next(node);
 544                 }
 545
 546                 /* if we matched lang and module return this match */
 547                 if (node) {
 548                         break;
 549                 }
 550
 551                 /* we didn't match lang and module, just return the first
 552                  * result with a matching language if we have one */
 553                 if (lang_match) {
 554                         node = lang_match;
 555                         break;
 556                 }
 557
 558                 /* we didn't match with only the language, just return the
 559                  * first match */
 560                 if (first_match) {
 561                         node = first_match;
 562                         break;
 563                 }
 564         }
 565         AST_RWLIST_UNLOCK(&xmldoc_tree);
 566
 567         return node;
 568 }
 569
 570 /*! \internal
 571  *  \brief Helper function used to build the syntax, it allocates the needed buffer (or reallocates it),
 572  *         and based on the reverse value it makes use of fmt to print the parameter list inside the
 573  *         realloced buffer (syntax).
 574  *  \param reverse We are going backwards while generating the syntax?
 575  *  \param len Current length of 'syntax' buffer.
 576  *  \param syntax Output buffer for the concatenated values.
 577  *  \param fmt A format string that will be used in a sprintf call.
 578  */
 579 static void __attribute__((format(printf, 4, 5))) xmldoc_reverse_helper(int reverse, int *len, char **syntax, const char *fmt, ...)
 580 {
 581         int totlen, tmpfmtlen;
 582         char *tmpfmt, tmp;
 583         va_list ap;
 584
 585         va_start(ap, fmt);
 586         if (ast_vasprintf(&tmpfmt, fmt, ap) < 0) {
 587                 va_end(ap);
 588                 return;
 589         }
 590         va_end(ap);
 591
 592         tmpfmtlen = strlen(tmpfmt);
 593         totlen = *len + tmpfmtlen + 1;
 594
 595         *syntax = ast_realloc(*syntax, totlen);
 596
 597         if (!*syntax) {
 598                 ast_free(tmpfmt);
 599                 return;
 600         }
 601
 602         if (reverse) {
 603                 memmove(*syntax + tmpfmtlen, *syntax, *len);
 604                 /* Save this char, it will be overwritten by the \0 of strcpy. */
 605                 tmp = (*syntax)[0];
 606                 strcpy(*syntax, tmpfmt);
 607                 /* Restore the already saved char. */
 608                 (*syntax)[tmpfmtlen] = tmp;
 609                 (*syntax)[totlen - 1] = '\0';
 610         } else {
 611                 strcpy(*syntax + *len, tmpfmt);
 612         }
 613
 614         *len = totlen - 1;
 615         ast_free(tmpfmt);
 616 }
 617
 618 /*! \internal
 619  *  \brief Check if the passed node has 'what' tags inside it.
 620  *  \param node Root node to search 'what' elements.
 621  *  \param what node name to search inside node.
 622  *  \retval 1 If a 'what' element is found inside 'node'.
 623  *  \retval 0 If no 'what' is found inside 'node'.
 624  */
 625 static int xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
 626 {
 627         struct ast_xml_node *node = fixnode;
 628
 629         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
 630                 if (!strcasecmp(ast_xml_node_get_name(node), what)) {
 631                         return 1;
 632                 }
 633         }
 634         return 0;
 635 }
 636
 637 /*! \internal
 638  *  \brief Check if the passed node has at least one node inside it.
 639  *  \param node Root node to search node elements.
 640  *  \retval 1 If a node element is found inside 'node'.
 641  *  \retval 0 If no node is found inside 'node'.
 642  */
 643 static int xmldoc_has_nodes(struct ast_xml_node *fixnode)
 644 {
 645         struct ast_xml_node *node = fixnode;
 646
 647         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
 648                 if (strcasecmp(ast_xml_node_get_name(node), "text")) {
 649                         return 1;
 650                 }
 651         }
 652         return 0;
 653 }
 654
 655 /*! \internal
 656  *  \brief Check if the passed node has at least one specialtag.
 657  *  \param node Root node to search "specialtags" elements.
 658  *  \retval 1 If a "specialtag" element is found inside 'node'.
 659  *  \retval 0 If no "specialtag" is found inside 'node'.
 660  */
 661 static int xmldoc_has_specialtags(struct ast_xml_node *fixnode)
 662 {
 663         struct ast_xml_node *node = fixnode;
 664         int i;
 665
 666         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
 667                 for (i = 0; i < ARRAY_LEN(special_tags); i++) {
 668                         if (!strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
 669                                 return 1;
 670                         }
 671                 }
 672         }
 673         return 0;
 674 }
 675
 676 /*! \internal
 677  *  \brief Build the syntax for a specified starting node.
 678  *  \param rootnode A pointer to the ast_xml root node.
 679  *  \param rootname Name of the application, function, option, etc. to build the syntax.
 680  *  \param childname The name of each parameter node.
 681  *  \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
 682  *  \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
 683  *  \retval NULL on error.
 684  *  \retval An ast_malloc'ed string with the syntax generated.
 685  */
 686 static char *xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
 687 {
 688 #define GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
 689 #define ISLAST(__rev, __a)  (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
 690 #define MP(__a) ((multiple ? __a : ""))
 691         struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
 692         const char *paramtype, *multipletype, *paramnameattr, *attrargsep, *parenthesis, *argname;
 693         int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
 694         int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis, multiple;
 695         char *syntax = NULL, *argsep, *paramname;
 696
 697         if (ast_strlen_zero(rootname) || ast_strlen_zero(childname)) {
 698                 ast_log(LOG_WARNING, "Tried to look in XML tree with faulty rootname or childname while creating a syntax.\n");
 699                 return NULL;
 700         }
 701
 702         if (!rootnode || !ast_xml_node_get_children(rootnode)) {
 703                 /* If the rootnode field is not found, at least print name. */
 704                 if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
 705                         syntax = NULL;
 706                 }
 707                 return syntax;
 708         }
 709
 710         /* Get the argument separator from the root node attribute name 'argsep', if not found
 711         defaults to ','. */
 712         attrargsep = ast_xml_get_attribute(rootnode, "argsep");
 713         if (attrargsep) {
 714                 argsep = ast_strdupa(attrargsep);
 715                 ast_xml_free_attr(attrargsep);
 716         } else {
 717                 argsep = ast_strdupa(",");
 718         }
 719
 720         /* Get order of evaluation. */
 721         for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
 722                 if (strcasecmp(ast_xml_node_get_name(node), childname)) {
 723                         continue;
 724                 }
 725                 required = 0;
 726                 hasparams = 1;
 727                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
 728                         if (ast_true(paramtype)) {
 729                                 required = 1;
 730                         }
 731                         ast_xml_free_attr(paramtype);
 732                 }
 733
 734                 lastparam = node;
 735                 reqlanode = required;
 736
 737                 if (!firstparam) {
 738                         /* first parameter node */
 739                         firstparam = node;
 740                         reqfinode = required;
 741                 }
 742         }
 743
 744         if (!hasparams) {
 745                 /* This application, function, option, etc, doesn't have any params. */
 746                 if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
 747                         syntax = NULL;
 748                 }
 749                 return syntax;
 750         }
 751
 752         if (reqfinode && reqlanode) {
 753                 /* check midnode */
 754                 for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
 755                         if (strcasecmp(ast_xml_node_get_name(node), childname)) {
 756                                 continue;
 757                         }
 758                         if (node != firstparam && node != lastparam) {
 759                                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
 760                                         if (!ast_true(paramtype)) {
 761                                                 optmidnode = 1;
 762                                                 break;
 763                                         }
 764                                         ast_xml_free_attr(paramtype);
 765                                 }
 766                         }
 767                 }
 768         }
 769
 770         if ((!reqfinode && reqlanode) || (reqfinode && reqlanode && optmidnode)) {
 771                 reverse = 1;
 772                 node = lastparam;
 773         } else {
 774                 reverse = 0;
 775                 node = firstparam;
 776         }
 777
 778         /* init syntax string. */
 779         if (reverse) {
 780                 xmldoc_reverse_helper(reverse, &len, &syntax,
 781                         (printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
 782         } else {
 783                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
 784                         (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
 785         }
 786
 787         for (; node; node = GOTONEXT(reverse, node)) {
 788                 if (strcasecmp(ast_xml_node_get_name(node), childname)) {
 789                         continue;
 790                 }
 791
 792                 /* Get the argument name, if it is not the leaf, go inside that parameter. */
 793                 if (xmldoc_has_inside(node, "argument")) {
 794                         parenthesis = ast_xml_get_attribute(node, "hasparams");
 795                         prnparenthesis = 0;
 796                         if (parenthesis) {
 797                                 prnparenthesis = ast_true(parenthesis);
 798                                 if (!strcasecmp(parenthesis, "optional")) {
 799                                         prnparenthesis = 2;
 800                                 }
 801                                 ast_xml_free_attr(parenthesis);
 802                         }
 803                         argname = ast_xml_get_attribute(node, "name");
 804                         if (argname) {
 805                                 paramname = xmldoc_get_syntax_fun(node, argname, "argument", prnparenthesis, prnparenthesis);
 806                                 ast_xml_free_attr(argname);
 807                         } else {
 808                                 /* Malformed XML, print **UNKOWN** */
 809                                 paramname = ast_strdup("**unknown**");
 810                         }
 811                 } else {
 812                         paramnameattr = ast_xml_get_attribute(node, "name");
 813                         if (!paramnameattr) {
 814                                 ast_log(LOG_WARNING, "Malformed XML %s: no %s name\n", rootname, childname);
 815                                 if (syntax) {
 816                                         /* Free already allocated syntax */
 817                                         ast_free(syntax);
 818                                 }
 819                                 /* to give up is ok? */
 820                                 if (ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : "")) < 0) {
 821                                         syntax = NULL;
 822                                 }
 823                                 return syntax;
 824                         }
 825                         paramname = ast_strdup(paramnameattr);
 826                         ast_xml_free_attr(paramnameattr);
 827                 }
 828
 829                 if (!paramname) {
 830                         return NULL;
 831                 }
 832
 833                 /* Defaults to 'false'. */
 834                 multiple = 0;
 835                 if ((multipletype = ast_xml_get_attribute(node, "multiple"))) {
 836                         if (ast_true(multipletype)) {
 837                                 multiple = 1;
 838                         }
 839                         ast_xml_free_attr(multipletype);
 840                 }
 841
 842                 required = 0;   /* Defaults to 'false'. */
 843                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
 844                         if (ast_true(paramtype)) {
 845                                 required = 1;
 846                         }
 847                         ast_xml_free_attr(paramtype);
 848                 }
 849
 850                 /* build syntax core. */
 851
 852                 if (required) {
 853                         /* First parameter */
 854                         if (!paramcount) {
 855                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
 856                         } else {
 857                                 /* Time to close open brackets. */
 858                                 while (openbrackets > 0) {
 859                                         xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
 860                                         openbrackets--;
 861                                 }
 862                                 if (reverse) {
 863                                         xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", paramname, argsep);
 864                                 } else {
 865                                         xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", argsep, paramname);
 866                                 }
 867                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s", MP("["), MP(argsep), MP("...]"));
 868                         }
 869                 } else {
 870                         /* First parameter */
 871                         if (!paramcount) {
 872                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]", paramname, MP("["), MP(argsep), MP("...]"));
 873                         } else {
 874                                 if (ISLAST(reverse, node)) {
 875                                         /* This is the last parameter. */
 876                                         if (reverse) {
 877                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]%s", paramname,
 878                                                                         MP("["), MP(argsep), MP("...]"), argsep);
 879                                         } else {
 880                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s[%s%s%s%s]", argsep, paramname,
 881                                                                         MP("["), MP(argsep), MP("...]"));
 882                                         }
 883                                 } else {
 884                                         if (reverse) {
 885                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s%s]", paramname, argsep,
 886                                                                         MP("["), MP(argsep), MP("...]"));
 887                                         } else {
 888                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s%s", argsep, paramname,
 889                                                                         MP("["), MP(argsep), MP("...]"));
 890                                         }
 891                                         openbrackets++;
 892                                 }
 893                         }
 894                 }
 895                 ast_free(paramname);
 896
 897                 paramcount++;
 898         }
 899
 900         /* Time to close open brackets. */
 901         while (openbrackets > 0) {
 902                 xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
 903                 openbrackets--;
 904         }
 905
 906         /* close syntax string. */
 907         if (reverse) {
 908                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
 909                         (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
 910         } else {
 911                 xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
 912         }
 913
 914         return syntax;
 915 #undef ISLAST
 916 #undef GOTONEXT
 917 #undef MP
 918 }
 919
 920 /*! \internal
 921  *  \brief Parse an enumlist inside a <parameter> to generate a COMMAND
 922  *         syntax.
 923  *  \param fixnode A pointer to the <enumlist> node.
 924  *  \retval {<unknown>} on error.
 925  *  \retval A string inside brackets {} with the enum's separated by pipes |.
 926  */
 927 static char *xmldoc_parse_cmd_enumlist(struct ast_xml_node *fixnode)
 928 {
 929         struct ast_xml_node *node = fixnode;
 930         struct ast_str *paramname;
 931         char *enumname, *ret;
 932         int first = 1;
 933
 934         paramname = ast_str_create(128);
 935         if (!paramname) {
 936                 return ast_strdup("{<unkown>}");
 937         }
 938
 939         ast_str_append(&paramname, 0, "{");
 940
 941         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
 942                 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
 943                         continue;
 944                 }
 945
 946                 enumname = xmldoc_get_syntax_cmd(node, "", 0);
 947                 if (!enumname) {
 948                         continue;
 949                 }
 950                 if (!first) {
 951                         ast_str_append(&paramname, 0, "|");
 952                 }
 953                 ast_str_append(&paramname, 0, "%s", enumname);
 954                 first = 0;
 955                 ast_free(enumname);
 956         }
 957
 958         ast_str_append(&paramname, 0, "}");
 959
 960         ret = ast_strdup(ast_str_buffer(paramname));
 961         ast_free(paramname);
 962
 963         return ret;
 964 }
 965
 966 /*! \internal
 967  *  \brief Generate a syntax of COMMAND type.
 968  *  \param fixnode The <syntax> node pointer.
 969  *  \param name The name of the 'command'.
 970  *  \param printname Print the name of the command before the paramters?
 971  *  \retval On error, return just 'name'.
 972  *  \retval On success return the generated syntax.
 973  */
 974 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
 975 {
 976         struct ast_str *syntax;
 977         struct ast_xml_node *tmpnode, *node = fixnode;
 978         char *ret, *paramname;
 979         const char *paramtype, *attrname, *literal;
 980         int required, isenum, first = 1, isliteral;
 981
 982         syntax = ast_str_create(128);
 983         if (!syntax) {
 984                 /* at least try to return something... */
 985                 return ast_strdup(name);
 986         }
 987
 988         /* append name to output string. */
 989         if (printname) {
 990                 ast_str_append(&syntax, 0, "%s", name);
 991                 first = 0;
 992         }
 993
 994         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
 995                 if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
 996                         continue;
 997                 }
 998
 999                 if (xmldoc_has_inside(node, "parameter")) {
1000                         /* is this a recursive parameter. */
1001                         paramname = xmldoc_get_syntax_cmd(node, "", 0);
1002                         isenum = 1;
1003                 } else {
1004                         for (tmpnode = ast_xml_node_get_children(node); tmpnode; tmpnode = ast_xml_node_get_next(tmpnode)) {
1005                                 if (!strcasecmp(ast_xml_node_get_name(tmpnode), "enumlist")) {
1006                                         break;
1007                                 }
1008                         }
1009                         if (tmpnode) {
1010                                 /* parse enumlist (note that this is a special enumlist
1011                                 that is used to describe a syntax like {<param1>|<param2>|...} */
1012                                 paramname = xmldoc_parse_cmd_enumlist(tmpnode);
1013                                 isenum = 1;
1014                         } else {
1015                                 /* this is a simple parameter. */
1016                                 attrname = ast_xml_get_attribute(node, "name");
1017                                 if (!attrname) {
1018                                         /* ignore this bogus parameter and continue. */
1019                                         continue;
1020                                 }
1021                                 paramname = ast_strdup(attrname);
1022                                 ast_xml_free_attr(attrname);
1023                                 isenum = 0;
1024                         }
1025                 }
1026
1027                 /* Is this parameter required? */
1028                 required = 0;
1029                 paramtype = ast_xml_get_attribute(node, "required");
1030                 if (paramtype) {
1031                         required = ast_true(paramtype);
1032                         ast_xml_free_attr(paramtype);
1033                 }
1034
1035                 /* Is this a replaceable value or a fixed parameter value? */
1036                 isliteral = 0;
1037                 literal = ast_xml_get_attribute(node, "literal");
1038                 if (literal) {
1039                         isliteral = ast_true(literal);
1040                         ast_xml_free_attr(literal);
1041                 }
1042
1043                 /* if required="false" print with [...].
1044                  * if literal="true" or is enum print without <..>.
1045                  * if not first print a space at the beginning.
1046                  */
1047                 ast_str_append(&syntax, 0, "%s%s%s%s%s%s",
1048                                 (first ? "" : " "),
1049                                 (required ? "" : "["),
1050                                 (isenum || isliteral ? "" : "<"),
1051                                 paramname,
1052                                 (isenum || isliteral ? "" : ">"),
1053                                 (required ? "" : "]"));
1054                 first = 0;
1055                 ast_free(paramname);
1056         }
1057
1058         /* return a common string. */
1059         ret = ast_strdup(ast_str_buffer(syntax));
1060         ast_free(syntax);
1061
1062         return ret;
1063 }
1064
1065 /*! \internal
1066  *  \brief Generate an AMI action/event syntax.
1067  *  \param fixnode The manager action/event node pointer.
1068  *  \param name The name of the manager action/event.
1069  *  \param manager_type "Action" or "Event"
1070  *  \retval The generated syntax.
1071  *  \retval NULL on error.
1072  */
1073 static char *xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name, const char *manager_type)
1074 {
1075         struct ast_str *syntax;
1076         struct ast_xml_node *node = fixnode;
1077         const char *paramtype, *attrname;
1078         int required;
1079         char *ret;
1080
1081         syntax = ast_str_create(128);
1082         if (!syntax) {
1083                 return ast_strdup(name);
1084         }
1085
1086         ast_str_append(&syntax, 0, "%s: %s", manager_type, name);
1087
1088         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1089                 if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
1090                         continue;
1091                 }
1092
1093                 /* Is this parameter required? */
1094                 required = !strcasecmp(manager_type, "event") ? 1 : 0;
1095                 paramtype = ast_xml_get_attribute(node, "required");
1096                 if (paramtype) {
1097                         required = ast_true(paramtype);
1098                         ast_xml_free_attr(paramtype);
1099                 }
1100
1101                 attrname = ast_xml_get_attribute(node, "name");
1102                 if (!attrname) {
1103                         /* ignore this bogus parameter and continue. */
1104                         continue;
1105                 }
1106
1107                 ast_str_append(&syntax, 0, "\n%s%s:%s <value>",
1108                         (required ? "" : "["),
1109                         attrname,
1110                         (required ? "" : "]"));
1111                 ast_xml_free_attr(attrname);
1112         }
1113
1114         /* return a common string. */
1115         ret = ast_strdup(ast_str_buffer(syntax));
1116         ast_free(syntax);
1117
1118         return ret;
1119 }
1120
1121 /*! \brief Types of syntax that we are able to generate. */
1122 enum syntaxtype {
1123         FUNCTION_SYNTAX,
1124         MANAGER_SYNTAX,
1125         MANAGER_EVENT_SYNTAX,
1126         COMMAND_SYNTAX
1127 };
1128
1129 /*! \brief Mapping between type of node and type of syntax to generate. */
1130 static struct strsyntaxtype {
1131         const char *type;
1132         enum syntaxtype stxtype;
1133 } stxtype[] = {
1134         { "function",           FUNCTION_SYNTAX                 },
1135         { "application",        FUNCTION_SYNTAX                 },
1136         { "manager",            MANAGER_SYNTAX                  },
1137         { "managerEvent",       MANAGER_EVENT_SYNTAX    },
1138         { "agi",                        COMMAND_SYNTAX                  }
1139 };
1140
1141 /*! \internal
1142  *  \brief Get syntax type based on type of node.
1143  *  \param type Type of node.
1144  *  \retval The type of syntax to generate based on the type of node.
1145  */
1146 static enum syntaxtype xmldoc_get_syntax_type(const char *type)
1147 {
1148         int i;
1149         for (i=0; i < ARRAY_LEN(stxtype); i++) {
1150                 if (!strcasecmp(stxtype[i].type, type)) {
1151                         return stxtype[i].stxtype;
1152                 }
1153         }
1154
1155         return FUNCTION_SYNTAX;
1156 }
1157
1158 /*!
1159  * \internal
1160  * \brief Build syntax information for an item
1161  * \param node  The syntax node to parse
1162  * \param type  The source type
1163  * \param name  The name of the item that the syntax describes
1164  *
1165  * \note This method exists for when you already have the node.  This
1166  * prevents having to lock the documentation tree twice
1167  *
1168  * \returns A malloc'd character pointer to the syntax of the item
1169  * \returns NULL on failure
1170  *
1171  * \since 11
1172  */
1173 static char *_ast_xmldoc_build_syntax(struct ast_xml_node *node, const char *type, const char *name)
1174 {
1175         char *syntax = NULL;
1176
1177         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1178                 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1179                         break;
1180                 }
1181         }
1182
1183         if (!node) {
1184                 return syntax;
1185         }
1186
1187         switch (xmldoc_get_syntax_type(type)) {
1188         case FUNCTION_SYNTAX:
1189                 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1190                 break;
1191         case COMMAND_SYNTAX:
1192                 syntax = xmldoc_get_syntax_cmd(node, name, 1);
1193                 break;
1194         case MANAGER_SYNTAX:
1195                 syntax = xmldoc_get_syntax_manager(node, name, "Action");
1196                 break;
1197         case MANAGER_EVENT_SYNTAX:
1198                 syntax = xmldoc_get_syntax_manager(node, name, "Event");
1199                 break;
1200         default:
1201                 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1202         }
1203
1204         return syntax;
1205 }
1206
1207 char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)
1208 {
1209         struct ast_xml_node *node;
1210
1211         node = xmldoc_get_node(type, name, module, documentation_language);
1212         if (!node) {
1213                 return NULL;
1214         }
1215
1216         return _ast_xmldoc_build_syntax(node, type, name);
1217 }
1218
1219 /*! \internal
1220  *  \brief Parse common internal elements.  This includes paragraphs, special
1221  *         tags, and information nodes.
1222  *  \param node The element to parse
1223  *  \param tabs Add this string before the content of the parsed element.
1224  *  \param posttabs Add this string after the content of the parsed element.
1225  *  \param buffer This must be an already allocated ast_str. It will be used to
1226  *                store the result (if something has already been placed in the
1227  *                buffer, the parsed elements will be appended)
1228  *  \retval 1 if any data was appended to the buffer
1229  *  \retval 2 if the data appended to the buffer contained a text paragraph
1230  *  \retval 0 if no data was appended to the buffer
1231  */
1232 static int xmldoc_parse_common_elements(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
1233 {
1234         return (xmldoc_parse_para(node, tabs, posttabs, buffer)
1235                 || xmldoc_parse_specialtags(node, tabs, posttabs, buffer)
1236                 || xmldoc_parse_info(node, tabs, posttabs, buffer));
1237 }
1238
1239 /*! \internal
1240  *  \brief Parse a <para> element.
1241  *  \param node The <para> element pointer.
1242  *  \param tabs Added this string before the content of the <para> element.
1243  *  \param posttabs Added this string after the content of the <para> element.
1244  *  \param buffer This must be an already allocated ast_str. It will be used
1245  *         to store the result (if already has something it will be appended to the current
1246  *         string).
1247  *  \retval 1 If 'node' is a named 'para'.
1248  *  \retval 2 If data is appended in buffer.
1249  *  \retval 0 on error.
1250  */
1251 static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
1252 {
1253         const char *tmptext;
1254         struct ast_xml_node *tmp;
1255         int ret = 0;
1256         struct ast_str *tmpstr;
1257
1258         if (!node || !ast_xml_node_get_children(node)) {
1259                 return ret;
1260         }
1261
1262         if (strcasecmp(ast_xml_node_get_name(node), "para")) {
1263                 return ret;
1264         }
1265
1266         ast_str_append(buffer, 0, "%s", tabs);
1267
1268         ret = 1;
1269
1270         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1271                 /* Get the text inside the <para> element and append it to buffer. */
1272                 tmptext = ast_xml_get_text(tmp);
1273                 if (tmptext) {
1274                         /* Strip \n etc. */
1275                         xmldoc_string_cleanup(tmptext, &tmpstr, 0);
1276                         ast_xml_free_text(tmptext);
1277                         if (tmpstr) {
1278                                 if (strcasecmp(ast_xml_node_get_name(tmp), "text")) {
1279                                         ast_str_append(buffer, 0, "<%s>%s</%s>", ast_xml_node_get_name(tmp),
1280                                                         ast_str_buffer(tmpstr), ast_xml_node_get_name(tmp));
1281                                 } else {
1282                                         ast_str_append(buffer, 0, "%s", ast_str_buffer(tmpstr));
1283                                 }
1284                                 ast_free(tmpstr);
1285                                 ret = 2;
1286                         }
1287                 }
1288         }
1289
1290         ast_str_append(buffer, 0, "%s", posttabs);
1291
1292         return ret;
1293 }
1294
1295 /*! \internal
1296  *  \brief Parse special elements defined in 'struct special_tags' special elements must have a <para> element inside them.
1297  *  \param fixnode special tag node pointer.
1298  *  \param tabs put tabs before printing the node content.
1299  *  \param posttabs put posttabs after printing node content.
1300  *  \param buffer Output buffer, the special tags will be appended here.
1301  *  \retval 0 if no special element is parsed.
1302  *  \retval 1 if a special element is parsed (data is appended to buffer).
1303  *  \retval 2 if a special element is parsed and also a <para> element is parsed inside the specialtag.
1304  */
1305 static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
1306 {
1307         struct ast_xml_node *node = fixnode;
1308         int ret = 0, i, count = 0;
1309
1310         if (!node || !ast_xml_node_get_children(node)) {
1311                 return ret;
1312         }
1313
1314         for (i = 0; i < ARRAY_LEN(special_tags); i++) {
1315                 if (strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
1316                         continue;
1317                 }
1318
1319                 ret = 1;
1320                 /* This is a special tag. */
1321
1322                 /* concat data */
1323                 if (!ast_strlen_zero(special_tags[i].init)) {
1324                         ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init);
1325                 }
1326
1327                 /* parse <para> elements inside special tags. */
1328                 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1329                         /* first <para> just print it without tabs at the begining. */
1330                         if ((xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2)
1331                                 || (xmldoc_parse_info(node, (!count ? "": tabs), posttabs, buffer) == 2)) {
1332                                 ret = 2;
1333                         }
1334                 }
1335
1336                 if (!ast_strlen_zero(special_tags[i].end)) {
1337                         ast_str_append(buffer, 0, "%s%s", special_tags[i].end, posttabs);
1338                 }
1339
1340                 break;
1341         }
1342
1343         return ret;
1344 }
1345
1346 /*! \internal
1347  *  \brief Parse an 'info' tag inside an element.
1348  *  \param node A pointer to the 'info' xml node.
1349  *  \param tabs A string to be appended at the beginning of each line being printed
1350  *              inside 'buffer'
1351  *  \param posttabs Add this string after the content of the <para> element, if one exists
1352  *  \param String buffer to put values found inide the info element.
1353  *  \ret 2 if the information contained a para element, and it returned a value of 2
1354  *  \ret 1 if information was put into the buffer
1355  *  \ret 0 if no information was put into the buffer or error
1356  */
1357 static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
1358 {
1359         const char *tech;
1360         char *internaltabs;
1361         int internal_ret;
1362         int ret = 0;
1363
1364         if (strcasecmp(ast_xml_node_get_name(node), "info")) {
1365                 return ret;
1366         }
1367
1368         ast_asprintf(&internaltabs, "%s    ", tabs);
1369         if (!internaltabs) {
1370                 return ret;
1371         }
1372
1373         tech = ast_xml_get_attribute(node, "tech");
1374         if (tech) {
1375                 ast_str_append(buffer, 0, "%s<note>Technology: %s</note>\n", internaltabs, tech);
1376                 ast_xml_free_attr(tech);
1377         }
1378
1379         ret = 1;
1380
1381         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1382                 if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
1383                         xmldoc_parse_enumlist(node, internaltabs, buffer);
1384                 } else if ((internal_ret = xmldoc_parse_common_elements(node, internaltabs, posttabs, buffer))) {
1385                         if (internal_ret > ret) {
1386                                 ret = internal_ret;
1387                         }
1388                 }
1389         }
1390         ast_free(internaltabs);
1391
1392         return ret;
1393 }
1394
1395 /*! \internal
1396  *  \brief Parse an <argument> element from the xml documentation.
1397  *  \param fixnode Pointer to the 'argument' xml node.
1398  *  \param insideparameter If we are parsing an <argument> inside a <parameter>.
1399  *  \param paramtabs pre tabs if we are inside a parameter element.
1400  *  \param tabs What to be printed before the argument name.
1401  *  \param buffer Output buffer to put values found inside the <argument> element.
1402  *  \retval 1 If there is content inside the argument.
1403  *  \retval 0 If the argument element is not parsed, or there is no content inside it.
1404  */
1405 static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer)
1406 {
1407         struct ast_xml_node *node = fixnode;
1408         const char *argname;
1409         int count = 0, ret = 0;
1410
1411         if (!node || !ast_xml_node_get_children(node)) {
1412                 return ret;
1413         }
1414
1415         /* Print the argument names */
1416         argname = ast_xml_get_attribute(node, "name");
1417         if (!argname) {
1418                 return 0;
1419         }
1420         if (xmldoc_has_inside(node, "para") || xmldoc_has_inside(node, "info") || xmldoc_has_specialtags(node)) {
1421                 ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
1422                 ast_xml_free_attr(argname);
1423         } else {
1424                 ast_xml_free_attr(argname);
1425                 return 0;
1426         }
1427
1428         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1429                 if (xmldoc_parse_common_elements(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
1430                         count++;
1431                         ret = 1;
1432                 }
1433         }
1434
1435         return ret;
1436 }
1437
1438 /*! \internal
1439  *  \brief Parse a <variable> node inside a <variablelist> node.
1440  *  \param node The variable node to parse.
1441  *  \param tabs A string to be appended at the begining of the output that will be stored
1442  *         in buffer.
1443  *  \param buffer This must be an already created ast_str. It will be used
1444  *         to store the result (if already has something it will be appended to the current
1445  *         string).
1446  *  \retval 0 if no data is appended.
1447  *  \retval 1 if data is appended.
1448  */
1449 static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
1450 {
1451         struct ast_xml_node *tmp;
1452         const char *valname;
1453         const char *tmptext;
1454         struct ast_str *cleanstr;
1455         int ret = 0, printedpara=0;
1456
1457         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1458                 if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
1459                         printedpara = 1;
1460                         continue;
1461                 }
1462
1463                 if (strcasecmp(ast_xml_node_get_name(tmp), "value")) {
1464                         continue;
1465                 }
1466
1467                 /* Parse a <value> tag only. */
1468                 if (!printedpara) {
1469                         ast_str_append(buffer, 0, "\n");
1470                         printedpara = 1;
1471                 }
1472                 /* Parse each <value name='valuename'>desciption</value> */
1473                 valname = ast_xml_get_attribute(tmp, "name");
1474                 if (valname) {
1475                         ret = 1;
1476                         ast_str_append(buffer, 0, "%s<value>%s</value>", tabs, valname);
1477                         ast_xml_free_attr(valname);
1478                 }
1479                 tmptext = ast_xml_get_text(tmp);
1480                 /* Check inside this node for any explanation about its meaning. */
1481                 if (tmptext) {
1482                         /* Cleanup text. */
1483                         xmldoc_string_cleanup(tmptext, &cleanstr, 1);
1484                         ast_xml_free_text(tmptext);
1485                         if (cleanstr && ast_str_strlen(cleanstr) > 0) {
1486                                 ast_str_append(buffer, 0, ":%s", ast_str_buffer(cleanstr));
1487                         }
1488                         ast_free(cleanstr);
1489                 }
1490                 ast_str_append(buffer, 0, "\n");
1491         }
1492
1493         return ret;
1494 }
1495
1496 /*! \internal
1497  *  \brief Parse a <variablelist> node and put all the output inside 'buffer'.
1498  *  \param node The variablelist node pointer.
1499  *  \param tabs A string to be appended at the begining of the output that will be stored
1500  *         in buffer.
1501  *  \param buffer This must be an already created ast_str. It will be used
1502  *         to store the result (if already has something it will be appended to the current
1503  *         string).
1504  *  \retval 1 If a <variablelist> element is parsed.
1505  *  \retval 0 On error.
1506  */
1507 static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
1508 {
1509         struct ast_xml_node *tmp;
1510         const char *varname;
1511         char *vartabs;
1512         int ret = 0;
1513
1514         if (!node || !ast_xml_node_get_children(node)) {
1515                 return ret;
1516         }
1517
1518         if (strcasecmp(ast_xml_node_get_name(node), "variablelist")) {
1519                 return ret;
1520         }
1521
1522         /* use this spacing (add 4 spaces) inside a variablelist node. */
1523         if (ast_asprintf(&vartabs, "%s    ", tabs) < 0) {
1524                 return ret;
1525         }
1526         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1527                 /* We can have a <para> element inside the variable list */
1528                 if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
1529                         ret = 1;
1530                         continue;
1531                 }
1532
1533                 if (!strcasecmp(ast_xml_node_get_name(tmp), "variable")) {
1534                         /* Store the variable name in buffer. */
1535                         varname = ast_xml_get_attribute(tmp, "name");
1536                         if (varname) {
1537                                 ast_str_append(buffer, 0, "%s<variable>%s</variable>: ", tabs, varname);
1538                                 ast_xml_free_attr(varname);
1539                                 /* Parse the <variable> possible values. */
1540                                 xmldoc_parse_variable(tmp, vartabs, buffer);
1541                                 ret = 1;
1542                         }
1543                 }
1544         }
1545
1546         ast_free(vartabs);
1547
1548         return ret;
1549 }
1550
1551 /*!
1552  * \internal
1553  * \brief Build seealso information for an item
1554  * \param node  The seealso node to parse
1555  *
1556  * \note This method exists for when you already have the node.  This
1557  * prevents having to lock the documentation tree twice
1558  *
1559  * \returns A malloc'd character pointer to the seealso information of the item
1560  * \returns NULL on failure
1561  *
1562  * \since 11
1563  */
1564 static char *_ast_xmldoc_build_seealso(struct ast_xml_node *node)
1565 {
1566         char *output;
1567         struct ast_str *outputstr;
1568         const char *typename;
1569         const char *content;
1570         int first = 1;
1571
1572         /* Find the <see-also> node. */
1573         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1574                 if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
1575                         break;
1576                 }
1577         }
1578
1579         if (!node || !ast_xml_node_get_children(node)) {
1580                 /* we couldnt find a <see-also> node. */
1581                 return NULL;
1582         }
1583
1584         /* prepare the output string. */
1585         outputstr = ast_str_create(128);
1586         if (!outputstr) {
1587                 return NULL;
1588         }
1589
1590         /* get into the <see-also> node. */
1591         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1592                 if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
1593                         continue;
1594                 }
1595
1596                 /* parse the <ref> node. 'type' attribute is required. */
1597                 typename = ast_xml_get_attribute(node, "type");
1598                 if (!typename) {
1599                         continue;
1600                 }
1601                 content = ast_xml_get_text(node);
1602                 if (!content) {
1603                         ast_xml_free_attr(typename);
1604                         continue;
1605                 }
1606                 if (!strcasecmp(typename, "application")) {
1607                         ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
1608                 } else if (!strcasecmp(typename, "function")) {
1609                         ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1610                 } else if (!strcasecmp(typename, "astcli")) {
1611                         ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
1612                 } else {
1613                         ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1614                 }
1615                 first = 0;
1616                 ast_xml_free_text(content);
1617                 ast_xml_free_attr(typename);
1618         }
1619
1620         output = ast_strdup(ast_str_buffer(outputstr));
1621         ast_free(outputstr);
1622
1623         return output;
1624 }
1625
1626 char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
1627 {
1628         char *output;
1629         struct ast_xml_node *node;
1630
1631         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1632                 return NULL;
1633         }
1634
1635         /* get the application/function root node. */
1636         node = xmldoc_get_node(type, name, module, documentation_language);
1637         if (!node || !ast_xml_node_get_children(node)) {
1638                 return NULL;
1639         }
1640
1641         output = _ast_xmldoc_build_seealso(node);
1642
1643         return output;
1644 }
1645
1646 /*! \internal
1647  *  \brief Parse a <enum> node.
1648  *  \brief fixnode An ast_xml_node pointer to the <enum> node.
1649  *  \bried buffer The output buffer.
1650  *  \retval 0 if content is not found inside the enum element (data is not appended to buffer).
1651  *  \retval 1 if content is found and data is appended to buffer.
1652  */
1653 static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1654 {
1655         struct ast_xml_node *node = fixnode;
1656         int ret = 0;
1657         char *optiontabs;
1658
1659         if (ast_asprintf(&optiontabs, "%s    ", tabs) < 0) {
1660                 return ret;
1661         }
1662
1663         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1664                 if (xmldoc_parse_common_elements(node, (ret ? tabs : " - "), "\n", buffer)) {
1665                         ret = 1;
1666                 }
1667
1668                 xmldoc_parse_enumlist(node, optiontabs, buffer);
1669         }
1670
1671         ast_free(optiontabs);
1672
1673         return ret;
1674 }
1675
1676 /*! \internal
1677  *  \brief Parse a <enumlist> node.
1678  *  \param fixnode As ast_xml pointer to the <enumlist> node.
1679  *  \param buffer The ast_str output buffer.
1680  *  \retval 0 if no <enumlist> node was parsed.
1681  *  \retval 1 if a <enumlist> node was parsed.
1682  */
1683 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1684 {
1685         struct ast_xml_node *node = fixnode;
1686         const char *enumname;
1687         int ret = 0;
1688
1689         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1690                 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
1691                         continue;
1692                 }
1693
1694                 enumname = ast_xml_get_attribute(node, "name");
1695                 if (enumname) {
1696                         ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
1697                         ast_xml_free_attr(enumname);
1698
1699                         /* parse only enum elements inside a enumlist node. */
1700                         if ((xmldoc_parse_enum(node, tabs, buffer))) {
1701                                 ret = 1;
1702                         } else {
1703                                 ast_str_append(buffer, 0, "\n");
1704                         }
1705                 }
1706         }
1707         return ret;
1708 }
1709
1710 /*! \internal
1711  *  \brief Parse an <option> node.
1712  *  \param fixnode An ast_xml pointer to the <option> node.
1713  *  \param tabs A string to be appended at the begining of each line being added to the
1714  *              buffer string.
1715  *  \param buffer The output buffer.
1716  *  \retval 0 if no option node is parsed.
1717  *  \retval 1 if an option node is parsed.
1718  */
1719 static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1720 {
1721         struct ast_xml_node *node;
1722         int ret = 0;
1723         char *optiontabs;
1724
1725         if (ast_asprintf(&optiontabs, "%s    ", tabs) < 0) {
1726                 return ret;
1727         }
1728         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
1729                 if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1730                         /* if this is the first data appended to buffer, print a \n*/
1731                         if (!ret && ast_xml_node_get_children(node)) {
1732                                 /* print \n */
1733                                 ast_str_append(buffer, 0, "\n");
1734                         }
1735                         if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
1736                                 ret = 1;
1737                         }
1738                         continue;
1739                 }
1740
1741                 if (xmldoc_parse_common_elements(node, (ret ? tabs :  ""), "\n", buffer)) {
1742                         ret = 1;
1743                 }
1744
1745                 xmldoc_parse_variablelist(node, optiontabs, buffer);
1746
1747                 xmldoc_parse_enumlist(node, optiontabs, buffer);
1748         }
1749         ast_free(optiontabs);
1750
1751         return ret;
1752 }
1753
1754 /*! \internal
1755  *  \brief Parse an <optionlist> element from the xml documentation.
1756  *  \param fixnode Pointer to the optionlist xml node.
1757  *  \param tabs A string to be appended at the begining of each line being added to the
1758  *              buffer string.
1759  *  \param buffer Output buffer to put what is inside the optionlist tag.
1760  */
1761 static void xmldoc_parse_optionlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1762 {
1763         struct ast_xml_node *node;
1764         const char *optname, *hasparams;
1765         char *optionsyntax;
1766         int optparams;
1767
1768         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
1769                 /* Start appending every option tag. */
1770                 if (strcasecmp(ast_xml_node_get_name(node), "option")) {
1771                         continue;
1772                 }
1773
1774                 /* Get the option name. */
1775                 optname = ast_xml_get_attribute(node, "name");
1776                 if (!optname) {
1777                         continue;
1778                 }
1779
1780                 optparams = 1;
1781                 hasparams = ast_xml_get_attribute(node, "hasparams");
1782                 if (hasparams && !strcasecmp(hasparams, "optional")) {
1783                         optparams = 2;
1784                 }
1785
1786                 optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
1787                 if (!optionsyntax) {
1788                         ast_xml_free_attr(optname);
1789                         ast_xml_free_attr(hasparams);
1790                         continue;
1791                 }
1792
1793                 ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
1794
1795                 if (!xmldoc_parse_option(node, tabs, buffer)) {
1796                         ast_str_append(buffer, 0, "\n");
1797                 }
1798                 ast_str_append(buffer, 0, "\n");
1799                 ast_xml_free_attr(optname);
1800                 ast_xml_free_attr(hasparams);
1801                 ast_free(optionsyntax);
1802         }
1803 }
1804
1805 /*! \internal
1806  *  \brief Parse a 'parameter' tag inside a syntax element.
1807  *  \param fixnode A pointer to the 'parameter' xml node.
1808  *  \param tabs A string to be appended at the beginning of each line being printed inside
1809  *              'buffer'.
1810  *  \param buffer String buffer to put values found inside the parameter element.
1811  */
1812 static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1813 {
1814         const char *paramname;
1815         struct ast_xml_node *node = fixnode;
1816         int hasarguments, printed = 0;
1817         char *internaltabs;
1818
1819         if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
1820                 return;
1821         }
1822
1823         hasarguments = xmldoc_has_inside(node, "argument");
1824         if (!(paramname = ast_xml_get_attribute(node, "name"))) {
1825                 /* parameter MUST have an attribute name. */
1826                 return;
1827         }
1828
1829         if (ast_asprintf(&internaltabs, "%s    ", tabs) < 0) {
1830                 ast_xml_free_attr(paramname);
1831                 return;
1832         }
1833
1834         if (!hasarguments && xmldoc_has_nodes(node)) {
1835                 ast_str_append(buffer, 0, "%s\n", paramname);
1836                 ast_xml_free_attr(paramname);
1837                 printed = 1;
1838         }
1839
1840         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1841                 if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
1842                         xmldoc_parse_optionlist(node, internaltabs, buffer);
1843                 } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
1844                         xmldoc_parse_enumlist(node, internaltabs, buffer);
1845                 } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1846                         xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? "        " : ""), buffer);
1847                 } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
1848                         if (!printed) {
1849                                 ast_str_append(buffer, 0, "%s\n", paramname);
1850                                 ast_xml_free_attr(paramname);
1851                                 printed = 1;
1852                         }
1853                         if (xmldoc_parse_para(node, internaltabs, "\n", buffer)) {
1854                                 /* If anything ever goes in below this condition before the continue below,
1855                                  * we should probably continue immediately. */
1856                                 continue;
1857                         }
1858                         continue;
1859                 } else if (!strcasecmp(ast_xml_node_get_name(node), "info")) {
1860                         if (!printed) {
1861                                 ast_str_append(buffer, 0, "%s\n", paramname);
1862                                 ast_xml_free_attr(paramname);
1863                                 printed = 1;
1864                         }
1865                         if (xmldoc_parse_info(node, internaltabs, "\n", buffer)) {
1866                                 /* If anything ever goes in below this condition before the continue below,
1867                                  * we should probably continue immediately. */
1868                                 continue;
1869                         }
1870                         continue;
1871                 } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
1872                         continue;
1873                 }
1874         }
1875         if (!printed) {
1876                 ast_xml_free_attr(paramname);
1877         }
1878         ast_free(internaltabs);
1879 }
1880
1881 /*!
1882  * \internal
1883  * \brief Build the arguments for an item
1884  * \param node  The arguments node to parse
1885  *
1886  * \note This method exists for when you already have the node.  This
1887  * prevents having to lock the documentation tree twice
1888  *
1889  * \returns A malloc'd character pointer to the arguments for the item
1890  * \returns NULL on failure
1891  *
1892  * \since 11
1893  */
1894 static char *_ast_xmldoc_build_arguments(struct ast_xml_node *node)
1895 {
1896         char *retstr = NULL;
1897         struct ast_str *ret;
1898
1899         ret = ast_str_create(128);
1900         if (!ret) {
1901                 return NULL;
1902         }
1903
1904         /* Find the syntax field. */
1905         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1906                 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1907                         break;
1908                 }
1909         }
1910
1911         if (!node || !ast_xml_node_get_children(node)) {
1912                 /* We couldn't find the syntax node. */
1913                 ast_free(ret);
1914                 return NULL;
1915         }
1916
1917         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1918                 xmldoc_parse_parameter(node, "", &ret);
1919         }
1920
1921         if (ast_str_strlen(ret) > 0) {
1922                 /* remove last '\n' */
1923                 char *buf = ast_str_buffer(ret);
1924                 if (buf[ast_str_strlen(ret) - 1] == '\n') {
1925                         ast_str_truncate(ret, -1);
1926                 }
1927                 retstr = ast_strdup(ast_str_buffer(ret));
1928         }
1929         ast_free(ret);
1930
1931         return retstr;
1932 }
1933
1934 char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module)
1935 {
1936         struct ast_xml_node *node;
1937
1938         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1939                 return NULL;
1940         }
1941
1942         node = xmldoc_get_node(type, name, module, documentation_language);
1943
1944         if (!node || !ast_xml_node_get_children(node)) {
1945                 return NULL;
1946         }
1947
1948         return _ast_xmldoc_build_arguments(node);
1949 }
1950
1951 /*! \internal
1952  *  \brief Return the string within a node formatted with <para> and <variablelist> elements.
1953  *  \param node Parent node where content resides.
1954  *  \param raw If set, return the node's content without further processing.
1955  *  \param raw_wrap Wrap raw text.
1956  *  \retval NULL on error
1957  *  \retval Node content on success.
1958  */
1959 static struct ast_str *xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
1960 {
1961         struct ast_xml_node *tmp;
1962         const char *notcleanret, *tmpstr;
1963         struct ast_str *ret;
1964
1965         if (raw_output) {
1966                 /* xmldoc_string_cleanup will allocate the ret object */
1967                 notcleanret = ast_xml_get_text(node);
1968                 tmpstr = notcleanret;
1969                 xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0);
1970                 ast_xml_free_text(tmpstr);
1971         } else {
1972                 ret = ast_str_create(128);
1973                 for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1974                         /* if found, parse a <para> element. */
1975                         if (xmldoc_parse_common_elements(tmp, "", "\n", &ret)) {
1976                                 continue;
1977                         }
1978                         /* if found, parse a <variablelist> element. */
1979                         xmldoc_parse_variablelist(tmp, "", &ret);
1980                         xmldoc_parse_enumlist(tmp, "    ", &ret);
1981                 }
1982                 /* remove last '\n' */
1983                 /* XXX Don't modify ast_str internals manually */
1984                 tmpstr = ast_str_buffer(ret);
1985                 if (tmpstr[ast_str_strlen(ret) - 1] == '\n') {
1986                         ast_str_truncate(ret, -1);
1987                 }
1988         }
1989         return ret;
1990 }
1991
1992 /*!
1993  *  \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree node
1994  *  \param node The node to obtain the information from
1995  *  \param var Name of field to return (synopsis, description, etc).
1996  *  \param raw Field only contains text, no other elements inside it.
1997  *  \retval NULL On error.
1998  *  \retval Field text content on success.
1999  *  \since 11
2000  */
2001 static char *_xmldoc_build_field(struct ast_xml_node *node, const char *var, int raw)
2002 {
2003         char *ret = NULL;
2004         struct ast_str *formatted;
2005
2006         node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
2007
2008         if (!node || !ast_xml_node_get_children(node)) {
2009                 ast_debug(1, "Cannot find variable '%s' in tree\n", var);
2010                 return ret;
2011         }
2012
2013         formatted = xmldoc_get_formatted(node, raw, raw);
2014         if (ast_str_strlen(formatted) > 0) {
2015                 ret = ast_strdup(ast_str_buffer(formatted));
2016         }
2017         ast_free(formatted);
2018
2019         return ret;
2020 }
2021
2022 /*!
2023  * \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
2024  * \param type Type of element (application, function, ...).
2025  * \param name Name of element (Dial, Echo, Playback, ...).
2026  * \param var Name of field to return (synopsis, description, etc).
2027  * \param module
2028  * \param raw Field only contains text, no other elements inside it.
2029  * \retval NULL On error.
2030  * \retval Field text content on success.
2031  */
2032 static char *xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
2033 {
2034         struct ast_xml_node *node;
2035
2036         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2037                 ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
2038                 return NULL;
2039         }
2040
2041         node = xmldoc_get_node(type, name, module, documentation_language);
2042
2043         if (!node) {
2044                 ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation\n", type, name);
2045                 return NULL;
2046         }
2047
2048         return _xmldoc_build_field(node, var, raw);
2049 }
2050
2051 /* \internal
2052  * \brief Build the synopsis for an item
2053  * \param node The synopsis node
2054  *
2055  * \note This method exists for when you already have the node.  This
2056  * prevents having to lock the documentation tree twice
2057  *
2058  * \returns A malloc'd character pointer to the synopsis information
2059  * \returns NULL on failure
2060  * \since 11
2061  */
2062 static char *_ast_xmldoc_build_synopsis(struct ast_xml_node *node)
2063 {
2064         return _xmldoc_build_field(node, "synopsis", 1);
2065 }
2066
2067 char *ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
2068 {
2069         return xmldoc_build_field(type, name, module, "synopsis", 1);
2070 }
2071
2072 /*!
2073  * \internal
2074  * \brief Build the descripton for an item
2075  * \param node  The description node to parse
2076  *
2077  * \note This method exists for when you already have the node.  This
2078  * prevents having to lock the documentation tree twice
2079  *
2080  * \returns A malloc'd character pointer to the arguments for the item
2081  * \returns NULL on failure
2082  * \since 11
2083  */
2084 static char *_ast_xmldoc_build_description(struct ast_xml_node *node)
2085 {
2086         return _xmldoc_build_field(node, "description", 0);
2087 }
2088
2089 char *ast_xmldoc_build_description(const char *type, const char *name, const char *module)
2090 {
2091         return xmldoc_build_field(type, name, module, "description", 0);
2092 }
2093
2094 /*! \internal \brief ast_xml_doc_item ao2 destructor
2095  * \since 11
2096  */
2097 static void ast_xml_doc_item_destructor(void *obj)
2098 {
2099         struct ast_xml_doc_item *doc = obj;
2100
2101         if (!doc) {
2102                 return;
2103         }
2104
2105         ast_free(doc->syntax);
2106         ast_free(doc->seealso);
2107         ast_free(doc->arguments);
2108         ast_free(doc->synopsis);
2109         ast_free(doc->description);
2110         ast_string_field_free_memory(doc);
2111
2112         if (doc->next) {
2113                 ao2_ref(doc->next, -1);
2114                 doc->next = NULL;
2115         }
2116 }
2117
2118 /*! \internal
2119  * \brief Create an ao2 ref counted ast_xml_doc_item
2120  * \param name The name of the item
2121  * \param type The item's source type
2122  * \since 11
2123  */
2124 static struct ast_xml_doc_item *ast_xml_doc_item_alloc(const char *name, const char *type)
2125 {
2126         struct ast_xml_doc_item *item;
2127
2128         if (!(item = ao2_alloc(sizeof(*item), ast_xml_doc_item_destructor))) {
2129                 ast_log(AST_LOG_ERROR, "Failed to allocate memory for ast_xml_doc_item instance\n");
2130                 return NULL;
2131         }
2132
2133         if (   !(item->syntax = ast_str_create(128))
2134                 || !(item->seealso = ast_str_create(128))
2135                 || !(item->arguments = ast_str_create(128))
2136                 || !(item->synopsis = ast_str_create(128))
2137                 || !(item->description = ast_str_create(128))) {
2138                 ast_log(AST_LOG_ERROR, "Failed to allocate strings for ast_xml_doc_item instance\n");
2139                 goto ast_xml_doc_item_failure;
2140         }
2141
2142         if (ast_string_field_init(item, 64)) {
2143                 ast_log(AST_LOG_ERROR, "Failed to initialize string field for ast_xml_doc_item instance\n");
2144                 goto ast_xml_doc_item_failure;
2145         }
2146         ast_string_field_set(item, name, name);
2147         ast_string_field_set(item, type, type);
2148
2149         return item;
2150
2151 ast_xml_doc_item_failure:
2152         ao2_ref(item, -1);
2153         return NULL;
2154 }
2155
2156 /*! \internal
2157  * \brief ao2 item hash function for ast_xml_doc_item
2158  * \since 11
2159  */
2160 static int ast_xml_doc_item_hash(const void *obj, const int flags)
2161 {
2162         const struct ast_xml_doc_item *item = obj;
2163         const char *name = (flags & OBJ_KEY) ? obj : item->name;
2164         return ast_str_case_hash(name);
2165 }
2166
2167 /*! \internal
2168  * \brief ao2 item comparison function for ast_xml_doc_item
2169  * \since 11
2170  */
2171 static int ast_xml_doc_item_cmp(void *obj, void *arg, int flags)
2172 {
2173         struct ast_xml_doc_item *left = obj;
2174         struct ast_xml_doc_item *right = arg;
2175         const char *match = (flags & OBJ_KEY) ? arg : right->name;
2176         return strcasecmp(left->name, match) ? 0 : (CMP_MATCH | CMP_STOP);
2177 }
2178
2179 /* \internal
2180  * \brief Build an XML documentation item
2181  * \param node The root node for the item
2182  * \param name The name of the item
2183  * \param type The item's source type
2184  *
2185  * \returns NULL on failure
2186  * \returns An ao2 ref counted object
2187  * \since 11
2188  */
2189 static struct ast_xml_doc_item *xmldoc_build_documentation_item(struct ast_xml_node *node, const char *name, const char *type)
2190 {
2191         struct ast_xml_doc_item *item;
2192         char *syntax;
2193         char *seealso;
2194         char *arguments;
2195         char *synopsis;
2196         char *description;
2197
2198         if (!(item = ast_xml_doc_item_alloc(name, type))) {
2199                 return NULL;
2200         }
2201
2202         syntax = _ast_xmldoc_build_syntax(node, type, name);
2203         seealso = _ast_xmldoc_build_seealso(node);
2204         arguments = _ast_xmldoc_build_arguments(node);
2205         synopsis = _ast_xmldoc_build_synopsis(node);
2206         description = _ast_xmldoc_build_description(node);
2207
2208         if (syntax) {
2209                 ast_str_set(&item->syntax, 0, "%s", syntax);
2210         }
2211         if (seealso) {
2212                 ast_str_set(&item->seealso, 0, "%s", seealso);
2213         }
2214         if (arguments) {
2215                 ast_str_set(&item->arguments, 0, "%s", arguments);
2216         }
2217         if (synopsis) {
2218                 ast_str_set(&item->synopsis, 0, "%s", synopsis);
2219         }
2220         if (description) {
2221                 ast_str_set(&item->description, 0, "%s", description);
2222         }
2223
2224         ast_free(syntax);
2225         ast_free(seealso);
2226         ast_free(arguments);
2227         ast_free(synopsis);
2228         ast_free(description);
2229
2230         return item;
2231 }
2232
2233 struct ao2_container *ast_xmldoc_build_documentation(const char *type)
2234 {
2235         struct ao2_container *docs;
2236         struct ast_xml_doc_item *item = NULL, *root = NULL;
2237         struct ast_xml_node *node = NULL, *instance = NULL;
2238         struct documentation_tree *doctree;
2239         const char *name;
2240
2241         if (!(docs = ao2_container_alloc(127, ast_xml_doc_item_hash, ast_xml_doc_item_cmp))) {
2242                 ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
2243                 return NULL;
2244         }
2245
2246         AST_RWLIST_RDLOCK(&xmldoc_tree);
2247         AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2248                 /* the core xml documents have priority over thirdparty document. */
2249                 node = ast_xml_get_root(doctree->doc);
2250                 if (!node) {
2251                         break;
2252                 }
2253
2254                 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
2255                         /* Ignore empty nodes or nodes that aren't of the type requested */
2256                         if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), type)) {
2257                                 continue;
2258                         }
2259                         name = ast_xml_get_attribute(node, "name");
2260                         if (!name) {
2261                                 continue;
2262                         }
2263
2264                         switch (xmldoc_get_syntax_type(type)) {
2265                         case MANAGER_EVENT_SYNTAX:
2266                                 for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
2267                                         struct ast_xml_doc_item *temp;
2268                                         if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
2269                                                 continue;
2270                                         }
2271                                         temp = xmldoc_build_documentation_item(instance, name, type);
2272                                         if (!temp) {
2273                                                 break;
2274                                         }
2275                                         if (!item) {
2276                                                 item = temp;
2277                                                 root = item;
2278                                         } else {
2279                                                 item->next = temp;
2280                                                 item = temp;
2281                                         }
2282                                 }
2283                                 item = root;
2284                                 break;
2285                         default:
2286                                 item = xmldoc_build_documentation_item(node, name, type);
2287                         }
2288                         ast_xml_free_attr(name);
2289
2290                         if (item) {
2291                                 ao2_link(docs, item);
2292                                 ao2_t_ref(item, -1, "Dispose of creation ref");
2293                                 item = NULL;
2294                         }
2295                 }
2296         }
2297         AST_RWLIST_UNLOCK(&xmldoc_tree);
2298
2299         return docs;
2300 }
2301
2302 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
2303 static int xml_pathmatch(char *xmlpattern, int xmlpattern_maxlen, glob_t *globbuf)
2304 {
2305         int globret;
2306
2307         snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/thirdparty/*-%s.xml",
2308                 ast_config_AST_DATA_DIR, documentation_language);
2309         if((globret = glob(xmlpattern, GLOB_NOCHECK, NULL, globbuf))) {
2310                 return globret;
2311         }
2312
2313         snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/thirdparty/*-%.2s_??.xml",
2314                 ast_config_AST_DATA_DIR, documentation_language);
2315         if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
2316                 return globret;
2317         }
2318
2319         snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/thirdparty/*-%s.xml",
2320                 ast_config_AST_DATA_DIR, default_documentation_language);
2321         if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
2322                 return globret;
2323         }
2324
2325         snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/*-%s.xml",
2326                 ast_config_AST_DATA_DIR, documentation_language);
2327         if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
2328                 return globret;
2329         }
2330
2331         snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/*-%.2s_??.xml",
2332                 ast_config_AST_DATA_DIR, documentation_language);
2333         if((globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf))) {
2334                 return globret;
2335         }
2336
2337         snprintf(xmlpattern, xmlpattern_maxlen, "%s/documentation/*-%s.xml",
2338                 ast_config_AST_DATA_DIR, default_documentation_language);
2339         globret = glob(xmlpattern, GLOB_APPEND | GLOB_NOCHECK, NULL, globbuf);
2340
2341         return globret;
2342 }
2343 #endif
2344
2345 /*! \brief Close and unload XML documentation. */
2346 static void xmldoc_unload_documentation(void)
2347 {
2348         struct documentation_tree *doctree;
2349
2350         AST_RWLIST_WRLOCK(&xmldoc_tree);
2351         while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
2352                 ast_free(doctree->filename);
2353                 ast_xml_close(doctree->doc);
2354                 ast_free(doctree);
2355         }
2356         AST_RWLIST_UNLOCK(&xmldoc_tree);
2357
2358         ast_xml_finish();
2359 }
2360
2361 int ast_xmldoc_load_documentation(void)
2362 {
2363         struct ast_xml_node *root_node;
2364         struct ast_xml_doc *tmpdoc;
2365         struct documentation_tree *doc_tree;
2366         char *xmlpattern;
2367         struct ast_config *cfg = NULL;
2368         struct ast_variable *var = NULL;
2369         struct ast_flags cnfflags = { 0 };
2370         int globret, i, dup, duplicate;
2371         glob_t globbuf;
2372 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
2373         int xmlpattern_maxlen;
2374 #endif
2375
2376         /* setup default XML documentation language */
2377         snprintf(documentation_language, sizeof(documentation_language), default_documentation_language);
2378
2379         if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
2380                 for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
2381                         if (!strcasecmp(var->name, "documentation_language")) {
2382                                 if (!ast_strlen_zero(var->value)) {
2383                                         snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
2384                                 }
2385                         }
2386                 }
2387                 ast_config_destroy(cfg);
2388         }
2389
2390         /* initialize the XML library. */
2391         ast_xml_init();
2392
2393         /* register function to be run when asterisk finish. */
2394         ast_register_atexit(xmldoc_unload_documentation);
2395
2396         globbuf.gl_offs = 0;    /* slots to reserve in gl_pathv */
2397
2398 #if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
2399         xmlpattern_maxlen = strlen(ast_config_AST_DATA_DIR) + strlen("/documentation/thirdparty") + strlen("/*-??_??.xml") + 1;
2400         xmlpattern = ast_malloc(xmlpattern_maxlen);
2401         globret = xml_pathmatch(xmlpattern, xmlpattern_maxlen, &globbuf);
2402 #else
2403         /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
2404         if (ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
2405                 documentation_language, documentation_language, default_documentation_language) < 0) {
2406                 return 1;
2407         }
2408         globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
2409 #endif
2410
2411         ast_debug(3, "gl_pathc %zd\n", globbuf.gl_pathc);
2412         if (globret == GLOB_NOSPACE) {
2413                 ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
2414                 ast_free(xmlpattern);
2415                 return 1;
2416         } else if (globret  == GLOB_ABORTED) {
2417                 ast_log(LOG_WARNING, "XML load failure, glob expansion of pattern '%s' failed: Read error\n", xmlpattern);
2418                 ast_free(xmlpattern);
2419                 return 1;
2420         }
2421         ast_free(xmlpattern);
2422
2423         AST_RWLIST_WRLOCK(&xmldoc_tree);
2424         /* loop over expanded files */
2425         for (i = 0; i < globbuf.gl_pathc; i++) {
2426                 /* check for duplicates (if we already [try to] open the same file. */
2427                 duplicate = 0;
2428                 for (dup = 0; dup < i; dup++) {
2429                         if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
2430                                 duplicate = 1;
2431                                 break;
2432                         }
2433                 }
2434                 if (duplicate || strchr(globbuf.gl_pathv[i], '*')) {
2435                 /* skip duplicates as well as pathnames not found
2436                  * (due to use of GLOB_NOCHECK in xml_pathmatch) */
2437                         continue;
2438                 }
2439                 tmpdoc = NULL;
2440                 tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
2441                 if (!tmpdoc) {
2442                         ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
2443                         continue;
2444                 }
2445                 /* Get doc root node and check if it starts with '<docs>' */
2446                 root_node = ast_xml_get_root(tmpdoc);
2447                 if (!root_node) {
2448                         ast_log(LOG_ERROR, "Error getting documentation root node\n");
2449                         ast_xml_close(tmpdoc);
2450                         continue;
2451                 }
2452                 /* Check root node name for malformed xmls. */
2453                 if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
2454                         ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
2455                         ast_xml_close(tmpdoc);
2456                         continue;
2457                 }
2458                 doc_tree = ast_calloc(1, sizeof(*doc_tree));
2459                 if (!doc_tree) {
2460                         ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
2461                         ast_xml_close(tmpdoc);
2462                         continue;
2463                 }
2464                 doc_tree->doc = tmpdoc;
2465                 doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
2466                 AST_RWLIST_INSERT_TAIL(&xmldoc_tree, doc_tree, entry);
2467         }
2468         AST_RWLIST_UNLOCK(&xmldoc_tree);
2469
2470         globfree(&globbuf);
2471
2472         return 0;
2473 }
2474
2475 #endif /* AST_XML_DOCS */
2476
2477