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