Adding some generic docs on extension and device states - watchers and providers
[asterisk/asterisk.git] / include / asterisk / doxyref.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /* \file This file generates Doxygen pages from files in the /doc
20  directory of the Asterisk source code tree 
21  */
22
23 /* The following is for Doxygen Developer's documentation generated
24  * by running "make progdocs" with doxygen installed on your
25  * system.
26  */
27 /*! \page DevDoc Asterisk Developer's Documentation - appendices
28  *  \arg \ref CodeGuide : The must-read document for all developer's
29  *  \arg \ref AstAPI
30  *  \arg \ref Def_Channel : What's a channel, anyway?
31  *  \arg \ref channel_drivers : Existing channel drivers
32  *  \arg \ref AstDebug : Hints on debugging
33  *  \arg \ref AstAMI : The Call management socket API
34  *  \arg \ref AstARA : A generic data storage and retrieval API for Asterisk
35  *  \arg \ref AstDUNDi : A way to find phone services dynamically by using the DUNDi protocol
36  *  \arg \ref AstCDR
37  *  \arg \ref AstREADME
38  *  \arg \ref AstVar
39  *  \arg \ref AstVideo
40  *  \arg \ref AstENUM : The IETF way to redirect from phone numbers to VoIP calls
41  *  \arg \ref AstHTTP
42  *  \arg \ref AstSpeech
43  *  \arg \ref ConfigFiles
44  *  \arg \ref SoundFiles included in the Asterisk distribution
45  *  \arg \ref AstCREDITS : A Thank You to contributors
46  \n\n
47  * \section weblinks Web sites
48  * \arg \b Main:  Asterisk Developer's website http://www.asterisk.org/developers/
49  * \arg \b Bugs: The Issue tracker http://bugs.digium.com
50  * \arg \b Lists: List server http://lists.digium.com
51  * \arg \b Wiki: The Asterisk Wiki      http://www.voip-info.org
52  * \arg \b Docs: The Asterisk Documentation Project http://www.asteriskdocs.org
53  * \arg \b Digium: The Asterisk company http://www.digium.com
54  *
55  */
56
57 /*! \page CodeGuide Coding Guidelines
58  *  \section Coding Guidelines
59  *  This file is in the /doc directory in your Asterisk source tree.
60  *  Make sure to stay up to date with the latest guidelines.
61  *  \verbinclude CODING-GUIDELINES
62  */
63
64 /*! \page AstAPI Asterisk API
65  *  \section Asteriskapi Asterisk API
66  *  Some generic documents on the Asterisk architecture
67  *
68  *  \arg \ref AstThreadStorage
69  *  \arg \ref DataStores
70  *  \arg \ref AstExtState
71  *
72  *  \subsection model_txt Generic Model
73  *  \verbinclude model.txt
74  *  \subsection channel_txt Channels
75  *  \arg See \ref Def_Channel
76  */
77
78 /*! \page AstDebug Debugging
79  *  \section debug Debugging
80  *  \verbinclude backtrace.txt
81  */
82
83 /*! \page AstSpeech The Generic Speech Recognition API
84  *  \section debug The Generic Speech Recognition API
85  *  \verbinclude speechrec.txt
86  */
87
88 /*! \page DataStores Channel Data Stores
89  *  \section debug Channel Data Stores
90  *  \verbinclude datastores.txt
91  */
92
93 /*! \page AstAMI AMI - The Manager Interface
94  *  \section ami AMI - The manager Interface
95  *  \arg \link Config_ami Configuration file \endlink
96  * \arg \ref manager.c
97  *  \verbinclude manager.txt
98  */
99
100 /*!  \page AstARA ARA - The Asterisk Realtime Interface
101  *  \section realtime ARA - a generic API to storage and retrieval
102  *  Implemented in \ref config.c 
103  *  Implemented in \ref pbx_realtime.c 
104  *  \verbinclude realtime.txt
105  *  \verbinclude extconfig.txt
106  */
107
108 /*!  \page AstDUNDi DUNDi
109 DUNDi is a peer-to-peer system for locating Internet gateways to telephony services. Unlike traditional centralized services (such as the remarkably simple and concise ENUM standard), DUNDi is fully-distributed with no centralized authority whatsoever.
110
111 DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it publishes routes which are in turn accessed via industry standard protocols such as IAX, SIP and H.323. 
112
113         \par References
114         \arg DUNDi is documented at http://www.dundi.com
115         \arg Implemented in \ref pbx_dundi.c and \ref dundi-parser.c
116         \arg Configuration in \link Config_dun dundi.conf \endlink
117  */
118
119 /*! \page AstCDR CDR - Call Data Records and billing
120  * \section cdr Call Data Records
121  * \par See also
122  * \arg \ref cdr.c
123  * \arg \ref cdr_drivers
124  * \arg \ref Config_cdr CDR configuration files
125  *
126  * \verbinclude cdrdriver.txt
127  */
128
129 /*! \page AstREADME README - the general administrator introduction
130  *  \verbinclude README
131  */
132  
133 /*! \page AstCREDITS CREDITS
134  *  \verbinclude CREDITS
135  */
136
137 /*! \page AstVideo Video support in Asterisk
138  * \section sectAstVideo Video support in Asterisk
139  *  \verbinclude video.txt
140  */
141
142 /*! \page AstVar Globally predefined channel variables
143  * \section globchan Globally predefined channel variables
144  *
145  * More and more of these variables are being replaced by dialplan functions.
146  * Some still exist though and some that does still exist needs to move to
147  * dialplan functions.
148  *
149  * See also
150  * - \ref pbx_retrieve_variable()
151  * - \ref AstChanVar
152  *
153  *  \verbinclude channelvariables.txt
154
155  */
156
157 /*! \page AstChanVar Asterisk Dialplan Variables
158  *      Asterisk Dialplan variables are divided into three groups:
159  *      - Predefined global variables, handled by the PBX core
160  *      - Global variables, that exist for the duration of the pbx execution
161  *      - Channel variables, that exist during a channel
162  *
163  * Global variables are reachable in all channels, all of the time.
164  * Channel variables are only reachable within the channel.
165  *
166  * For more information on the predefined variables, see \ref AstVar
167  * 
168  * Global and Channel variables:
169  * - Names are Case insensitive
170  * - Names that start with a character, but are alphanumeric
171  * - Global variables are defined and reached with the GLOBAL() dialplan function
172  *   and the set application, like
173  *
174  *      exten => 1234,1,set(GLOBAL(myvariable)=tomteluva)
175  *
176  *      - \ref func_global.c
177  *
178  * - Channel variables are defined with the set() dialplan application
179  *
180  *      exten => 1234,1,set(xmasattribute=tomtegröt)
181  *
182  * - Some channels also supports setting channel variables with the \b setvar=
183  *   configuraiton option for a device or line.
184  *
185  * \section AstChanVar_globalvars Global Variables
186  * Global variables can also be set in the [globals] section of extensions.conf. The
187  * setting \b clearglobalvars in extensions.conf [general] section affects whether
188  * or not the global variables defined in \b globals are reset at dialplan reload.
189  * 
190  * There are CLI commands to change and read global variables. This can be handy
191  * to reset counters at midnight from an external script.
192  *
193  * \section AstChanVar_devnotes Developer notes
194  * Variable handling is managed within \ref pbx.c
195  * You need to include pbx.h to reach these functions.
196  *      - \ref pbx_builtin_setvar_helper()
197  *      - \ref pbx_builtin_getvar_helper()
198  *
199  * The variables is a linked list stored in the channel data structure
200  * with the list starting at varshead in struct ast_channel
201  * 
202  *
203  */
204
205 /*! \page AstENUM ENUM
206  * \section enumreadme ENUM
207  * \arg Configuration: \ref Config_enum
208  * \arg \ref enum.c
209  * \arg \ref func_enum.c
210  *
211  * \verbinclude enum.txt
212  */
213
214 /*! \page ConfigFiles Configuration files
215  * \section config Main configuration files
216  * \arg \link Config_ast asterisk.conf - the main configuration file \endlink
217  * \arg \link Config_ext extensions.conf - The Dial Plan \endlink
218  * \arg \link Config_mod modules.conf - which modules to load and not to load \endlink
219  * \arg \link Config_fea features.conf - call features (transfer, parking, etc) \endlink
220  * \section chanconf Channel configuration files
221  * \arg \link Config_iax IAX2 configuration  \endlink
222  * \arg \link Config_sip SIP configuration  \endlink
223  * \arg \link Config_mgcp MGCP configuration  \endlink
224  * \arg \link Config_rtp RTP configuration  \endlink
225  * \arg \link Config_zap Zaptel configuration  \endlink
226  * \arg \link Config_oss OSS (sound card) configuration  \endlink
227  * \arg \link Config_alsa ALSA (sound card) configuration  \endlink
228  * \arg \link Config_agent Agent (proxy channel) configuration  \endlink
229  * \arg \link Config_misdn MISDN Experimental ISDN BRI channel configuration  \endlink
230  * \arg \link Config_h323 H.323 configuration  \endlink
231  * \section appconf Application configuration files
232  * \arg \link Config_mm Meetme (conference bridge) configuration  \endlink
233  * \arg \link Config_qu Queue system configuration  \endlink
234  * \arg \link Config_vm Voicemail configuration  \endlink
235  * \arg \link Config_followme Followme configuration  \endlink
236  * \section cdrconf CDR configuration files
237  * \arg \link Config_cdr CDR configuration  \endlink
238  * \arg \link cdr_custom Custom CDR driver configuration \endlink
239  * \arg \link cdr_ami Manager CDR driver configuration \endlink
240  * \arg \link cdr_odbc ODBC CDR driver configuration \endlink
241  * \arg \link cdr_pgsql PostgreSQL CDR driver configuration \endlink
242  * \arg \link cdr_sqlite SQLite CDR driver configuration \endlink
243  * \arg \link cdr_tds FreeTDS CDR driver configuration (Microsoft SQL Server) \endlink
244  * \section miscconf Miscellenaous configuration files
245  * \arg \link Config_adsi ADSI configuration  \endlink
246  * \arg \link Config_ami AMI - Manager configuration  \endlink
247  * \arg \link Config_ara Realtime configuration  \endlink
248  * \arg \link Config_codec Codec configuration  \endlink
249  * \arg \link Config_dun DUNDi configuration  \endlink
250  * \arg \link Config_enum ENUM configuration  \endlink
251  * \arg \link Config_moh Music on Hold configuration  \endlink
252  * \arg \link Config_vm Voicemail configuration  \endlink
253  */
254
255 /*! \page Config_ast Asterisk.conf
256  * \verbinclude asterisk-conf.txt
257  */
258 /*! \page Config_mod Modules configuration
259  * All res_ resource modules are loaded with globals on, which means
260  * that non-static functions are callable from other modules.
261  *
262  * If you want your non res_* module to export functions to other modules
263  * you have to include it in the [global] section.
264  * \verbinclude modules.conf.sample
265  */
266
267 /*! \page Config_fea Call features configuration
268  * \par See also
269  * \arg \ref res_features.c : Call feature implementation
270  * \section featconf features.conf
271  * \verbinclude features.conf.sample
272  */
273
274 /*! \page Config_followme Followme: An application for simple follow-me calls
275  * \section followmeconf Followme.conf
276  * - See app_followme.c
277  * \verbinclude followme.conf.sample
278  */
279
280 /*! \page Config_ext Extensions.conf - the Dial Plan
281  * \section dialplan Extensions.conf 
282  * \verbinclude extensions.conf.sample
283  */
284
285 /*! \page Config_iax IAX2 configuration
286  * IAX2 is implemented in \ref chan_iax2.c
287  * \arg \link Config_iax iax.conf Configuration file example \endlink
288  * \section iaxreadme IAX readme file
289  * \verbinclude iax.txt
290  * \section Config_iax IAX Configuration example
291  * \verbinclude iax.conf.sample
292  * \section iaxjitter IAX Jitterbuffer information
293  * \verbinclude jitterbuffer.txt
294  */
295
296 /*! \page Config_iax IAX configuration
297  * \arg Implemented in \ref chan_iax2.c
298  * \section iaxconf iax.conf
299  * \verbinclude iax.conf.sample
300  */
301
302 /*! \page Config_sip SIP configuration
303  * Also see \ref Config_rtp RTP configuration
304  * \arg Implemented in \ref chan_sip.c
305  * \section sipconf sip.conf
306  * \verbinclude sip.conf.sample
307  *
308  * \arg \b Back \ref chanconf
309  */
310
311 /*! \page Config_mgcp MGCP configuration
312  * Also see \ref Config_rtp RTP configuration
313  * \arg Implemented in \ref chan_mgcp.c
314  * \section mgcpconf mgcp.conf
315  * \verbinclude mgcp.conf.sample
316  */
317
318 /*! \page README_misdn MISDN documentation
319  * \arg See \ref Config_misdn
320  * \section mISDN configuration
321  * \verbinclude misdn.txt
322  */
323
324 /*! \page Config_misdn MISDN configuration
325  * \arg Implemented in \ref chan_misdn.c
326  * \arg \ref README_misdn
327  * \arg See the mISDN home page: http://www.isdn4linux.de/mISDN/
328  * \section misdnconf misdn.conf
329  * \verbinclude misdn.conf.sample
330  */
331
332 /*! \page Config_vm VoiceMail configuration
333  * \section vmconf voicemail.conf
334  * \arg Implemented in \ref app_voicemail.c
335  * \verbinclude voicemail.conf.sample
336  */
337
338 /*! \page Config_zap Zaptel configuration
339  * \section zapconf zapata.conf
340  * \arg Implemented in \ref chan_zap.c
341  * \verbinclude zapata.conf.sample
342  */
343
344 /*! \page Config_h323 H.323 channel driver information
345  * This is the configuration of the H.323 channel driver within the Asterisk
346  * distribution. There's another one, called OH323, in asterisk-addons
347  * \arg Implemented in \ref chan_h323.c
348  * \section h323conf h323.conf
349  * \ref chan_h323.c
350  * \verbinclude h323.txt
351  */
352
353 /*! \page Config_oss OSS configuration
354  * \section ossconf oss.conf
355  * \arg Implemented in \ref chan_oss.c
356  * \verbinclude oss.conf.sample
357  */
358
359 /*! \page Config_alsa ALSA configuration
360  * \section alsaconf alsa.conf
361  * \arg Implemented in \ref chan_alsa.c
362  * \verbinclude alsa.conf.sample
363  */
364
365 /*! \page Config_agent Agent configuration
366  * \section agentconf agents.conf
367  * The agent channel is a proxy channel for queues
368  * \arg Implemented in \ref chan_agent.c
369  * \verbinclude agents.conf.sample
370  */
371
372 /*! \page Config_rtp RTP configuration
373  * \arg Implemented in \ref rtp.c
374  * Used in \ref chan_sip.c and \ref chan_mgcp.c (and various H.323 channels)
375  * \section rtpconf rtp.conf
376  * \verbinclude rtp.conf.sample
377  */
378
379 /*! \page Config_dun DUNDi Configuration
380  * \arg See also \ref AstDUNDi
381  * \section dundiconf dundi.conf
382  * \verbinclude dundi.conf.sample
383  */
384
385 /*! \page Config_enum ENUM Configuration
386  * \section enumconf enum.conf
387  * \arg See also \ref enumreadme
388  * \arg Implemented in \ref func_enum.c and \ref enum.c
389  * \verbinclude enum.conf.sample
390  */
391
392 /*! \page cdr_custom Custom CDR Configuration
393  * \par See also 
394  * \arg \ref cdrconf
395  * \arg \ref cdr_custom.c
396  * \verbinclude cdr_custom.conf.sample
397  */
398
399 /*! \page cdr_ami Manager CDR driver configuration
400  * \par See also 
401  * \arg \ref cdrconf
402  * \arg \ref AstAMI
403  * \arg \ref cdr_manager.c
404  * \verbinclude cdr_manager.conf.sample
405  */
406
407 /*! \page cdr_odbc ODBC CDR driver configuration
408  * \arg See also \ref cdrconf
409  * \arg \ref cdr_odbc.c
410  * \verbinclude cdr_odbc.conf.sample
411  * See also:
412  * \arg http://www.unixodbc.org
413  */
414
415 /*! \page cdr_pgsql PostgreSQL CDR driver configuration
416  * \arg See also \ref cdrconf
417  * \arg \ref cdr_pgsql.c
418  * See also:
419  * \arg http://www.postgresql.org
420  * \verbinclude cdr_pgsql.conf.sample
421  */
422
423 /*! \page cdr_sqlite SQLite CDR driver configuration
424  * \arg See also \ref cdrconf
425  * \arg \ref cdr_sqlite.c
426  * See also:
427  * \arg http://www.sqlite.org
428  */
429
430 /*! \page cdr_tds FreeTDS CDR driver configuration
431  * \arg See also \ref cdrconf
432  * See also:
433  * \arg http://www.freetds.org
434  * \verbinclude cdr_tds.conf.sample
435  */
436
437 /*! \page Config_cdr CDR configuration
438  * \par See also
439  * \arg \ref cdr_drivers
440  * \arg \link Config_cdr CDR configuration  \endlink  
441  * \arg \link cdr_custom Custom CDR driver configuration \endlink
442  * \arg \link cdr_ami Manager CDR driver configuration \endlink
443  * \arg \link cdr_odbc ODBC CDR driver configuration \endlink
444  * \arg \link cdr_pgsql PostgreSQL CDR driver configuration \endlink
445  * \arg \link cdr_sqlite SQLite CDR driver configuration \endlink
446  * \arg \link cdr_tds FreeTDS CDR driver configuration (Microsoft SQL Server) \endlink
447  * \verbinclude cdr.conf.sample
448  */
449
450 /*! \page Config_moh Music on Hold Configuration
451  * \arg Implemented in \ref res_musiconhold.c
452  * \section mohconf musiconhold.conf
453  * \verbinclude musiconhold.conf.sample
454  */
455
456 /*! \page Config_adsi ADSI Configuration
457  * \section adsiconf adsi.conf
458  * \verbinclude adsi.conf.sample
459  */
460
461 /*! \page Config_codec CODEC Configuration
462  * \section codecsconf codecs.conf
463  * \verbinclude codecs.conf.sample
464  */
465
466 /*! \page Config_ara REALTIME Configuration
467  * \arg See also: \arg \link AstARA \endlink
468  * \section extconf extconfig.conf
469  * \verbinclude extconfig.conf.sample
470  */
471
472 /*! \page Config_ami AMI configuration
473  * \arg See also: \arg \link AstAMI \endlink
474  * \section amiconf manager.conf
475  * \verbinclude manager.conf.sample
476  */
477
478 /*! \page Config_qu ACD - Queue system configuration
479  * \arg Implemented in \ref app_queue.c
480  * \section quconf queues.conf
481  * \verbinclude queues.conf.sample
482  */
483
484 /*! \page Config_mm Meetme - The conference bridge configuration
485  * \arg Implemented in \ref app_meetme.c
486  * \section mmconf meetme.conf
487  * \verbinclude meetme.conf.sample
488  */
489
490 /*! \page SoundFiles Sound files
491  *  \section SecSound Asterisk Sound files
492  *  Asterisk includes a large number of sound files. Many of these
493  *  are used by applications and demo scripts within asterisk.
494  *
495  *  Additional sound files are available in the asterisk-addons
496  *  repository on svn.digium.com
497  */
498
499 /*! \addtogroup cdr_drivers Module: CDR Drivers
500  *  \section CDR_generic Asterisk CDR Drivers
501  *  \brief CDR drivers are loaded dynamically (see \ref Config_mod "Modules Configuration"). Each loaded CDR driver produce a billing record for each call.
502  *  \arg \ref Config_cdr "CDR Configuration"
503  */
504
505
506 /*! \addtogroup channel_drivers Module: Asterisk Channel Drivers
507  *  \section channel_generic Asterisk Channel Drivers
508  *  \brief Channel drivers are loaded dynamically (see \ref Config_mod "Modules Configuration"). 
509  */
510
511 /*! \addtogroup applications Module: Dial plan applications
512  *  \section app_generic Asterisk Dial Plan Applications
513  *  \brief Applications support the dialplan. They register dynamically with \ref ast_register_application() and unregister with ast_unregister_application()
514  * \par See also
515  * \arg \ref functions
516  *  
517  */
518
519 /*! \addtogroup functions Module: Dial plan functions
520  *  \section func_generic Asterisk Dial Plan Functions
521  *  \brief Functions support the dialplan.  They do not change any property of a channel
522  *  or touch a channel in any way.
523  * \par See also
524  * \arg \ref applications
525  *  
526  */
527
528 /*! \addtogroup codecs Module: Codecs
529  *  \section codec_generic Asterisk Codec Modules
530  *  Codecs are referenced in configuration files by name 
531  *  \par See also 
532  *  \arg \ref formats 
533  *
534  */
535
536 /*! \addtogroup formats Module: Media File Formats 
537  *  \section codec_generic Asterisk Format drivers
538  *  Formats are modules that read or write media files to disk.
539  *  \par See also
540  *  \arg \ref codecs 
541  */
542
543 /*! \page AstHTTP AMI over HTTP support
544  * The http.c file includes support for manager transactions over
545  * http.
546  *  \section ami AMI - The manager Interface
547  *  \arg \link Config_ami Configuration file \endlink
548  *  \verbinclude ajam.txt
549  */
550