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