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