Asterisk - The Open Source Telephony Project  18.5.0
xmldoc.h
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 #ifndef _ASTERISK_XMLDOC_H
18 #define _ASTERISK_XMLDOC_H
19 
20 /*! \file
21  * \brief Asterisk XML Documentation API
22  */
23 
24 #include "asterisk/xml.h"
25 #include "asterisk/stringfields.h"
26 #include "asterisk/strings.h"
27 
28 /*! \brief From where the documentation come from, this structure is useful for
29  * use it inside application/functions/manager actions structure. */
31  AST_XML_DOC, /*!< From XML documentation */
32  AST_STATIC_DOC /*!< From application/function registration */
33 };
34 
35 #ifdef AST_XML_DOCS
36 
37 struct ao2_container;
38 struct ast_xml_node;
39 
40 /*!
41  * \brief The struct to be used as the head of an ast_xml_doc_item list
42  * when being manipulated
43  * \since 13.0.0
44  */
46 
47 /*! \brief Struct that contains the XML documentation for a particular item. Note
48  * that this is an ao2 ref counted object.
49  *
50  * \note
51  * Each of the ast_str objects are built from the corresponding ast_xmldoc_build_*
52  * calls
53  *
54  * \since 11
55  */
57  /*! The syntax of the item */
58  struct ast_str *syntax;
59  /*! Seealso tagged information, if it exists */
60  struct ast_str *seealso;
61  /*! The arguments to the item */
62  struct ast_str *arguments;
63  /*! A synopsis of the item */
64  struct ast_str *synopsis;
65  /*! A description of the item */
68  /*! The name of the item */
70  /*! The type of the item */
72  /*! Reference to another field */
74  );
75  /*! The node that this item was created from. Note that the life time of
76  * the node is not tied to the lifetime of this object.
77  */
78  struct ast_xml_node *node;
79  /*! The next XML documentation item that matches the same name/item type */
81 };
82 
83 /*! \brief Execute an XPath query on the loaded XML documentation
84  * \param query The XPath query string to execute
85  * \param ... Variable printf style format arguments
86  * \retval An XPath results object on success
87  * \retval NULL if no match found
88  *
89  * \since 12
90  */
91 struct ast_xml_xpath_results *__attribute__((format(printf, 1, 2))) ast_xmldoc_query(const char *fmt, ...);
92 
93 /*!
94  * \brief Get the syntax for a specified application or function.
95  * \param type Application, Function or AGI ?
96  * \param name Name of the application or function.
97  * \param module The module the item is in (optional, can be NULL)
98  * \retval NULL on error.
99  * \retval The generated syntax in a ast_malloc'ed string.
100  */
101 char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *module);
102 
103 /*!
104  * \brief Parse the <see-also> node content.
105  * \param type 'application', 'function' or 'agi'.
106  * \param name Application or functions name.
107  * \param module The module the item is in (optional, can be NULL)
108  * \retval NULL on error.
109  * \retval Content of the see-also node.
110  */
111 char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module);
112 
113 /*!
114  * \brief Generate the [arguments] tag based on type of node ('application',
115  * 'function' or 'agi') and name.
116  * \param type 'application', 'function' or 'agi' ?
117  * \param name Name of the application or function to build the 'arguments' tag.
118  * \param module The module the item is in (optional, can be NULL)
119  * \retval NULL on error.
120  * \retval Output buffer with the [arguments] tag content.
121  */
122 char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module);
123 
124 /*!
125  * \brief Generate the [final response] tag based on type of node ('application',
126  * 'function' or 'agi') and name.
127  *
128  * \param type 'application', 'function' or 'agi'
129  * \param name Name of the application or function to build the 'responses' tag.
130  * \param module The module the item is in (optional, can be NULL)
131  *
132  * \return An XMLDoc item list with the [final response] tag content.
133  *
134  * \since 13.0.0
135  */
136 struct ast_xml_doc_item *ast_xmldoc_build_final_response(const char *type, const char *name, const char *module);
137 
138 /*!
139  * \brief Generate the [list responses] tag based on type of node ('application',
140  * 'function' or 'agi') and name.
141  *
142  * \param type 'application', 'function' or 'agi'
143  * \param name Name of the application or function to build the 'responses' tag.
144  * \param module The module the item is in (optional, can be NULL)
145  *
146  * \return An XMLDoc item list with the [list responses] tag content.
147  *
148  * \since 13.0.0
149  */
150 struct ast_xml_doc_item *ast_xmldoc_build_list_responses(const char *type, const char *name, const char *module);
151 
152 /*!
153  * \brief Colorize and put delimiters (instead of tags) to the xmldoc output.
154  * \param bwinput Not colorized input with tags.
155  * \param withcolors Result output with colors.
156  * \retval NULL on error.
157  * \retval New malloced buffer colorized and with delimiters.
158  */
159 char *ast_xmldoc_printable(const char *bwinput, int withcolors);
160 
161 /*!
162  * \brief Generate synopsis documentation from XML.
163  * \param type The source of documentation (application, function, etc).
164  * \param name The name of the application, function, etc.
165  * \param module The module the item is in (optional, can be NULL)
166  * \retval NULL on error.
167  * \retval A malloc'ed string with the synopsis.
168  */
169 char *ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module);
170 
171 /*!
172  * \brief Generate description documentation from XML.
173  * \param type The source of documentation (application, function, etc).
174  * \param name The name of the application, function, etc.
175  * \param module The module the item is in (optional, can be NULL)
176  * \retval NULL on error.
177  * \retval A malloc'ed string with the formatted description.
178  */
179 char *ast_xmldoc_build_description(const char *type, const char *name, const char *module);
180 
181 /*!
182  * \brief Build the documentation for a particular source type
183  * \param type The source of the documentation items (application, function, etc.)
184  *
185  * \retval NULL on error
186  * \retval An ao2_container populated with ast_xml_doc instances for each item
187  * that exists for the specified source type
188  *
189  * \since 11
190  */
191 struct ao2_container *ast_xmldoc_build_documentation(const char *type);
192 
193 /*!
194  * \brief Regenerate the documentation for a particular item
195  * \param item The documentation item to regenerate
196  *
197  * \retval -1 on error
198  * \retval 0 on success
199  *
200  * \since 12
201  */
203 
204 #endif /* AST_XML_DOCS */
205 
206 #endif /* _ASTERISK_XMLDOC_H */
#define AST_LIST_HEAD(name, type)
Defines a structure to be used to hold a list of specified type.
Definition: linkedlists.h:172
String manipulation functions.
struct ast_xml_doc_item * next
Definition: xmldoc.h:80
const ast_string_field ref
Definition: xmldoc.h:74
struct ast_xml_node * node
Definition: xmldoc.h:78
char * ast_xmldoc_build_description(const char *type, const char *name, const char *module)
Generate description documentation from XML.
Definition: xmldoc.c:2250
struct ao2_container * ast_xmldoc_build_documentation(const char *type)
Build the documentation for a particular source type.
Definition: xmldoc.c:2653
struct ast_xml_xpath_results * ast_xmldoc_query(const char *fmt,...)
Execute an XPath query on the loaded XML documentation.
Definition: xmldoc.c:2545
static struct aco_type item
Definition: test_config.c:1463
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:337
char * ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
Generate synopsis documentation from XML.
Definition: xmldoc.c:2227
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
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:30
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
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
The struct to be used as the head of an ast_xml_doc_item list when being manipulated.
Definition: xmldoc.h:45
const ast_string_field type
Definition: xmldoc.h:74
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:299
Asterisk XML abstraction layer.
struct ast_str * description
Definition: xmldoc.h:66
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
const ast_string_field name
Definition: xmldoc.h:74
char * ast_xmldoc_printable(const char *bwinput, int withcolors)
Colorize and put delimiters (instead of tags) to the xmldoc output.
Definition: xmldoc.c:242
int ast_xmldoc_regenerate_doc_item(struct ast_xml_doc_item *item)
Regenerate the documentation for a particular item.
Definition: xmldoc.c:2604
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
char * ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
Parse the <see-also> node content.
Definition: xmldoc.c:1698
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
Generic container type.
struct ast_str * arguments
Definition: xmldoc.h:62
struct ast_str * syntax
Definition: xmldoc.h:58
static snd_pcm_format_t format
Definition: chan_alsa.c:102
struct ast_str * seealso
Definition: xmldoc.h:60
struct ast_str * synopsis
Definition: xmldoc.h:64