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