1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
#ifndef _ASTERISK_XMLDOC_H
#define _ASTERISK_XMLDOC_H
/*! \file
* \brief Asterisk XML Documentation API
*/
#include "asterisk/xml.h"
#include "asterisk/stringfields.h"
#include "asterisk/strings.h"
/*! \brief From where the documentation come from, this structure is useful for
* use it inside application/functions/manager actions structure. */
enum ast_doc_src {
AST_XML_DOC, /*!< From XML documentation */
AST_STATIC_DOC /*!< From application/function registration */
};
#ifdef AST_XML_DOCS
struct ao2_container;
struct ast_xml_node;
/*!
* \brief The struct to be used as the head of an ast_xml_doc_item list
* when being manipulated
* \since 13.0.0
*/
AST_LIST_HEAD(ast_xml_doc_item_list, ast_xml_doc_item);
/*! \brief Struct that contains the XML documentation for a particular item. Note
* that this is an ao2 ref counted object.
*
* \note
* Each of the ast_str objects are built from the corresponding ast_xmldoc_build_*
* calls
*
* \since 11
*/
struct ast_xml_doc_item {
/*! The syntax of the item */
struct ast_str *syntax;
/*! Seealso tagged information, if it exists */
struct ast_str *seealso;
/*! The arguments to the item */
struct ast_str *arguments;
/*! A synopsis of the item */
struct ast_str *synopsis;
/*! A description of the item */
struct ast_str *description;
AST_DECLARE_STRING_FIELDS(
/*! The name of the item */
AST_STRING_FIELD(name);
/*! The type of the item */
AST_STRING_FIELD(type);
/*! Reference to another field */
AST_STRING_FIELD(ref);
);
/*! The node that this item was created from. Note that the life time of
* the node is not tied to the lifetime of this object.
*/
struct ast_xml_node *node;
/*! The next XML documentation item that matches the same name/item type */
AST_LIST_ENTRY(ast_xml_doc_item) next;
};
/*! \brief Execute an XPath query on the loaded XML documentation
* \param query The XPath query string to execute
* \param ... Variable printf style format arguments
* \retval An XPath results object on success
* \retval NULL if no match found
*
* \since 12
*/
struct ast_xml_xpath_results *__attribute__((format(printf, 1, 2))) ast_xmldoc_query(const char *fmt, ...);
/*!
* \brief Get the syntax for a specified application or function.
* \param type Application, Function or AGI ?
* \param name Name of the application or function.
* \param module The module the item is in (optional, can be NULL)
* \retval NULL on error.
* \retval The generated syntax in a ast_malloc'ed string.
*/
char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *module);
/*!
* \brief Parse the <see-also> node content.
* \param type 'application', 'function' or 'agi'.
* \param name Application or functions name.
* \param module The module the item is in (optional, can be NULL)
* \retval NULL on error.
* \retval Content of the see-also node.
*/
char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module);
/*!
* \brief Generate the [arguments] tag based on type of node ('application',
* 'function' or 'agi') and name.
* \param type 'application', 'function' or 'agi' ?
* \param name Name of the application or function to build the 'arguments' tag.
* \param module The module the item is in (optional, can be NULL)
* \retval NULL on error.
* \retval Output buffer with the [arguments] tag content.
*/
char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module);
/*!
* \brief Generate the [final response] tag based on type of node ('application',
* 'function' or 'agi') and name.
*
* \param type 'application', 'function' or 'agi'
* \param name Name of the application or function to build the 'responses' tag.
* \param module The module the item is in (optional, can be NULL)
*
* \return An XMLDoc item list with the [final response] tag content.
*
* \since 13.0.0
*/
struct ast_xml_doc_item *ast_xmldoc_build_final_response(const char *type, const char *name, const char *module);
/*!
* \brief Generate the [list responses] tag based on type of node ('application',
* 'function' or 'agi') and name.
*
* \param type 'application', 'function' or 'agi'
* \param name Name of the application or function to build the 'responses' tag.
* \param module The module the item is in (optional, can be NULL)
*
* \return An XMLDoc item list with the [list responses] tag content.
*
* \since 13.0.0
*/
struct ast_xml_doc_item *ast_xmldoc_build_list_responses(const char *type, const char *name, const char *module);
/*!
* \brief Colorize and put delimiters (instead of tags) to the xmldoc output.
* \param bwinput Not colorized input with tags.
* \param withcolors Result output with colors.
* \retval NULL on error.
* \retval New malloced buffer colorized and with delimiters.
*/
char *ast_xmldoc_printable(const char *bwinput, int withcolors);
/*!
* \brief Generate synopsis documentation from XML.
* \param type The source of documentation (application, function, etc).
* \param name The name of the application, function, etc.
* \param module The module the item is in (optional, can be NULL)
* \retval NULL on error.
* \retval A malloc'ed string with the synopsis.
*/
char *ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module);
/*!
* \brief Generate description documentation from XML.
* \param type The source of documentation (application, function, etc).
* \param name The name of the application, function, etc.
* \param module The module the item is in (optional, can be NULL)
* \retval NULL on error.
* \retval A malloc'ed string with the formatted description.
*/
char *ast_xmldoc_build_description(const char *type, const char *name, const char *module);
/*!
* \brief Build the documentation for a particular source type
* \param type The source of the documentation items (application, function, etc.)
*
* \retval NULL on error
* \retval An ao2_container populated with ast_xml_doc instances for each item
* that exists for the specified source type
*
* \since 11
*/
struct ao2_container *ast_xmldoc_build_documentation(const char *type);
/*!
* \brief Regenerate the documentation for a particular item
* \param item The documentation item to regenerate
*
* \retval -1 on error
* \retval 0 on success
*
* \since 12
*/
int ast_xmldoc_regenerate_doc_item(struct ast_xml_doc_item *item);
#endif /* AST_XML_DOCS */
#endif /* _ASTERISK_XMLDOC_H */
|
