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