Doxygen Updates - Title update
[asterisk/asterisk.git] / include / asterisk / doxyref.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2012, Digium, Inc.
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 /*! 
18  * \file
19  *
20  * This is the main header file used for generating miscellaneous documentation
21  * using Doxygen.  This also utilizes the documentation in 
22  * include/asterisk/doxygen/ header files.
23  */
24
25 /* 
26  * The following is for Doxygen Developer's documentation generated
27  * by running "make progdocs" with doxygen installed on your
28  * system.
29  */
30
31 /*! 
32  * \page DevDoc Asterisk Developer's Documentation - Appendices
33  *
34  * \section devpolicy Development and Release Policies
35  * \arg \ref CodeGuide : The must-read document for all developers
36  * \arg \ref CommitMessages : Information on formatting and special tags for commit messages
37  * \arg \ref ReleaseStatus : The current support level for various Asterisk releases
38  * \arg \ref ReleasePolicies : Asterisk Release and Commit Policies
39  * \arg \ref Reviewboard : Reviewboard Usage and Guidelines
40  * \arg \ref MantisWorkflow : Workflow Guidelines for Asterisk Open Source Issue Tracker
41  * \arg \ref AsteriskGitHowto : How to setup a local GIT mirror of the Asterisk SVN repository
42  * \arg \ref AstCREDITS : A Thank You to contributors (unfortunately out of date)
43  *
44  * \section apisandinterfaces Asterisk APIs and Interfaces
45  * \arg \ref AstAPI
46  * \arg \ref AstAPIChanges
47  * \arg \ref Def_Channel : What's a channel, anyway?
48  * \arg \ref channel_drivers : Existing channel drivers
49  * \arg \ref AstAMI : The Call management socket API
50  * \arg \ref AstARA : A generic data storage and retrieval API for Asterisk
51  * \arg \ref AstDUNDi : A way to find phone services dynamically by using the DUNDi protocol
52  * \arg \ref AJI_intro : The Asterisk Jabber Interface
53  * \arg \ref AstCDR
54  * \arg \ref AstVar
55  * \arg \ref AstVideo
56  * \arg \ref AstENUM : The IETF way to redirect from phone numbers to VoIP calls
57  * \arg \ref AstHTTP
58  * \arg \ref AstSpeech
59  *
60  * \section debugconfig Debugging and Configuration References
61  * \arg \ref AstDebug : Hints on debugging
62  * \arg \ref extref 
63  * \arg \ref ConfigFiles
64  * \arg \ref SoundFiles included in the Asterisk distribution
65  *
66  * \section weblinks Web sites
67  * \arg \b Main:  Asterisk Developer's website http://www.asterisk.org/developers/
68  * \arg \b Bugs: The Issue Tracker https://issues.asterisk.org
69  * \arg \b Lists: List Server http://lists.digium.com
70  * \arg \b Wiki: The Asterisk Wiki      http://wiki.asterisk..org
71  * \arg \b Docs: The Asterisk Documentation Project http://www.asteriskdocs.org
72  * \arg \b Digium: The Asterisk Company http://www.digium.com
73  */
74
75 /*! 
76  * \page CodeGuide Coding Guidelines
77  * \AsteriskTrunkWarning
78  * \section Coding Guidelines
79  * This file is in the /doc directory in your Asterisk source tree.
80  * Make sure to stay up to date with the latest guidelines.
81  * \verbinclude CODING-GUIDELINES
82  */
83
84 /*! 
85  * \page AstAPI Asterisk API
86  * \section Asteriskapi Asterisk API
87  * Some generic documents on the Asterisk architecture
88  *
89  * \arg \ref AstThreadStorage
90  * \arg \ref DataStores
91  * \arg \ref AstExtState
92  * \arg \ref AstDataRetrieval
93  *
94  * \subsection channel_txt Channels
95  * \arg See \ref Def_Channel
96  */
97
98 /*! 
99  * \page AstAPIChanges Asterisk API Changes
100  *
101  * \section Changes161 Version 1.6.1
102  * \li ast_install_vm_functions()
103  * \li vmwi_generate()
104  * \li ast_channel_datastore_alloc()
105  * \li ast_channel_datastore_free()
106  * \li ast_channel_cmpwhentohangup()
107  * \li ast_channel_setwhentohangup()
108  * \li ast_settimeout()
109  * \li ast_datastore_alloc()
110  * \li ast_datastore_free()
111  * \li ast_device_state_changed()
112  * \li ast_device_state_changed_literal()
113  * \li ast_dnsmgr_get()
114  * \li ast_dnsmgr_lookup()
115  * \li ast_dsp_set_digitmode()
116  * \li ast_get_txt()
117  * \li ast_event_unsubscribe()
118  * \li localized_context_find_or_create()
119  * \li localized_merge_contexts_and_delete()
120  * \li ast_console_puts_mutable()
121  * \li ast_rtp_get_quality()
122  * \li ast_tcptls_client_start()
123  * \li ast_tcptls_server_start()
124  * \li ast_tcptls_server_stop()
125  *
126  * \section Changes162 Version 1.6.2
127  *
128  * \section Changes18 Version 1.8
129  * \li ast_channel_alloc()
130  */
131
132 /*! 
133  * \page AstAMI AMI - The Manager Interface
134  * \section ami AMI - The manager Interface
135  * \arg \link Config_ami Configuration file \endlink
136  * \arg \ref manager.c
137  * \todo include missing manager txt
138  */
139
140 /*!
141  * \page AstARA ARA - The Asterisk Realtime Interface
142  * \section realtime ARA - a generic API to storage and retrieval
143  * Implemented in \ref config.c 
144  * Implemented in \ref pbx_realtime.c 
145  * \todo include missing realtime txt
146  * \todo include missing extconfig txt
147  */
148
149 /*! 
150  * \page AstDUNDi DUNDi
151  *
152  * DUNDi is a peer-to-peer system for locating Internet gateways to telephony 
153  * services. Unlike traditional centralized services (such as the remarkably 
154  * simple and concise ENUM standard), DUNDi is fully-distributed with no 
155  * centralized authority whatsoever.
156  *
157  * DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, 
158  * it publishes routes which are in turn accessed via industry standard 
159  * protocols such as IAX, SIP and H.323. 
160  *
161  * \par References
162  * \arg DUNDi is documented at http://www.dundi.com
163  * \arg Implemented in \ref pbx_dundi.c and \ref dundi-parser.c
164  * \arg Configuration in \ref dundi.conf
165  */
166
167 /*! 
168  * \page AstCDR CDR - Call Data Records and billing
169  * \section cdr Call Data Records
170  * \par See also
171  * \arg \ref cdr.c
172  * \arg \ref cdr_drivers
173  * \arg \ref Config_cdr CDR configuration files
174  *
175  * \todo include missing cdrdriver txt
176  */
177
178 /*! 
179  * \page AstCREDITS CREDITS
180  * \verbinclude CREDITS
181  */
182
183 /*! 
184  * \page AstVideo Video support in Asterisk
185  * \section sectAstVideo Video support in Asterisk
186  * \todo include missing video txt
187  */
188
189 /*! 
190  * \page AstVar Globally predefined channel variables
191  * \section globchan Globally predefined channel variables
192  *
193  * More and more of these variables are being replaced by dialplan functions.
194  * Some still exist though and some that does still exist needs to move to
195  * dialplan functions.
196  *
197  * See also
198  * - \ref pbx_retrieve_variable()
199  * - \ref AstChanVar
200  *
201  */
202
203 /*! 
204  * \page AstChanVar Asterisk Dialplan Variables
205  *      Asterisk Dialplan variables are divided into three groups:
206  *      - Predefined global variables, handled by the PBX core
207  *      - Global variables, that exist for the duration of the pbx execution
208  *      - Channel variables, that exist during a channel
209  *
210  * Global variables are reachable in all channels, all of the time.
211  * Channel variables are only reachable within the channel.
212  *
213  * For more information on the predefined variables, see \ref AstVar
214  * 
215  * Global and Channel variables:
216  * - Names are Case insensitive
217  * - Names that start with a character, but are alphanumeric
218  * - Global variables are defined and reached with the GLOBAL() dialplan function
219  *   and the set application, like
220  *
221  *      exten => 1234,1,set(GLOBAL(myvariable)=tomteluva)
222  *
223  *      - \ref func_global.c
224  *
225  * - Channel variables are defined with the set() dialplan application
226  *
227  *      exten => 1234,1,set(xmasattribute=tomtegröt)
228  *
229  * - Some channels also supports setting channel variables with the \b setvar=
230  *   configuraiton option for a device or line.
231  *
232  * \section AstChanVar_globalvars Global Variables
233  * Global variables can also be set in the [globals] section of extensions.conf. The
234  * setting \b clearglobalvars in extensions.conf [general] section affects whether
235  * or not the global variables defined in \b globals are reset at dialplan reload.
236  * 
237  * There are CLI commands to change and read global variables. This can be handy
238  * to reset counters at midnight from an external script.
239  *
240  * \section AstChanVar_devnotes Developer notes
241  * Variable handling is managed within \ref pbx.c
242  * You need to include pbx.h to reach these functions.
243  *      - \ref pbx_builtin_setvar_helper()
244  *      - \ref pbx_builtin_getvar_helper()
245  *
246  * The variables is a linked list stored in the channel data structure
247  * with the list starting at varshead in struct ast_channel
248  */
249
250 /*! 
251  * \page Config_mod Modules configuration
252  * All res_ resource modules are loaded with globals on, which means
253  * that non-static functions are callable from other modules.
254  *
255  * If you want your non res_* module to export functions to other modules
256  * you have to include it in the [global] section.
257  */
258
259 /*!
260  * \page Config_ext Extensions.conf - the Dial Plan
261  * \section dialplan Extensions.conf 
262  * \verbinclude extensions.conf.sample
263  */
264
265 /*! 
266  * \page Config_rtp RTP configuration
267  * \arg Implemented in \ref rtp.c
268  * Used in \ref chan_sip.c and \ref chan_mgcp.c (and various H.323 channels)
269  * \section rtpconf rtp.conf
270  * \verbinclude rtp.conf.sample
271  */
272
273 /*! 
274  * \page Config_codec CODEC Configuration
275  * \section codecsconf codecs.conf
276  * \verbinclude codecs.conf.sample
277  */
278
279 /*! 
280  * \page Config_ara REALTIME Configuration
281  * \arg See also: \arg \link AstARA \endlink
282  * \section extconf extconfig.conf
283  * \verbinclude extconfig.conf.sample
284  */
285
286 /*! 
287  * \page Config_ami AMI configuration
288  * \arg See also: \arg \link AstAMI \endlink
289  * \section amiconf manager.conf
290  * \verbinclude manager.conf.sample
291  */
292
293 /*! 
294  * \page SoundFiles Sound files
295  * \section SecSound Asterisk Sound files
296  * Asterisk includes a large number of sound files. Many of these
297  * are used by applications and demo scripts within asterisk.
298  *
299  * Additional sound files are available in the asterisk-addons
300  * repository on svn.digium.com
301  */
302
303 /*!
304  * \page AstHTTP AMI over HTTP support
305  * The http.c file includes support for manager transactions over
306  * http.
307  * \section ami AMI - The manager Interface
308  * \arg \link Config_ami Configuration file \endlink
309  */
310
311 /*
312  * Doxygen Groups
313  */
314
315 /*! \addtogroup configuration_file Configuration Files
316  */
317
318 /*! 
319  * \addtogroup cdr_drivers Module: CDR Drivers
320  * \section CDR_generic Asterisk CDR Drivers
321  * \brief CDR drivers are loaded dynamically, each loaded CDR driver produce 
322  *        a billing record for each call.
323  * \arg \ref Config_mod "Modules Configuration"
324  * \arg \ref Config_cdr "CDR Configuration"
325  */
326
327 /*! 
328  * \addtogroup channel_drivers Module: Asterisk Channel Drivers
329  * \section channel_generic Asterisk Channel Drivers
330  * \brief Channel drivers are loaded dynamically. 
331  * \arg \ref Config_mod "Modules Configuration"
332  */
333
334 /*! 
335  * \addtogroup applications Dial plan applications
336  * \section app_generic Asterisk Dial Plan Applications
337  * \brief Applications support the dialplan. They register dynamically with 
338  *        \see ast_register_application() and unregister with 
339  *        \see ast_unregister_application()
340  * \par See also
341  * \arg \ref functions
342  */
343
344 /*! 
345  * \addtogroup functions Module: Dial plan functions
346  * \section func_generic Asterisk Dial Plan Functions
347  * \brief Functions support the dialplan.  They do not change any property of a channel
348  *        or touch a channel in any way.
349  * \par See also
350  * \arg \ref applications
351  *  
352  */
353
354 /*! 
355  * \addtogroup codecs Module: Codecs
356  * \section codec_generic Asterisk Codec Modules
357  * Codecs are referenced in configuration files by name 
358  * \par See also 
359  * \arg \ref formats 
360  */
361
362 /*! 
363  * \addtogroup formats Module: Media File Formats 
364  * \section codec_generic Asterisk Format drivers
365  * Formats are modules that read or write media files to disk.
366  * \par See also
367  * \arg \ref codecs 
368  */
369
370 /*! 
371  * \addtogroup rtp_engines Module: RTP Engines
372  * \section rtp_engine_blah Asterisk RTP Engines
373  */