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