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