Fix checking for CONFIG_STATUS_FILEINVALID so that modules don't crash upon trying...
[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
24 #include "asterisk.h"
25
26 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
27
28 #include "asterisk/_private.h"
29 #include "asterisk/paths.h"
30 #include "asterisk/linkedlists.h"
31 #include "asterisk/strings.h"
32 #include "asterisk/config.h"
33 #include "asterisk/term.h"
34 #include "asterisk/xmldoc.h"
35
36 #ifdef AST_XML_DOCS
37
38 /*! \brief Default documentation language. */
39 static const char default_documentation_language[] = "en_US";
40
41 /*! \brief Number of columns to print when showing the XML documentation with a
42  *         'core show application/function *' CLI command. Used in text wrapping.*/
43 static const int xmldoc_text_columns = 74;
44
45 /*! \brief This is a value that we will use to let the wrapping mechanism move the cursor
46  *         backward and forward xmldoc_max_diff positions before cutting the middle of a
47  *         word, trying to find a space or a \n. */
48 static const int xmldoc_max_diff = 5;
49
50 /*! \brief XML documentation language. */
51 static char documentation_language[6];
52
53 /*! \brief XML documentation tree */
54 struct documentation_tree {
55         char *filename;                                 /*!< XML document filename. */
56         struct ast_xml_doc *doc;                        /*!< Open document pointer. */
57         AST_RWLIST_ENTRY(documentation_tree) entry;
58 };
59
60 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname);
61
62 /*!
63  * \brief Container of documentation trees
64  *
65  * \note A RWLIST is a sufficient container type to use here for now.
66  *       However, some changes will need to be made to implement ref counting
67  *       if reload support is added in the future.
68  */
69 static AST_RWLIST_HEAD_STATIC(xmldoc_tree, documentation_tree);
70
71 static const struct strcolorized_tags {
72         const char *init;      /*!< Replace initial tag with this string. */
73         const char *end;       /*!< Replace end tag with this string. */
74         const int colorfg;     /*!< Foreground color. */
75         const char *inittag;   /*!< Initial tag description. */
76         const char *endtag;    /*!< Ending tag description. */
77 } colorized_tags[] = {
78         { "<",  ">",  COLOR_GREEN,  "<replaceable>", "</replaceable>" },
79         { "\'", "\'", COLOR_BLUE,   "<literal>",     "</literal>" },
80         { "*",  "*",  COLOR_RED,    "<emphasis>",    "</emphasis>" },
81         { "\"", "\"", COLOR_YELLOW, "<filename>",    "</filename>" },
82         { "\"", "\"", COLOR_CYAN,   "<directory>",   "</directory>" },
83         { "${", "}",  COLOR_GREEN,  "<variable>",    "</variable>" },
84         { "",   "",   COLOR_BLUE,   "<value>",       "</value>" },
85         { "",   "",   COLOR_BLUE,   "<enum>",        "</enum>" },
86         { "\'", "\'", COLOR_GRAY,   "<astcli>",      "</astcli>" },
87
88         /* Special tags */
89         { "", "", COLOR_YELLOW, "<note>",   "</note>" },
90         { "", "", COLOR_RED,   "<warning>", "</warning>" }
91 };
92
93 static const struct strspecial_tags {
94         const char *tagname;            /*!< Special tag name. */
95         const char *init;               /*!< Print this at the beginning. */
96         const char *end;                /*!< Print this at the end. */
97 } special_tags[] = {
98         { "note",    "<note>NOTE:</note> ",             "" },
99         { "warning", "<warning>WARNING!!!:</warning> ", "" }
100 };
101
102 /*! \internal
103  *  \brief Calculate the space in bytes used by a format string
104  *         that will be passed to a sprintf function.
105  *  \param postbr The format string to use to calculate the length.
106  *  \retval The postbr length.
107  */
108 static int xmldoc_postbrlen(const char *postbr)
109 {
110         int postbrreallen = 0, i;
111         size_t postbrlen;
112
113         if (!postbr) {
114                 return 0;
115         }
116         postbrlen = strlen(postbr);
117         for (i = 0; i < postbrlen; i++) {
118                 if (postbr[i] == '\t') {
119                         postbrreallen += 8 - (postbrreallen % 8);
120                 } else {
121                         postbrreallen++;
122                 }
123         }
124         return postbrreallen;
125 }
126
127 /*! \internal
128  *  \brief Setup postbr to be used while wrapping the text.
129  *         Add to postbr array all the spaces and tabs at the beginning of text.
130  *  \param postbr output array.
131  *  \param len text array length.
132  *  \param text Text with format string before the actual string.
133  */
134 static void xmldoc_setpostbr(char *postbr, size_t len, const char *text)
135 {
136         int c, postbrlen = 0;
137
138         if (!text) {
139                 return;
140         }
141
142         for (c = 0; c < len; c++) {
143                 if (text[c] == '\t' || text[c] == ' ') {
144                         postbr[postbrlen++] = text[c];
145                 } else {
146                         break;
147                 }
148         }
149         postbr[postbrlen] = '\0';
150 }
151
152 /*! \internal
153  *  \brief Try to find a space or a break in text starting at currentpost
154  *         and moving at most maxdiff positions.
155  *         Helper for xmldoc_string_wrap().
156  *  \param text Input string where it will search.
157  *  \param currentpos Current position within text.
158  *  \param maxdiff Not move more than maxdiff inside text.
159  *  \retval 1 if a space or break is found inside text while moving.
160  *  \retval 0 if no space or break is found.
161  */
162 static int xmldoc_wait_nextspace(const char *text, int currentpos, int maxdiff)
163 {
164         int i, textlen;
165
166         if (!text) {
167                 return 0;
168         }
169
170         textlen = strlen(text);
171         for (i = currentpos; i < textlen; i++) {
172                 if (text[i] == ESC) {
173                         /* Move to the end of the escape sequence */
174                         while (i < textlen && text[i] != 'm') {
175                                 i++;
176                         }
177                 } else if (text[i] == ' ' || text[i] == '\n') {
178                         /* Found the next space or linefeed */
179                         return 1;
180                 } else if (i - currentpos > maxdiff) {
181                         /* We have looked the max distance and didn't find it */
182                         return 0;
183                 }
184         }
185
186         /* Reached the end and did not find it */
187
188         return 0;
189 }
190
191 /*! \internal
192  *  \brief Helper function for xmldoc_string_wrap().
193  *         Try to found a space or a break inside text moving backward
194  *         not more than maxdiff positions.
195  *  \param text The input string where to search for a space.
196  *  \param currentpos The current cursor position.
197  *  \param maxdiff The max number of positions to move within text.
198  *  \retval 0 If no space is found (Notice that text[currentpos] is not a space or a break)
199  *  \retval > 0 If a space or a break is found, and the result is the position relative to
200  *              currentpos.
201  */
202 static int xmldoc_foundspace_backward(const char *text, int currentpos, int maxdiff)
203 {
204         int i;
205
206         for (i = currentpos; i > 0; i--) {
207                 if (text[i] == ' ' || text[i] == '\n') {
208                         return (currentpos - i);
209                 } else if (text[i] == 'm' && (text[i - 1] >= '0' || text[i - 1] <= '9')) {
210                         /* give up, we found the end of a possible ESC sequence. */
211                         return 0;
212                 } else if (currentpos - i > maxdiff) {
213                         /* give up, we can't move anymore. */
214                         return 0;
215                 }
216         }
217
218         /* we found the beginning of the text */
219
220         return 0;
221 }
222
223 /*! \internal
224  *  \brief Justify a text to a number of columns.
225  *  \param text Input text to be justified.
226  *  \param columns Number of columns to preserve in the text.
227  *  \param maxdiff Try to not cut a word when goinf down.
228  *  \retval NULL on error.
229  *  \retval The wrapped text.
230  */
231 static char *xmldoc_string_wrap(const char *text, int columns, int maxdiff)
232 {
233         struct ast_str *tmp;
234         char *ret, postbr[160];
235         int count = 1, i, backspace, needtobreak = 0, colmax, textlen;
236
237         /* sanity check */
238         if (!text || columns <= 0 || maxdiff < 0) {
239                 ast_log(LOG_WARNING, "Passing wrong arguments while trying to wrap the text\n");
240                 return NULL;
241         }
242
243         tmp = ast_str_create(strlen(text) * 3);
244
245         if (!tmp) {
246                 return NULL;
247         }
248
249         /* Check for blanks and tabs and put them in postbr. */
250         xmldoc_setpostbr(postbr, sizeof(postbr), text);
251         colmax = columns - xmldoc_postbrlen(postbr);
252
253         textlen = strlen(text);
254         for (i = 0; i < textlen; i++) {
255                 if (needtobreak || !(count % colmax)) {
256                         if (text[i] == ' ') {
257                                 ast_str_append(&tmp, 0, "\n%s", postbr);
258                                 needtobreak = 0;
259                                 count = 1;
260                         } else if (text[i] != '\n') {
261                                 needtobreak = 1;
262                                 if (xmldoc_wait_nextspace(text, i, maxdiff)) {
263                                         /* wait for the next space */
264                                         ast_str_append(&tmp, 0, "%c", text[i]);
265                                         continue;
266                                 }
267                                 /* Try to look backwards */
268                                 backspace = xmldoc_foundspace_backward(text, i, maxdiff);
269                                 if (backspace) {
270                                         needtobreak = 1;
271                                         tmp->used -= backspace;
272                                         tmp->str[tmp->used] = '\0';
273                                         i -= backspace + 1;
274                                         continue;
275                                 }
276                                 ast_str_append(&tmp, 0, "\n%s", postbr);
277                                 needtobreak = 0;
278                                 count = 1;
279                         }
280                         /* skip blanks after a \n */
281                         while (text[i] == ' ') {
282                                 i++;
283                         }
284                 }
285                 if (text[i] == '\n') {
286                         xmldoc_setpostbr(postbr, sizeof(postbr), &text[i] + 1);
287                         colmax = columns - xmldoc_postbrlen(postbr);
288                         needtobreak = 0;
289                         count = 1;
290                 }
291                 if (text[i] == ESC) {
292                         /* Ignore Escape sequences. */
293                         do {
294                                 ast_str_append(&tmp, 0, "%c", text[i]);
295                                 i++;
296                         } while (i < textlen && text[i] != 'm');
297                 } else {
298                         count++;
299                 }
300                 ast_str_append(&tmp, 0, "%c", text[i]);
301         }
302
303         ret = ast_strdup(tmp->str);
304         ast_free(tmp);
305
306         return ret;
307 }
308
309 char *ast_xmldoc_printable(const char *bwinput, int withcolors)
310 {
311         struct ast_str *colorized;
312         char *wrapped = NULL;
313         int i, c, len, colorsection;
314         char *tmp;
315         size_t bwinputlen;
316         static const int base_fg = COLOR_CYAN;
317
318         if (!bwinput) {
319                 return NULL;
320         }
321
322         bwinputlen = strlen(bwinput);
323
324         if (!(colorized = ast_str_create(256))) {
325                 return NULL;
326         }
327
328         if (withcolors) {
329                 ast_term_color_code(&colorized, base_fg, 0);
330                 if (!colorized) {
331                         return NULL;
332                 }
333         }
334
335         for (i = 0; i < bwinputlen; i++) {
336                 colorsection = 0;
337                 /* Check if we are at the beginning of a tag to be colorized. */
338                 for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
339                         if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
340                                 continue;
341                         }
342
343                         if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
344                                 continue;
345                         }
346
347                         len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
348
349                         /* Setup color */
350                         if (withcolors) {
351                                 ast_term_color_code(&colorized, colorized_tags[c].colorfg, 0);
352                                 if (!colorized) {
353                                         return NULL;
354                                 }
355                         }
356
357                         /* copy initial string replace */
358                         ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
359                         if (!colorized) {
360                                 return NULL;
361                         }
362                         {
363                                 char buf[len + 1];
364                                 ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
365                                 ast_str_append(&colorized, 0, "%s", buf);
366                         }
367                         if (!colorized) {
368                                 return NULL;
369                         }
370
371                         /* copy the ending string replace */
372                         ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
373                         if (!colorized) {
374                                 return NULL;
375                         }
376
377                         /* Continue with the last color. */
378                         if (withcolors) {
379                                 ast_term_color_code(&colorized, base_fg, 0);
380                                 if (!colorized) {
381                                         return NULL;
382                                 }
383                         }
384
385                         i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
386                         colorsection = 1;
387                         break;
388                 }
389
390                 if (!colorsection) {
391                         ast_str_append(&colorized, 0, "%c", bwinput[i]);
392                         if (!colorized) {
393                                 return NULL;
394                         }
395                 }
396         }
397
398         if (withcolors) {
399                 ast_term_color_code(&colorized, COLOR_BRWHITE, 0);
400                 if (!colorized) {
401                         return NULL;
402                 }
403         }
404
405         /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
406         wrapped = xmldoc_string_wrap(colorized->str, xmldoc_text_columns, xmldoc_max_diff);
407
408         ast_free(colorized);
409
410         return wrapped;
411 }
412
413 /*! \internal
414  *  \brief Cleanup spaces and tabs after a \n
415  *  \param text String to be cleaned up.
416  *  \param output buffer (not already allocated).
417  *  \param lastspaces Remove last spaces in the string.
418  */
419 static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces)
420 {
421         int i;
422         size_t textlen;
423
424         if (!text) {
425                 *output = NULL;
426                 return;
427         }
428
429         textlen = strlen(text);
430
431         *output = ast_str_create(textlen);
432         if (!(*output)) {
433                 ast_log(LOG_ERROR, "Problem allocating output buffer\n");
434                 return;
435         }
436
437         for (i = 0; i < textlen; i++) {
438                 if (text[i] == '\n' || text[i] == '\r') {
439                         /* remove spaces/tabs/\n after a \n. */
440                         while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') {
441                                 i++;
442                         }
443                         ast_str_append(output, 0, " ");
444                         continue;
445                 } else {
446                         ast_str_append(output, 0, "%c", text[i]);
447                 }
448         }
449
450         /* remove last spaces (we dont want always to remove the trailing spaces). */
451         if (lastspaces) {
452                 ast_str_trim_blanks(*output);
453         }
454 }
455
456 /*! \internal
457  *  \brief Get the application/function node for 'name' application/function with language 'language'
458  *         if we don't find any, get the first application with 'name' no matter which language with.
459  *  \param type 'application', 'function', ...
460  *  \param name Application or Function name.
461  *  \param language Try to get this language (if not found try with en_US)
462  *  \retval NULL on error.
463  *  \retval A node of type ast_xml_node.
464  */
465 static struct ast_xml_node *xmldoc_get_node(const char *type, const char *name, const char *language)
466 {
467         struct ast_xml_node *node = NULL;
468         struct documentation_tree *doctree;
469         const char *lang;
470
471         AST_RWLIST_RDLOCK(&xmldoc_tree);
472         AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
473                 /* the core xml documents have priority over thirdparty document. */
474                 node = ast_xml_get_root(doctree->doc);
475                 while ((node = ast_xml_find_element(node, type, "name", name))) {
476                         /* Check language */
477                         lang = ast_xml_get_attribute(node, "language");
478                         if (lang && !strcmp(lang, language)) {
479                                 ast_xml_free_attr(lang);
480                                 break;
481                         } else if (lang) {
482                                 ast_xml_free_attr(lang);
483                         }
484                 }
485
486                 if (node && ast_xml_node_get_children(node)) {
487                         break;
488                 }
489
490                 /* We didn't find the application documentation for the specified language,
491                 so, try to load documentation for any language */
492                 node = ast_xml_get_root(doctree->doc);
493                 if (ast_xml_node_get_children(node)) {
494                         if ((node = ast_xml_find_element(ast_xml_node_get_children(node), type, "name", name))) {
495                                 break;
496                         }
497                 }
498         }
499         AST_RWLIST_UNLOCK(&xmldoc_tree);
500
501         return node;
502 }
503
504 /*! \internal
505  *  \brief Helper function used to build the syntax, it allocates the needed buffer (or reallocates it),
506  *         and based on the reverse value it makes use of fmt to print the parameter list inside the
507  *         realloced buffer (syntax).
508  *  \param reverse We are going backwards while generating the syntax?
509  *  \param len Current length of 'syntax' buffer.
510  *  \param syntax Output buffer for the concatenated values.
511  *  \param fmt A format string that will be used in a sprintf call.
512  */
513 static __attribute__((format(printf,4,5))) void xmldoc_reverse_helper(int reverse, int *len, char **syntax, const char *fmt, ...)
514 {
515         int totlen, tmpfmtlen;
516         char *tmpfmt, tmp;
517         va_list ap;
518
519         va_start(ap, fmt);
520         if (ast_vasprintf(&tmpfmt, fmt, ap) < 0) {
521                 va_end(ap);
522                 return;
523         }
524         va_end(ap);
525
526         tmpfmtlen = strlen(tmpfmt);
527         totlen = *len + tmpfmtlen + 1;
528
529         *syntax = ast_realloc(*syntax, totlen);
530
531         if (!*syntax) {
532                 ast_free(tmpfmt);
533                 return;
534         }
535
536         if (reverse) {
537                 memmove(*syntax + tmpfmtlen, *syntax, *len);
538                 /* Save this char, it will be overwritten by the \0 of strcpy. */
539                 tmp = (*syntax)[0];
540                 strcpy(*syntax, tmpfmt);
541                 /* Restore the already saved char. */
542                 (*syntax)[tmpfmtlen] = tmp;
543                 (*syntax)[totlen - 1] = '\0';
544         } else {
545                 strcpy(*syntax + *len, tmpfmt);
546         }
547
548         *len = totlen - 1;
549         ast_free(tmpfmt);
550 }
551
552 /*! \internal
553  *  \brief Check if the passed node has 'what' tags inside it.
554  *  \param node Root node to search 'what' elements.
555  *  \param what node name to search inside node.
556  *  \retval 1 If a <argument> element is found inside 'node'.
557  *  \retval 0 If no <argument> is found inside 'node'.
558  */
559 static int xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
560 {
561         struct ast_xml_node *node = fixnode;
562
563         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
564                 if (!strcasecmp(ast_xml_node_get_name(node), what)) {
565                         return 1;
566                 }
567         }
568         return 0;
569 }
570
571 /*! \internal
572  *  \brief Build the syntax for a specified starting node.
573  *  \param rootnode A pointer to the ast_xml root node.
574  *  \param rootname Name of the application, function, option, etc. to build the syntax.
575  *  \param childname The name of each parameter node.
576  *  \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
577  *  \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
578  *  \retval NULL on error.
579  *  \retval An ast_malloc'ed string with the syntax generated.
580  */
581 static char *xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
582 {
583 #define GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
584 #define ISLAST(__rev, __a)  (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
585 #define MP(__a) ((multiple ? __a : ""))
586         struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
587         const char *paramtype, *multipletype, *paramnameattr, *attrargsep, *parenthesis, *argname;
588         int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
589         int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis, multiple;
590         char *syntax = NULL, *argsep, *paramname;
591
592         if (ast_strlen_zero(rootname) || ast_strlen_zero(childname)) {
593                 ast_log(LOG_WARNING, "Tried to look in XML tree with faulty rootname or childname while creating a syntax.\n");
594                 return NULL;
595         }
596
597         if (!rootnode || !ast_xml_node_get_children(rootnode)) {
598                 /* If the rootnode field is not found, at least print name. */
599                 ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : ""));
600                 return syntax;
601         }
602
603         /* Get the argument separator from the root node attribute name 'argsep', if not found
604         defaults to ','. */
605         attrargsep = ast_xml_get_attribute(rootnode, "argsep");
606         if (attrargsep) {
607                 argsep = ast_strdupa(attrargsep);
608                 ast_xml_free_attr(attrargsep);
609         } else {
610                 argsep = ast_strdupa(",");
611         }
612
613         /* Get order of evaluation. */
614         for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
615                 if (strcasecmp(ast_xml_node_get_name(node), childname)) {
616                         continue;
617                 }
618                 required = 0;
619                 hasparams = 1;
620                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
621                         if (ast_true(paramtype)) {
622                                 required = 1;
623                         }
624                         ast_xml_free_attr(paramtype);
625                 }
626
627                 lastparam = node;
628                 reqlanode = required;
629
630                 if (!firstparam) {
631                         /* first parameter node */
632                         firstparam = node;
633                         reqfinode = required;
634                 }
635         }
636
637         if (!hasparams) {
638                 /* This application, function, option, etc, doesn't have any params. */
639                 ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : ""));
640                 return syntax;
641         }
642
643         if (reqfinode && reqlanode) {
644                 /* check midnode */
645                 for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
646                         if (strcasecmp(ast_xml_node_get_name(node), childname)) {
647                                 continue;
648                         }
649                         if (node != firstparam && node != lastparam) {
650                                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
651                                         if (!ast_true(paramtype)) {
652                                                 optmidnode = 1;
653                                                 break;
654                                         }
655                                         ast_xml_free_attr(paramtype);
656                                 }
657                         }
658                 }
659         }
660
661         if ((!reqfinode && reqlanode) || (reqfinode && reqlanode && optmidnode)) {
662                 reverse = 1;
663                 node = lastparam;
664         } else {
665                 reverse = 0;
666                 node = firstparam;
667         }
668
669         /* init syntax string. */
670         if (reverse) {
671                 xmldoc_reverse_helper(reverse, &len, &syntax,
672                         (printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
673         } else {
674                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
675                         (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
676         }
677
678         for (; node; node = GOTONEXT(reverse, node)) {
679                 if (strcasecmp(ast_xml_node_get_name(node), childname)) {
680                         continue;
681                 }
682
683                 /* Get the argument name, if it is not the leaf, go inside that parameter. */
684                 if (xmldoc_has_inside(node, "argument")) {
685                         parenthesis = ast_xml_get_attribute(node, "hasparams");
686                         prnparenthesis = 0;
687                         if (parenthesis) {
688                                 prnparenthesis = ast_true(parenthesis);
689                                 if (!strcasecmp(parenthesis, "optional")) {
690                                         prnparenthesis = 2;
691                                 }
692                                 ast_xml_free_attr(parenthesis);
693                         }
694                         argname = ast_xml_get_attribute(node, "name");
695                         if (argname) {
696                                 paramname = xmldoc_get_syntax_fun(node, argname, "argument", prnparenthesis, prnparenthesis);
697                                 ast_xml_free_attr(argname);
698                         } else {
699                                 /* Malformed XML, print **UNKOWN** */
700                                 paramname = ast_strdup("**unknown**");
701                         }
702                 } else {
703                         paramnameattr = ast_xml_get_attribute(node, "name");
704                         if (!paramnameattr) {
705                                 ast_log(LOG_WARNING, "Malformed XML %s: no %s name\n", rootname, childname);
706                                 if (syntax) {
707                                         /* Free already allocated syntax */
708                                         ast_free(syntax);
709                                 }
710                                 /* to give up is ok? */
711                                 ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : ""));
712                                 return syntax;
713                         }
714                         paramname = ast_strdup(paramnameattr);
715                         ast_xml_free_attr(paramnameattr);
716                 }
717
718                 /* Defaults to 'false'. */
719                 multiple = 0;
720                 if ((multipletype = ast_xml_get_attribute(node, "multiple"))) {
721                         if (ast_true(multipletype)) {
722                                 multiple = 1;
723                         }
724                         ast_xml_free_attr(multipletype);
725                 }
726
727                 required = 0;   /* Defaults to 'false'. */
728                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
729                         if (ast_true(paramtype)) {
730                                 required = 1;
731                         }
732                         ast_xml_free_attr(paramtype);
733                 }
734
735                 /* build syntax core. */
736
737                 if (required) {
738                         /* First parameter */
739                         if (!paramcount) {
740                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
741                         } else {
742                                 /* Time to close open brackets. */
743                                 while (openbrackets > 0) {
744                                         xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
745                                         openbrackets--;
746                                 }
747                                 if (reverse) {
748                                         xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", paramname, argsep);
749                                 } else {
750                                         xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", argsep, paramname);
751                                 }
752                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s", MP("["), MP(argsep), MP("...]"));
753                         }
754                 } else {
755                         /* First parameter */
756                         if (!paramcount) {
757                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]", paramname, MP("["), MP(argsep), MP("...]"));
758                         } else {
759                                 if (ISLAST(reverse, node)) {
760                                         /* This is the last parameter. */
761                                         if (reverse) {
762                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]%s", paramname,
763                                                                         MP("["), MP(argsep), MP("...]"), argsep);
764                                         } else {
765                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s[%s%s%s%s]", argsep, paramname,
766                                                                         MP("["), MP(argsep), MP("...]"));
767                                         }
768                                 } else {
769                                         if (reverse) {
770                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s%s]", paramname, argsep,
771                                                                         MP("["), MP(argsep), MP("...]"));
772                                         } else {
773                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s%s", argsep, paramname,
774                                                                         MP("["), MP(argsep), MP("...]"));
775                                         }
776                                         openbrackets++;
777                                 }
778                         }
779                 }
780                 ast_free(paramname);
781
782                 paramcount++;
783         }
784
785         /* Time to close open brackets. */
786         while (openbrackets > 0) {
787                 xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
788                 openbrackets--;
789         }
790
791         /* close syntax string. */
792         if (reverse) {
793                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
794                         (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
795         } else {
796                 xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
797         }
798
799         return syntax;
800 #undef ISLAST
801 #undef GOTONEXT
802 #undef MP
803 }
804
805 /*! \internal
806  *  \brief Parse an enumlist inside a <parameter> to generate a COMMAND
807  *         syntax.
808  *  \param fixnode A pointer to the <enumlist> node.
809  *  \retval {<unknown>} on error.
810  *  \retval A string inside brackets {} with the enum's separated by pipes |.
811  */
812 static char *xmldoc_parse_cmd_enumlist(struct ast_xml_node *fixnode)
813 {
814         struct ast_xml_node *node = fixnode;
815         struct ast_str *paramname;
816         char *enumname, *ret;
817         int first = 1;
818
819         paramname = ast_str_create(128);
820         if (!paramname) {
821                 return ast_strdup("{<unkown>}");
822         }
823
824         ast_str_append(&paramname, 0, "{");
825
826         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
827                 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
828                         continue;
829                 }
830
831                 enumname = xmldoc_get_syntax_cmd(node, "", 0);
832                 if (!enumname) {
833                         continue;
834                 }
835                 if (!first) {
836                         ast_str_append(&paramname, 0, "|");
837                 }
838                 ast_str_append(&paramname, 0, "%s", enumname);
839                 first = 0;
840                 ast_free(enumname);
841         }
842
843         ast_str_append(&paramname, 0, "}");
844
845         ret = ast_strdup(paramname->str);
846         ast_free(paramname);
847
848         return ret;
849 }
850
851 /*! \internal
852  *  \brief Generate a syntax of COMMAND type.
853  *  \param fixnode The <syntax> node pointer.
854  *  \param name The name of the 'command'.
855  *  \param printname Print the name of the command before the paramters?
856  *  \retval On error, return just 'name'.
857  *  \retval On success return the generated syntax.
858  */
859 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
860 {
861         struct ast_str *syntax;
862         struct ast_xml_node *tmpnode, *node = fixnode;
863         char *ret, *paramname;
864         const char *paramtype, *attrname, *literal;
865         int required, isenum, first = 1, isliteral;
866
867         syntax = ast_str_create(128);
868         if (!syntax) {
869                 /* at least try to return something... */
870                 return ast_strdup(name);
871         }
872
873         /* append name to output string. */
874         if (printname) {
875                 ast_str_append(&syntax, 0, "%s", name);
876                 first = 0;
877         }
878
879         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
880                 if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
881                         continue;
882                 }
883
884                 if (xmldoc_has_inside(node, "parameter")) {
885                         /* is this a recursive parameter. */
886                         paramname = xmldoc_get_syntax_cmd(node, "", 0);
887                         isenum = 1;
888                 } else if (!xmldoc_has_inside(node, "enumlist")) {
889                         /* this is a simple parameter. */
890                         attrname = ast_xml_get_attribute(node, "name");
891                         if (!attrname) {
892                                 /* ignore this bogus parameter and continue. */
893                                 continue;
894                         }
895                         paramname = ast_strdup(attrname);
896                         ast_xml_free_attr(attrname);
897                         isenum = 0;
898                 } else {
899                         /* parse enumlist (note that this is a special enumlist
900                         that is used to describe a syntax like {<param1>|<param2>|...} */
901                         for (tmpnode = ast_xml_node_get_children(node); tmpnode; tmpnode = ast_xml_node_get_next(tmpnode)) {
902                                 if (!strcasecmp(ast_xml_node_get_name(tmpnode), "enumlist")) {
903                                         break;
904                                 }
905                         }
906                         paramname = xmldoc_parse_cmd_enumlist(tmpnode);
907                         isenum = 1;
908                 }
909
910                 /* Is this parameter required? */
911                 required = 0;
912                 paramtype = ast_xml_get_attribute(node, "required");
913                 if (paramtype) {
914                         required = ast_true(paramtype);
915                         ast_xml_free_attr(paramtype);
916                 }
917
918                 /* Is this a replaceable value or a fixed parameter value? */
919                 isliteral = 0;
920                 literal = ast_xml_get_attribute(node, "literal");
921                 if (literal) {
922                         isliteral = ast_true(literal);
923                         ast_xml_free_attr(literal);
924                 }
925
926                 /* if required="false" print with [...].
927                  * if literal="true" or is enum print without <..>.
928                  * if not first print a space at the beginning.
929                  */
930                 ast_str_append(&syntax, 0, "%s%s%s%s%s%s",
931                                 (first ? "" : " "),
932                                 (required ? "" : "["),
933                                 (isenum || isliteral ? "" : "<"),
934                                 paramname,
935                                 (isenum || isliteral ? "" : ">"),
936                                 (required ? "" : "]"));
937                 first = 0;
938                 ast_free(paramname);
939         }
940
941         /* return a common string. */
942         ret = ast_strdup(syntax->str);
943         ast_free(syntax);
944
945         return ret;
946 }
947
948 /*! \brief Types of syntax that we are able to generate. */
949 enum syntaxtype {
950         FUNCTION_SYNTAX,
951         COMMAND_SYNTAX
952 };
953
954 /*! \brief Mapping between type of node and type of syntax to generate. */
955 struct strsyntaxtype {
956         const char *type;
957         enum syntaxtype stxtype;
958 } stxtype[] = {
959         { "function",           FUNCTION_SYNTAX },
960         { "application",        FUNCTION_SYNTAX },
961         { "agi",                COMMAND_SYNTAX  }
962 };
963
964 /*! \internal
965  *  \brief Get syntax type based on type of node.
966  *  \param type Type of node.
967  *  \retval The type of syntax to generate based on the type of node.
968  */
969 static enum syntaxtype xmldoc_get_syntax_type(const char *type)
970 {
971         int i;
972         for (i=0; i < ARRAY_LEN(stxtype); i++) {
973                 if (!strcasecmp(stxtype[i].type, type)) {
974                         return stxtype[i].stxtype;
975                 }
976         }
977
978         return FUNCTION_SYNTAX;
979 }
980
981 char *ast_xmldoc_build_syntax(const char *type, const char *name)
982 {
983         struct ast_xml_node *node;
984         char *syntax = NULL;
985
986         node = xmldoc_get_node(type, name, documentation_language);
987         if (!node) {
988                 return NULL;
989         }
990
991         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
992                 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
993                         break;
994                 }
995         }
996
997         if (node) {
998                 if (xmldoc_get_syntax_type(type) == FUNCTION_SYNTAX) {
999                         syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1000                 } else {
1001                         syntax = xmldoc_get_syntax_cmd(node, name, 1);
1002                 }
1003         }
1004         return syntax;
1005 }
1006
1007 /*! \internal
1008  *  \brief Parse a <para> element.
1009  *  \param node The <para> element pointer.
1010  *  \param tabs Added this string before the content of the <para> element.
1011  *  \param posttabs Added this string after the content of the <para> element.
1012  *  \param buffer This must be an already allocated ast_str. It will be used
1013  *         to store the result (if already has something it will be appended to the current
1014  *         string).
1015  *  \retval 1 If 'node' is a named 'para'.
1016  *  \retval 2 If data is appended in buffer.
1017  *  \retval 0 on error.
1018  */
1019 static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
1020 {
1021         const char *tmptext;
1022         struct ast_xml_node *tmp;
1023         int ret = 0;
1024         struct ast_str *tmpstr;
1025
1026         if (!node || !ast_xml_node_get_children(node)) {
1027                 return ret;
1028         }
1029
1030         if (strcasecmp(ast_xml_node_get_name(node), "para")) {
1031                 return ret;
1032         }
1033
1034         ast_str_append(buffer, 0, "%s", tabs);
1035
1036         ret = 1;
1037
1038         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1039                 /* Get the text inside the <para> element and append it to buffer. */
1040                 tmptext = ast_xml_get_text(tmp);
1041                 if (tmptext) {
1042                         /* Strip \n etc. */
1043                         xmldoc_string_cleanup(tmptext, &tmpstr, 0);
1044                         ast_xml_free_text(tmptext);
1045                         if (tmpstr) {
1046                                 if (strcasecmp(ast_xml_node_get_name(tmp), "text")) {
1047                                         ast_str_append(buffer, 0, "<%s>%s</%s>", ast_xml_node_get_name(tmp),
1048                                                         tmpstr->str, ast_xml_node_get_name(tmp));
1049                                 } else {
1050                                         ast_str_append(buffer, 0, "%s", tmpstr->str);
1051                                 }
1052                                 ast_free(tmpstr);
1053                                 ret = 2;
1054                         }
1055                 }
1056         }
1057
1058         ast_str_append(buffer, 0, "%s", posttabs);
1059
1060         return ret;
1061 }
1062
1063 /*! \internal
1064  *  \brief Parse special elements defined in 'struct special_tags' special elements must have a <para> element inside them.
1065  *  \param fixnode special tag node pointer.
1066  *  \param tabs put tabs before printing the node content.
1067  *  \param posttabs put posttabs after printing node content.
1068  *  \param buffer Output buffer, the special tags will be appended here.
1069  *  \retval 0 if no special element is parsed.
1070  *  \retval 1 if a special element is parsed (data is appended to buffer).
1071  *  \retval 2 if a special element is parsed and also a <para> element is parsed inside the specialtag.
1072  */
1073 static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
1074 {
1075         struct ast_xml_node *node = fixnode;
1076         int ret = 0, i, count = 0;
1077
1078         if (!node || !ast_xml_node_get_children(node)) {
1079                 return ret;
1080         }
1081
1082         for (i = 0; i < ARRAY_LEN(special_tags); i++) {
1083                 if (strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
1084                         continue;
1085                 }
1086
1087                 ret = 1;
1088                 /* This is a special tag. */
1089
1090                 /* concat data */
1091                 if (!ast_strlen_zero(special_tags[i].init)) {
1092                         ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init);
1093                 }
1094
1095                 /* parse <para> elements inside special tags. */
1096                 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1097                         /* first <para> just print it without tabs at the begining. */
1098                         if (xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2) {
1099                                 ret = 2;
1100                         }
1101                 }
1102
1103                 if (!ast_strlen_zero(special_tags[i].end)) {
1104                         ast_str_append(buffer, 0, "%s%s", special_tags[i].end, posttabs);
1105                 }
1106
1107                 break;
1108         }
1109
1110         return ret;
1111 }
1112
1113 /*! \internal
1114  *  \brief Parse an <argument> element from the xml documentation.
1115  *  \param fixnode Pointer to the 'argument' xml node.
1116  *  \param insideparameter If we are parsing an <argument> inside a <parameter>.
1117  *  \param paramtabs pre tabs if we are inside a parameter element.
1118  *  \param tabs What to be printed before the argument name.
1119  *  \param buffer Output buffer to put values found inside the <argument> element.
1120  *  \retval 1 If there is content inside the argument.
1121  *  \retval 0 If the argument element is not parsed, or there is no content inside it.
1122  */
1123 static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer)
1124 {
1125         struct ast_xml_node *node = fixnode;
1126         const char *argname;
1127         int count = 0, ret = 0;
1128
1129         if (!node || !ast_xml_node_get_children(node)) {
1130                 return ret;
1131         }
1132
1133         /* Print the argument names */
1134         argname = ast_xml_get_attribute(node, "name");
1135         if (!argname) {
1136                 return 0;
1137         }
1138         ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
1139         ast_xml_free_attr(argname);
1140
1141         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1142                 if (xmldoc_parse_para(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
1143                         count++;
1144                         ret = 1;
1145                 } else if (xmldoc_parse_specialtags(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
1146                         count++;
1147                         ret = 1;
1148                 }
1149         }
1150
1151         return ret;
1152 }
1153
1154 /*! \internal
1155  *  \brief Parse a <variable> node inside a <variablelist> node.
1156  *  \param node The variable node to parse.
1157  *  \param tabs A string to be appended at the begining of the output that will be stored
1158  *         in buffer.
1159  *  \param buffer This must be an already created ast_str. It will be used
1160  *         to store the result (if already has something it will be appended to the current
1161  *         string).
1162  *  \retval 0 if no data is appended.
1163  *  \retval 1 if data is appended.
1164  */
1165 static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
1166 {
1167         struct ast_xml_node *tmp;
1168         const char *valname;
1169         const char *tmptext;
1170         struct ast_str *cleanstr;
1171         int ret = 0, printedpara=0;
1172
1173         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1174                 if (xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer)) {
1175                         printedpara = 1;
1176                         continue;
1177                 } else if (xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer)) {
1178                         printedpara = 1;
1179                         continue;
1180                 }
1181
1182                 if (strcasecmp(ast_xml_node_get_name(tmp), "value")) {
1183                         continue;
1184                 }
1185
1186                 /* Parse a <value> tag only. */
1187                 if (!printedpara) {
1188                         ast_str_append(buffer, 0, "\n");
1189                         printedpara = 1;
1190                 }
1191                 /* Parse each <value name='valuename'>desciption</value> */
1192                 valname = ast_xml_get_attribute(tmp, "name");
1193                 if (valname) {
1194                         ret = 1;
1195                         ast_str_append(buffer, 0, "%s<value>%s</value>", tabs, valname);
1196                         ast_xml_free_attr(valname);
1197                 }
1198                 tmptext = ast_xml_get_text(tmp);
1199                 /* Check inside this node for any explanation about its meaning. */
1200                 if (tmptext) {
1201                         /* Cleanup text. */
1202                         xmldoc_string_cleanup(tmptext, &cleanstr, 1);
1203                         ast_xml_free_text(tmptext);
1204                         if (cleanstr && cleanstr->used > 0) {
1205                                 ast_str_append(buffer, 0, ":%s", cleanstr->str);
1206                         }
1207                         ast_free(cleanstr);
1208                 }
1209                 ast_str_append(buffer, 0, "\n");
1210         }
1211
1212         return ret;
1213 }
1214
1215 /*! \internal
1216  *  \brief Parse a <variablelist> node and put all the output inside 'buffer'.
1217  *  \param node The variablelist node pointer.
1218  *  \param tabs A string to be appended at the begining of the output that will be stored
1219  *         in buffer.
1220  *  \param buffer This must be an already created ast_str. It will be used
1221  *         to store the result (if already has something it will be appended to the current
1222  *         string).
1223  *  \retval 1 If a <variablelist> element is parsed.
1224  *  \retval 0 On error.
1225  */
1226 static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
1227 {
1228         struct ast_xml_node *tmp;
1229         const char *varname;
1230         char *vartabs;
1231         int ret = 0;
1232
1233         if (!node || !ast_xml_node_get_children(node)) {
1234                 return ret;
1235         }
1236
1237         if (strcasecmp(ast_xml_node_get_name(node), "variablelist")) {
1238                 return ret;
1239         }
1240
1241         /* use this spacing (add 4 spaces) inside a variablelist node. */
1242         ast_asprintf(&vartabs, "%s    ", tabs);
1243         if (!vartabs) {
1244                 return ret;
1245         }
1246         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1247                 /* We can have a <para> element inside the variable list */
1248                 if ((xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer))) {
1249                         ret = 1;
1250                         continue;
1251                 } else if ((xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer))) {
1252                         ret = 1;
1253                         continue;
1254                 }
1255
1256                 if (!strcasecmp(ast_xml_node_get_name(tmp), "variable")) {
1257                         /* Store the variable name in buffer. */
1258                         varname = ast_xml_get_attribute(tmp, "name");
1259                         if (varname) {
1260                                 ast_str_append(buffer, 0, "%s<variable>%s</variable>: ", tabs, varname);
1261                                 ast_xml_free_attr(varname);
1262                                 /* Parse the <variable> possible values. */
1263                                 xmldoc_parse_variable(tmp, vartabs, buffer);
1264                                 ret = 1;
1265                         }
1266                 }
1267         }
1268
1269         ast_free(vartabs);
1270
1271         return ret;
1272 }
1273
1274 char *ast_xmldoc_build_seealso(const char *type, const char *name)
1275 {
1276         struct ast_str *outputstr;
1277         char *output;
1278         struct ast_xml_node *node;
1279         const char *typename;
1280         const char *content;
1281         int first = 1;
1282
1283         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1284                 return NULL;
1285         }
1286
1287         /* get the application/function root node. */
1288         node = xmldoc_get_node(type, name, documentation_language);
1289         if (!node || !ast_xml_node_get_children(node)) {
1290                 return NULL;
1291         }
1292
1293         /* Find the <see-also> node. */
1294         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1295                 if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
1296                         break;
1297                 }
1298         }
1299
1300         if (!node || !ast_xml_node_get_children(node)) {
1301                 /* we couldnt find a <see-also> node. */
1302                 return NULL;
1303         }
1304
1305         /* prepare the output string. */
1306         outputstr = ast_str_create(128);
1307         if (!outputstr) {
1308                 return NULL;
1309         }
1310
1311         /* get into the <see-also> node. */
1312         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1313                 if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
1314                         continue;
1315                 }
1316
1317                 /* parse the <ref> node. 'type' attribute is required. */
1318                 typename = ast_xml_get_attribute(node, "type");
1319                 if (!typename) {
1320                         continue;
1321                 }
1322                 content = ast_xml_get_text(node);
1323                 if (!content) {
1324                         ast_xml_free_attr(typename);
1325                         continue;
1326                 }
1327                 if (!strcasecmp(typename, "application")) {
1328                         ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
1329                 } else if (!strcasecmp(typename, "function")) {
1330                         ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1331                 } else if (!strcasecmp(typename, "astcli")) {
1332                         ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
1333                 } else {
1334                         ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1335                 }
1336                 first = 0;
1337                 ast_xml_free_text(content);
1338         }
1339
1340         output = ast_strdup(outputstr->str);
1341         ast_free(outputstr);
1342
1343         return output;
1344 }
1345
1346 /*! \internal
1347  *  \brief Parse a <enum> node.
1348  *  \brief fixnode An ast_xml_node pointer to the <enum> node.
1349  *  \bried buffer The output buffer.
1350  *  \retval 0 if content is not found inside the enum element (data is not appended to buffer).
1351  *  \retval 1 if content is found and data is appended to buffer.
1352  */
1353 static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1354 {
1355         struct ast_xml_node *node = fixnode;
1356         int ret = 0;
1357
1358         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1359                 if ((xmldoc_parse_para(node, (ret ? tabs : " - "), "\n", buffer))) {
1360                         ret = 1;
1361                 } else if ((xmldoc_parse_specialtags(node, (ret ? tabs : " - "), "\n", buffer))) {
1362                         ret = 1;
1363                 }
1364         }
1365         return ret;
1366 }
1367
1368 /*! \internal
1369  *  \brief Parse a <enumlist> node.
1370  *  \param fixnode As ast_xml pointer to the <enumlist> node.
1371  *  \param buffer The ast_str output buffer.
1372  *  \retval 0 if no <enumlist> node was parsed.
1373  *  \retval 1 if a <enumlist> node was parsed.
1374  */
1375 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1376 {
1377         struct ast_xml_node *node = fixnode;
1378         const char *enumname;
1379         int ret = 0;
1380
1381         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1382                 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
1383                         continue;
1384                 }
1385
1386                 enumname = ast_xml_get_attribute(node, "name");
1387                 if (enumname) {
1388                         ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
1389                         ast_xml_free_attr(enumname);
1390
1391                         /* parse only enum elements inside a enumlist node. */
1392                         if ((xmldoc_parse_enum(node, tabs, buffer))) {
1393                                 ret = 1;
1394                         } else {
1395                                 ast_str_append(buffer, 0, "\n");
1396                         }
1397                 }
1398         }
1399         return ret;
1400 }
1401
1402 /*! \internal
1403  *  \brief Parse an <option> node.
1404  *  \param fixnode An ast_xml pointer to the <option> node.
1405  *  \param tabs A string to be appended at the begining of each line being added to the
1406  *              buffer string.
1407  *  \param buffer The output buffer.
1408  *  \retval 0 if no option node is parsed.
1409  *  \retval 1 if an option node is parsed.
1410  */
1411 static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1412 {
1413         struct ast_xml_node *node;
1414         int ret = 0;
1415         char *optiontabs;
1416
1417         ast_asprintf(&optiontabs, "%s    ", tabs);
1418         if (!optiontabs) {
1419                 return ret;
1420         }
1421         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
1422                 if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1423                         /* if this is the first data appended to buffer, print a \n*/
1424                         if (!ret && ast_xml_node_get_children(node)) {
1425                                 /* print \n */
1426                                 ast_str_append(buffer, 0, "\n");
1427                         }
1428                         if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
1429                                 ret = 1;
1430                         }
1431                         continue;
1432                 }
1433
1434                 if (xmldoc_parse_para(node, (ret ? tabs :  ""), "\n", buffer)) {
1435                         ret = 1;
1436                 } else if (xmldoc_parse_specialtags(node, (ret ? tabs :  ""), "\n", buffer)) {
1437                         ret = 1;
1438                 }
1439
1440                 xmldoc_parse_variablelist(node, optiontabs, buffer);
1441
1442                 xmldoc_parse_enumlist(node, optiontabs, buffer);
1443         }
1444         ast_free(optiontabs);
1445
1446         return ret;
1447 }
1448
1449 /*! \internal
1450  *  \brief Parse an <optionlist> element from the xml documentation.
1451  *  \param fixnode Pointer to the optionlist xml node.
1452  *  \param tabs A string to be appended at the begining of each line being added to the
1453  *              buffer string.
1454  *  \param buffer Output buffer to put what is inside the optionlist tag.
1455  */
1456 static void xmldoc_parse_optionlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1457 {
1458         struct ast_xml_node *node;
1459         const char *optname, *hasparams;
1460         char *optionsyntax;
1461         int optparams;
1462
1463         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
1464                 /* Start appending every option tag. */
1465                 if (strcasecmp(ast_xml_node_get_name(node), "option")) {
1466                         continue;
1467                 }
1468
1469                 /* Get the option name. */
1470                 optname = ast_xml_get_attribute(node, "name");
1471                 if (!optname) {
1472                         continue;
1473                 }
1474
1475                 optparams = 1;
1476                 hasparams = ast_xml_get_attribute(node, "hasparams");
1477                 if (hasparams && !strcasecmp(hasparams, "optional")) {
1478                         optparams = 2;
1479                 }
1480
1481                 optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
1482                 if (!optionsyntax) {
1483                         ast_xml_free_attr(optname);
1484                         ast_xml_free_attr(hasparams);
1485                         continue;
1486                 }
1487
1488                 ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
1489
1490                 if (!xmldoc_parse_option(node, tabs, buffer)) {
1491                         ast_str_append(buffer, 0, "\n");
1492                 }
1493                 ast_xml_free_attr(optname);
1494                 ast_xml_free_attr(hasparams);
1495         }
1496 }
1497
1498 /*! \internal
1499  *  \brief Parse a 'parameter' tag inside a syntax element.
1500  *  \param fixnode A pointer to the 'parameter' xml node.
1501  *  \param tabs A string to be appended at the beginning of each line being printed inside
1502  *              'buffer'.
1503  *  \param buffer String buffer to put values found inside the parameter element.
1504  */
1505 static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1506 {
1507         const char *paramname;
1508         struct ast_xml_node *node = fixnode;
1509         int hasarguments, printed = 0;
1510         char *internaltabs;
1511
1512         if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
1513                 return;
1514         }
1515
1516         hasarguments = xmldoc_has_inside(node, "argument");
1517         if (!(paramname = ast_xml_get_attribute(node, "name"))) {
1518                 /* parameter MUST have an attribute name. */
1519                 return;
1520         }
1521
1522         ast_asprintf(&internaltabs, "%s    ", tabs);
1523         if (!internaltabs) {
1524                 return;
1525         }
1526
1527         if (!hasarguments) {
1528                 ast_str_append(buffer, 0, "%s\n", paramname);
1529                 ast_xml_free_attr(paramname);
1530                 printed = 1;
1531         }
1532
1533         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1534                 if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
1535                         xmldoc_parse_optionlist(node, internaltabs, buffer);
1536                 } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
1537                         xmldoc_parse_enumlist(node, internaltabs, buffer);
1538                 } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1539                         xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? "        " : ""), buffer);
1540                 } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
1541                         if (!printed) {
1542                                 ast_str_append(buffer, 0, "%s\n", paramname);
1543                                 ast_xml_free_attr(paramname);
1544                                 printed = 1;
1545                         }
1546                         xmldoc_parse_para(node, internaltabs, "\n", buffer);
1547                         continue;
1548                 } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
1549                         continue;
1550                 }
1551         }
1552         ast_free(internaltabs);
1553 }
1554
1555 char *ast_xmldoc_build_arguments(const char *type, const char *name)
1556 {
1557         struct ast_xml_node *node;
1558         struct ast_str *ret = ast_str_create(128);
1559         char *retstr = NULL;
1560
1561         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1562                 return NULL;
1563         }
1564
1565         node = xmldoc_get_node(type, name, documentation_language);
1566
1567         if (!node || !ast_xml_node_get_children(node)) {
1568                 return NULL;
1569         }
1570
1571         /* Find the syntax field. */
1572         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1573                 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1574                         break;
1575                 }
1576         }
1577
1578         if (!node || !ast_xml_node_get_children(node)) {
1579                 /* We couldn't find the syntax node. */
1580                 return NULL;
1581         }
1582
1583         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1584                 xmldoc_parse_parameter(node, "", &ret);
1585         }
1586
1587         if (ret->used > 0) {
1588                 /* remove last '\n' */
1589                 if (ret->str[ret->used - 1] == '\n') {
1590                         ret->str[ret->used - 1] = '\0';
1591                         ret->used--;
1592                 }
1593                 retstr = ast_strdup(ret->str);
1594         }
1595         ast_free(ret);
1596
1597         return retstr;
1598 }
1599
1600 /*! \internal
1601  *  \brief Return the string within a node formatted with <para> and <variablelist> elements.
1602  *  \param node Parent node where content resides.
1603  *  \param raw If set, return the node's content without further processing.
1604  *  \param raw_wrap Wrap raw text.
1605  *  \retval NULL on error
1606  *  \retval Node content on success.
1607  */
1608 static struct ast_str *xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
1609 {
1610         struct ast_xml_node *tmp;
1611         const char *notcleanret, *tmpstr;
1612         struct ast_str *ret = ast_str_create(128);
1613
1614         if (raw_output) {
1615                 notcleanret = ast_xml_get_text(node);
1616                 tmpstr = notcleanret;
1617                 xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0);
1618                 ast_xml_free_text(tmpstr);
1619         } else {
1620                 for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1621                         /* if found, parse a <para> element. */
1622                         if (xmldoc_parse_para(tmp, "", "\n", &ret)) {
1623                                 continue;
1624                         } else if (xmldoc_parse_specialtags(tmp, "", "\n", &ret)) {
1625                                 continue;
1626                         }
1627                         /* if found, parse a <variablelist> element. */
1628                         xmldoc_parse_variablelist(tmp, "", &ret);
1629                         xmldoc_parse_enumlist(tmp, "    ", &ret);
1630                 }
1631                 /* remove last '\n' */
1632                 /* XXX Don't modify ast_str internals manually */
1633                 if (ret->str[ret->used-1] == '\n') {
1634                         ret->str[ret->used-1] = '\0';
1635                         ret->used--;
1636                 }
1637         }
1638         return ret;
1639 }
1640
1641 /*!
1642  *  \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
1643  *  \param type Type of element (application, function, ...).
1644  *  \param name Name of element (Dial, Echo, Playback, ...).
1645  *  \param var Name of field to return (synopsis, description, etc).
1646  *  \param raw Field only contains text, no other elements inside it.
1647  *  \retval NULL On error.
1648  *  \retval Field text content on success.
1649  */
1650 static char *xmldoc_build_field(const char *type, const char *name, const char *var, int raw)
1651 {
1652         struct ast_xml_node *node;
1653         char *ret = NULL;
1654         struct ast_str *formatted;
1655
1656         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1657                 ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
1658                 return ret;
1659         }
1660
1661         node = xmldoc_get_node(type, name, documentation_language);
1662
1663         if (!node) {
1664                 ast_log(LOG_WARNING, "Counldn't find %s %s in XML documentation\n", type, name);
1665                 return ret;
1666         }
1667
1668         node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
1669
1670         if (!node || !ast_xml_node_get_children(node)) {
1671                 ast_log(LOG_DEBUG, "Cannot find variable '%s' in tree '%s'\n", name, var);
1672                 return ret;
1673         }
1674
1675         formatted = xmldoc_get_formatted(node, raw, raw);
1676         if (formatted->used > 0) {
1677                 ret = ast_strdup(formatted->str);
1678         }
1679         ast_free(formatted);
1680
1681         return ret;
1682 }
1683
1684 char *ast_xmldoc_build_synopsis(const char *type, const char *name)
1685 {
1686         return xmldoc_build_field(type, name, "synopsis", 1);
1687 }
1688
1689 char *ast_xmldoc_build_description(const char *type, const char *name)
1690 {
1691         return xmldoc_build_field(type, name, "description", 0);
1692 }
1693
1694 /*! \brief Close and unload XML documentation. */
1695 static void xmldoc_unload_documentation(void)
1696 {
1697         struct documentation_tree *doctree;
1698
1699         AST_RWLIST_WRLOCK(&xmldoc_tree);
1700         while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
1701                 ast_free(doctree->filename);
1702                 ast_xml_close(doctree->doc);
1703         }
1704         AST_RWLIST_UNLOCK(&xmldoc_tree);
1705
1706         ast_xml_finish();
1707 }
1708
1709 int ast_xmldoc_load_documentation(void)
1710 {
1711         struct ast_xml_node *root_node;
1712         struct ast_xml_doc *tmpdoc;
1713         struct documentation_tree *doc_tree;
1714         char *xmlpattern;
1715         struct ast_config *cfg = NULL;
1716         struct ast_variable *var = NULL;
1717         struct ast_flags cnfflags = { 0 };
1718         int globret, i, dup, duplicate;
1719         glob_t globbuf;
1720
1721         /* setup default XML documentation language */
1722         snprintf(documentation_language, sizeof(documentation_language), default_documentation_language);
1723
1724         if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
1725                 for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
1726                         if (!strcasecmp(var->name, "documentation_language")) {
1727                                 if (!ast_strlen_zero(var->value)) {
1728                                         snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
1729                                 }
1730                         }
1731                 }
1732                 ast_config_destroy(cfg);
1733         }
1734
1735         /* initialize the XML library. */
1736         ast_xml_init();
1737
1738         /* register function to be run when asterisk finish. */
1739         ast_register_atexit(xmldoc_unload_documentation);
1740
1741         /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
1742         ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
1743                         documentation_language, documentation_language, default_documentation_language);
1744         globbuf.gl_offs = 0;    /* initialize it to silence gcc */
1745         globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
1746         if (globret == GLOB_NOSPACE) {
1747                 ast_log(LOG_WARNING, "Glob Expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
1748                 ast_free(xmlpattern);
1749                 return 1;
1750         } else if (globret  == GLOB_ABORTED) {
1751                 ast_log(LOG_WARNING, "Glob Expansion of pattern '%s' failed: Read error\n", xmlpattern);
1752                 ast_free(xmlpattern);
1753                 return 1;
1754         }
1755         ast_free(xmlpattern);
1756
1757         AST_RWLIST_WRLOCK(&xmldoc_tree);
1758         /* loop over expanded files */
1759         for (i = 0; i < globbuf.gl_pathc; i++) {
1760                 /* check for duplicates (if we already [try to] open the same file. */
1761                 duplicate = 0;
1762                 for (dup = 0; dup < i; dup++) {
1763                         if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
1764                                 duplicate = 1;
1765                                 break;
1766                         }
1767                 }
1768                 if (duplicate) {
1769                         continue;
1770                 }
1771                 tmpdoc = NULL;
1772                 tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
1773                 if (!tmpdoc) {
1774                         ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
1775                         continue;
1776                 }
1777                 /* Get doc root node and check if it starts with '<docs>' */
1778                 root_node = ast_xml_get_root(tmpdoc);
1779                 if (!root_node) {
1780                         ast_log(LOG_ERROR, "Error getting documentation root node");
1781                         ast_xml_close(tmpdoc);
1782                         continue;
1783                 }
1784                 /* Check root node name for malformed xmls. */
1785                 if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
1786                         ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
1787                         ast_xml_close(tmpdoc);
1788                         continue;
1789                 }
1790                 doc_tree = ast_calloc(1, sizeof(*doc_tree));
1791                 if (!doc_tree) {
1792                         ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
1793                         ast_xml_close(tmpdoc);
1794                         continue;
1795                 }
1796                 doc_tree->doc = tmpdoc;
1797                 doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
1798                 AST_RWLIST_INSERT_TAIL(&xmldoc_tree, doc_tree, entry);
1799         }
1800         AST_RWLIST_UNLOCK(&xmldoc_tree);
1801
1802         globfree(&globbuf);
1803
1804         return 0;
1805 }
1806
1807 #endif /* AST_XML_DOCS */
1808
1809