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