From b1f91b97d2085cc845d0f57bd9907de50c995105 Mon Sep 17 00:00:00 2001 From: russell Date: Sat, 1 Nov 2008 21:10:07 +0000 Subject: Merge changes from team/group/appdocsxml This commit introduces the first phase of an effort to manage documentation of the interfaces in Asterisk in an XML format. Currently, a new format is available for applications and dialplan functions. A good number of conversions to the new format are also included. For more information, see the following message to asterisk-dev: http://lists.digium.com/pipermail/asterisk-dev/2008-October/034968.html git-svn-id: http://svn.digium.com/svn/asterisk/trunk@153365 f38db490-d61c-443f-a65b-d21fe96a405b --- Makefile | 26 +- apps/app_adsiprog.c | 22 +- apps/app_alarmreceiver.c | 29 +- apps/app_amd.c | 119 +- apps/app_authenticate.c | 73 +- apps/app_cdr.c | 18 +- apps/app_chanisavail.c | 66 +- apps/app_channelredirect.c | 34 +- apps/app_chanspy.c | 352 +++-- apps/app_controlplayback.c | 85 +- apps/app_dahdibarge.c | 29 +- apps/app_dahdiras.c | 31 +- apps/app_dahdiscan.c | 26 +- apps/app_dial.c | 572 ++++--- apps/app_dictate.c | 21 +- apps/app_directed_pickup.c | 59 +- apps/app_directory.c | 116 +- apps/app_disa.c | 106 +- apps/app_dumpchan.c | 29 +- apps/app_echo.c | 23 +- apps/app_exec.c | 107 +- apps/app_fax.c | 153 +- apps/app_festival.c | 27 +- apps/app_getcpeid.c | 21 +- apps/app_ices.c | 31 +- apps/app_image.c | 41 +- apps/app_jack.c | 52 +- apps/app_milliwatt.c | 33 +- apps/app_mixmonitor.c | 98 +- apps/app_morsecode.c | 37 +- apps/app_mp3.c | 28 +- apps/app_nbscat.c | 22 +- apps/app_page.c | 67 +- apps/app_playback.c | 63 +- apps/app_privacy.c | 52 +- apps/app_queue.c | 501 +++++-- apps/app_readexten.c | 105 +- apps/app_readfile.c | 37 +- apps/app_record.c | 85 +- apps/app_sayunixtime.c | 69 +- apps/app_senddtmf.c | 35 +- apps/app_sendtext.c | 43 +- apps/app_setcallerid.c | 65 +- apps/app_skel.c | 34 +- apps/app_softhangup.c | 31 +- apps/app_stack.c | 93 +- apps/app_system.c | 79 +- apps/app_talkdetect.c | 48 +- apps/app_transfer.c | 51 +- apps/app_url.c | 61 +- apps/app_userevent.c | 40 +- apps/app_verbose.c | 49 +- apps/app_waituntil.c | 41 +- apps/app_while.c | 89 +- apps/app_zapateller.c | 53 +- build_tools/get_documentation | 3 + configure | 266 +++- configure.ac | 23 + doc/appdocsxml.dtd | 64 + doc/tex/asterisk-conf.tex | 3 + funcs/func_base64.c | 35 +- funcs/func_blacklist.c | 17 +- funcs/func_callerid.c | 89 +- funcs/func_cdr.c | 163 +- funcs/func_channel.c | 243 ++- funcs/func_config.c | 22 +- funcs/func_cut.c | 57 +- funcs/func_db.c | 69 +- funcs/func_devstate.c | 79 +- funcs/func_dialgroup.c | 52 +- funcs/func_dialplan.c | 20 +- funcs/func_enum.c | 137 +- funcs/func_env.c | 79 +- funcs/func_extstate.c | 34 +- funcs/func_global.c | 66 +- funcs/func_groupcount.c | 78 +- funcs/func_iconv.c | 35 +- funcs/func_lock.c | 67 +- funcs/func_logic.c | 92 +- funcs/func_math.c | 40 +- funcs/func_md5.c | 16 +- funcs/func_module.c | 23 +- funcs/func_odbc.c | 124 +- funcs/func_rand.c | 25 +- funcs/func_realtime.c | 88 +- funcs/func_sha1.c | 25 +- funcs/func_shell.c | 32 +- funcs/func_speex.c | 73 +- funcs/func_strings.c | 332 +++-- funcs/func_timeout.c | 59 +- funcs/func_uri.c | 33 +- funcs/func_version.c | 56 +- funcs/func_vmcount.c | 29 +- funcs/func_volume.c | 27 +- include/asterisk/_private.h | 6 + include/asterisk/autoconfig.h.in | 3 + include/asterisk/compat.h | 11 + include/asterisk/extconf.h | 10 +- include/asterisk/module.h | 17 + include/asterisk/pbx.h | 20 +- include/asterisk/strings.h | 15 + include/asterisk/term.h | 22 + include/asterisk/xml.h | 122 ++ main/Makefile | 4 +- main/asterisk.c | 6 + main/config.c | 18 - main/features.c | 141 +- main/pbx.c | 3026 ++++++++++++++++++++++++++++++++------ main/term.c | 64 +- main/xml.c | 195 +++ makeopts.in | 3 + 111 files changed, 8160 insertions(+), 2575 deletions(-) create mode 100644 build_tools/get_documentation create mode 100644 doc/appdocsxml.dtd create mode 100644 include/asterisk/xml.h create mode 100644 main/xml.c diff --git a/Makefile b/Makefile index 7b017f22f..0521518e0 100644 --- a/Makefile +++ b/Makefile @@ -105,6 +105,9 @@ endif ASTCFLAGS+=$(COPTS) ASTLDFLAGS+=$(LDOPTS) +# libxml2 cflags +ASTCFLAGS+=$(LIBXML2_INCLUDE) + #Uncomment this to see all build commands instead of 'quiet' output #NOISY_BUILD=yes @@ -481,6 +484,20 @@ datafiles: _all mkdir -p $(DESTDIR)$(AGI_DIR) $(MAKE) -C sounds install +documentation: + @echo -n "Building Documentation For: " + @echo "" > doc/core-en_US.xml + @echo "" >> doc/core-en_US.xml + @echo "" >> doc/core-en_US.xml + @for x in $(MOD_SUBDIRS); do \ + echo -n "$$x " ; \ + for i in $$x/*.c; do \ + $(AWK) -f build_tools/get_documentation $$i >> doc/core-en_US.xml ; \ + done ; \ + done + @echo "" >> doc/core-en_US.xml + @echo -e "\ndoc/core-en_US.xml --> $(ASTDATADIR)/documentation/core-en_US.xml" + update: @if [ -d .svn ]; then \ echo "Updating from Subversion..." ; \ @@ -529,12 +546,16 @@ bininstall: _all installdirs $(SUBDIRS_INSTALL) if [ -n "$(OLDHEADERS)" ]; then \ rm -f $(addprefix $(DESTDIR)$(ASTHEADERDIR)/,$(OLDHEADERS)) ;\ fi + mkdir -p $(DESTDIR)$(ASTDATADIR)/documentation + mkdir -p $(DESTDIR)$(ASTDATADIR)/documentation/thirdparty mkdir -p $(DESTDIR)$(ASTLOGDIR)/cdr-csv mkdir -p $(DESTDIR)$(ASTLOGDIR)/cdr-custom mkdir -p $(DESTDIR)$(ASTDATADIR)/keys mkdir -p $(DESTDIR)$(ASTDATADIR)/firmware mkdir -p $(DESTDIR)$(ASTDATADIR)/firmware/iax mkdir -p $(DESTDIR)$(ASTMANDIR)/man8 + $(INSTALL) -m 644 doc/core-*.xml $(ASTDATADIR)/documentation + $(INSTALL) -m 644 doc/appdocsxml.dtd $(ASTVARLIBDIR)/documentation $(INSTALL) -m 644 keys/iaxtel.pub $(DESTDIR)$(ASTDATADIR)/keys $(INSTALL) -m 644 keys/freeworlddialup.pub $(DESTDIR)$(ASTDATADIR)/keys $(INSTALL) -m 644 doc/asterisk.8 $(DESTDIR)$(ASTMANDIR)/man8 @@ -576,7 +597,7 @@ ifneq ($(findstring ~,$(DESTDIR)),) @exit 1 endif -install: badshell datafiles bininstall +install: badshell datafiles documentation bininstall @if [ -x /usr/sbin/asterisk-post-install ]; then \ /usr/sbin/asterisk-post-install $(DESTDIR) . ; \ fi @@ -656,7 +677,7 @@ samples: adsi echo "astrundir => $(ASTVARRUNDIR)" ; \ echo "astlogdir => $(ASTLOGDIR)" ; \ echo "" ; \ - echo ";[options]" ; \ + echo "[options]" ; \ echo ";verbose = 3" ; \ echo ";debug = 3" ; \ echo ";alwaysfork = yes ; same as -F at startup" ; \ @@ -686,6 +707,7 @@ samples: adsi echo ";runuser = asterisk ; The user to run as" ; \ echo ";rungroup = asterisk ; The group to run as" ; \ echo ";lightbackground = yes ; If your terminal is set for a light-colored background" ; \ + echo "documentation_language = en_US ; Set the Language you want Documentation displayed in. Value is in the same format as locale names" ; \ echo "" ; \ echo "; Changing the following lines may compromise your security." ; \ echo ";[files]" ; \ diff --git a/apps/app_adsiprog.c b/apps/app_adsiprog.c index 255026fbd..f35a81eea 100644 --- a/apps/app_adsiprog.c +++ b/apps/app_adsiprog.c @@ -47,14 +47,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "ADSIProg"; -static char *synopsis = "Load Asterisk ADSI Scripts into phone"; +/*** DOCUMENTATION + + + Load Asterisk ADSI Scripts into phone + + + + adsi script to use. If not given uses the default script asterisk.adsi + + + + This application programs an ADSI Phone with the given script + + + ***/ /* #define DUMP_MESSAGES */ -static char *descrip = -" ADSIProg(script): This application programs an ADSI Phone with the given\n" -"script. If nothing is specified, the default script (asterisk.adsi) is used.\n"; - struct adsi_event { int id; char *name; @@ -1570,7 +1580,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(app, adsi_exec, synopsis, descrip)) + if (ast_register_application_xml(app, adsi_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_alarmreceiver.c b/apps/app_alarmreceiver.c index db76bbdb7..12ae49d65 100644 --- a/apps/app_alarmreceiver.c +++ b/apps/app_alarmreceiver.c @@ -63,18 +63,21 @@ struct event_node{ typedef struct event_node event_node_t; static char *app = "AlarmReceiver"; - -static char *synopsis = "Provide support for receiving alarm reports from a burglar or fire alarm panel"; -static char *descrip = -" AlarmReceiver(): Only 1 signalling format is supported at this time: Ademco\n" -"Contact ID. This application should be called whenever there is an alarm\n" -"panel calling in to dump its events. The application will handshake with the\n" -"alarm panel, and receive events, validate them, handshake them, and store them\n" -"until the panel hangs up. Once the panel hangs up, the application will run the\n" -"system command specified by the eventcmd setting in alarmreceiver.conf and pipe\n" -"the events to the standard input of the application. The configuration file also\n" -"contains settings for DTMF timing, and for the loudness of the acknowledgement\n" -"tones.\n"; +/*** DOCUMENTATION + + + Provide support for receiving alarm reports from a burglar or fire alarm panel + + + + This application should be called whenever there is an alarm panel calling in to dump its events. + The application will handshake with the alarm panel, and receive events, validate them, handshake them, and store them until the panel hangs up. + Once the panel hangs up, the application will run the system command specified by the eventcmd setting in alarmreceiver.conf and pipe the events to the standard input of the application. + The configuration file also contains settings for DTMF timing, and for the loudness of the acknowledgement tones. + Only 1 signalling format is supported at this time: Ademco Contact ID. + + + ***/ /* Config Variables */ static int fdtimeout = 2000; @@ -711,7 +714,7 @@ static int unload_module(void) static int load_module(void) { if (load_config()) { - if (ast_register_application(app, alarmreceiver_exec, synopsis, descrip)) + if (ast_register_application_xml(app, alarmreceiver_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } else diff --git a/apps/app_amd.c b/apps/app_amd.c index 81298f400..bf3603b3e 100644 --- a/apps/app_amd.c +++ b/apps/app_amd.c @@ -39,45 +39,88 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/config.h" #include "asterisk/app.h" +/*** DOCUMENTATION + + + Attempt to detect answering machines. + + + + Is maximum initial silence duration before greeting. + If this is exceeded set as MACHINE + + + is the maximum length of a greeting. + If this is exceeded set as MACHINE + + + Is the silence after detecting a greeting. + If this is exceeded set as HUMAN + + + Is the maximum time allowed for the algorithm + to decide HUMAN or MACHINE + + + Is the minimum duration of Voice considered to be a word + + + Is the minimum duration of silence after a word to + consider the audio that follows to be a new word + + + Is the maximum number of words in a greeting + If this is exceeded set as MACHINE + + + How long do we consider silence + + + Is the maximum duration of a word to accept. + If exceeded set as MACHINE + + + + This application attempts to detect answering machines at the beginning + of outbound calls. Simply call this application after the call + has been answered (outbound only, of course). + When loaded, AMD reads amd.conf and uses the parameters specified as + default values. Those default values get overwritten when the calling AMD + with parameters. + This application sets the following channel variables: + + + This is the status of the answering machine detection + + + + + + + Indicates the cause that led to the conclusion + + Total Time. + + + Silence Duration - Initial Silence. + + + Silence Duration - afterGreetingSilence. + + + Voice Duration - Greeting. + + + Word Count - maximum number of words. + + + + + + + ***/ static char *app = "AMD"; -static char *synopsis = "Attempts to detect answering machines"; -static char *descrip = -" AMD([initialSilence],[greeting],[afterGreetingSilence],[totalAnalysisTime]\n" -" ,[minimumWordLength],[betweenWordsSilence],[maximumNumberOfWords]\n" -" ,[silenceThreshold],[|maximumWordLength])\n" -" This application attempts to detect answering machines at the beginning\n" -" of outbound calls. Simply call this application after the call\n" -" has been answered (outbound only, of course).\n" -" When loaded, AMD reads amd.conf and uses the parameters specified as\n" -" default values. Those default values get overwritten when calling AMD\n" -" with parameters.\n" -"- 'initialSilence' is the maximum silence duration before the greeting. If\n" -" exceeded then MACHINE.\n" -"- 'greeting' is the maximum length of a greeting. If exceeded then MACHINE.\n" -"- 'afterGreetingSilence' is the silence after detecting a greeting.\n" -" If exceeded then HUMAN.\n" -"- 'totalAnalysisTime' is the maximum time allowed for the algorithm to decide\n" -" on a HUMAN or MACHINE.\n" -"- 'minimumWordLength'is the minimum duration of Voice to considered as a word.\n" -"- 'betweenWordsSilence' is the minimum duration of silence after a word to \n" -" consider the audio that follows as a new word.\n" -"- 'maximumNumberOfWords'is the maximum number of words in the greeting. \n" -" If exceeded then MACHINE.\n" -"- 'silenceThreshold' is the silence threshold.\n" -"- 'maximumWordLength' is the maximum duration of a word to accept. If exceeded then MACHINE\n" -"This application sets the following channel variables upon completion:\n" -" AMDSTATUS - This is the status of the answering machine detection.\n" -" Possible values are:\n" -" MACHINE | HUMAN | NOTSURE | HANGUP\n" -" AMDCAUSE - Indicates the cause that led to the conclusion.\n" -" Possible values are:\n" -" TOOLONG-<%d total_time>\n" -" INITIALSILENCE-<%d silenceDuration>-<%d initialSilence>\n" -" HUMAN-<%d silenceDuration>-<%d afterGreetingSilence>\n" -" MAXWORDS-<%d wordsCount>-<%d maximumNumberOfWords>\n" -" LONGGREETING-<%d voiceDuration>-<%d greeting>\n" -" MAXWORDLENGTH-<%d consecutiveVoiceDuration>\n"; #define STATE_IN_WORD 1 #define STATE_IN_SILENCE 2 @@ -437,7 +480,7 @@ static int load_module(void) { if (load_config(0)) return AST_MODULE_LOAD_DECLINE; - if (ast_register_application(app, amd_exec, synopsis, descrip)) + if (ast_register_application_xml(app, amd_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_authenticate.c b/apps/app_authenticate.c index 1bdc1153b..10d0b2f73 100644 --- a/apps/app_authenticate.c +++ b/apps/app_authenticate.c @@ -54,31 +54,52 @@ AST_APP_OPTIONS(auth_app_options, { static char *app = "Authenticate"; - -static char *synopsis = "Authenticate a user"; - -static char *descrip = -" Authenticate(password[,options[,maxdigits[,prompt]]]): This application asks the caller\n" -"to enter a given password in order to continue dialplan execution. If the password\n" -"begins with the '/' character, it is interpreted as a file which contains a list of\n" -"valid passwords, listed 1 password per line in the file.\n" -" When using a database key, the value associated with the key can be anything.\n" -"Users have three attempts to authenticate before the channel is hung up.\n" -" Options:\n" -" a - Set the channels' account code to the password that is entered\n" -" d - Interpret the given path as database key, not a literal file\n" -" m - Interpret the given path as a file which contains a list of account\n" -" codes and password hashes delimited with ':', listed one per line in\n" -" the file. When one of the passwords is matched, the channel will have\n" -" its account code set to the corresponding account code in the file.\n" -" r - Remove the database key upon successful entry (valid with 'd' only)\n" -" maxdigits - maximum acceptable number of digits. Stops reading after\n" -" maxdigits have been entered (without requiring the user to\n" -" press the '#' key).\n" -" Defaults to 0 - no limit - wait for the user press the '#' key.\n" -" prompt - Override the agent-pass prompt file.\n" - ; -; +/*** DOCUMENTATION + + + Authenticate a user + + + + Password the user should know + + + + + + + + + + + maximum acceptable number of digits. Stops reading after + maxdigits have been entered (without requiring the user to press the # key). + Defaults to 0 - no limit - wait for the user press the # key. + + + Override the agent-pass prompt file. + + + + This application asks the caller to enter a given password in order to continue dialplan execution. + If the password begins with the / character, + it is interpreted as a file which contains a list of valid passwords, listed 1 password per line in the file. + When using a database key, the value associated with the key can be anything. + Users have three attempts to authenticate before the channel is hung up. + + + ***/ static int auth_exec(struct ast_channel *chan, void *data) { @@ -225,7 +246,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(app, auth_exec, synopsis, descrip)) + if (ast_register_application_xml(app, auth_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_cdr.c b/apps/app_cdr.c index 038b0a32f..ca228da03 100644 --- a/apps/app_cdr.c +++ b/apps/app_cdr.c @@ -32,13 +32,19 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" #include "asterisk/module.h" -static char *nocdr_descrip = -" NoCDR(): This application will tell Asterisk not to maintain a CDR for the\n" -"current call.\n"; +/*** DOCUMENTATION + + + Tell Asterisk to not maintain a CDR for the current call + + + + This application will tell Asterisk not to maintain a CDR for the current call. + + + ***/ static char *nocdr_app = "NoCDR"; -static char *nocdr_synopsis = "Tell Asterisk to not maintain a CDR for the current call"; - static int nocdr_exec(struct ast_channel *chan, void *data) { @@ -55,7 +61,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(nocdr_app, nocdr_exec, nocdr_synopsis, nocdr_descrip)) + if (ast_register_application_xml(nocdr_app, nocdr_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_chanisavail.c b/apps/app_chanisavail.c index 68cab31aa..bc1adcc79 100644 --- a/apps/app_chanisavail.c +++ b/apps/app_chanisavail.c @@ -43,22 +43,54 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "ChanIsAvail"; -static char *synopsis = "Check channel availability"; - -static char *descrip = -" ChanIsAvail(Technology/resource[&Technology2/resource2...][,options]): \n" -"This application will check to see if any of the specified channels are\n" -"available.\n" -" Options:\n" -" a - Check for all available channels, not only the first one.\n" -" s - Consider the channel unavailable if the channel is in use at all.\n" -" t - Simply checks if specified channels exist in the channel list\n" -" (implies option s).\n" -"This application sets the following channel variable upon completion:\n" -" AVAILCHAN - the name of the available channel, if one exists\n" -" AVAILORIGCHAN - the canonical channel name that was used to create the channel\n" -" AVAILSTATUS - the status code for the available channel\n"; - +/*** DOCUMENTATION + + + Check channel availability + + + + + Optional extra devices to check + If you need more then one enter them as + Technology2/Resource2&Technology3/Resourse3&..... + + Specification of the device(s) to check. These must be in the format of + Technology/Resource, where Technology + represents a particular channel driver, and Resource + represents a resource available to that particular channel driver. + + + + + + + + + + + This application will check to see if any of the specified channels are available. + This application sets the following channel variables: + + + The name of the available channel, if one exists + + + The canonical channel name that was used to create the channel + + + The status code for the available channel + + + + + ***/ static int chanavail_exec(struct ast_channel *chan, void *data) { @@ -165,7 +197,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, chanavail_exec, synopsis, descrip) ? + return ast_register_application_xml(app, chanavail_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_channelredirect.c b/apps/app_channelredirect.c index 610f254df..f89c45225 100644 --- a/apps/app_channelredirect.c +++ b/apps/app_channelredirect.c @@ -35,14 +35,32 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/features.h" +/*** DOCUMENTATION + + + Redirects given channel to a dialplan target + + + + + + + + + Sends the specified channel to the specified extension priority + + This application sets the following channel variables upon completion + + + + + Are set to the result of the redirection + + + + + ***/ static char *app = "ChannelRedirect"; -static char *synopsis = "Redirects given channel to a dialplan target."; -static char *descrip = -"ChannelRedirect(channel,[[context,]extension,]priority)\n" -" Sends the specified channel to the specified extension priority\n" -"This application sets the following channel variables upon completion:\n" -" CHANNELREDIRECT_STATUS - Are set to the result of the redirection\n" -" either NOCHANNEL or SUCCESS\n"; static int asyncgoto_exec(struct ast_channel *chan, void *data) { @@ -89,7 +107,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, asyncgoto_exec, synopsis, descrip) ? + return ast_register_application_xml(app, asyncgoto_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_chanspy.c b/apps/app_chanspy.c index dea2017ea..92a430546 100644 --- a/apps/app_chanspy.c +++ b/apps/app_chanspy.c @@ -52,128 +52,238 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define AST_NAME_STRLEN 256 #define NUM_SPYGROUPS 128 -static const char *tdesc = "Listen to a channel, and optionally whisper into it"; +/*** DOCUMENTATION + + + Listen to a channel, and optionally whisper into it. + + + + + + + + + + + + + + + + + + + + + + + + This application is used to listen to the audio from an Asterisk channel. This includes the audio + coming in and "out of the channel being spied on. If the chanprefix parameter is specified, + only channels beginning with this string will be spied upon. + While spying, the following actions may be performed: + - Dialing # cycles the volume level. + - Dialing * will stop spying and look for another channel to spy on. + - Dialing a series of digits followed by # builds a channel name to append + to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing the digits '1234#' + while spying will begin spying on the channel 'Agent/1234'. Note that this feature will be overriden if the 'd' option + is used + The X option supersedes the three features above in that if a valid + single digit extension exists in the correct context ChanSpy will exit to it. + This also disables choosing a channel based on chanprefix and a digit sequence. + + + + + Listen to a channel, and optionally whisper into it. + + + + + Specify extension. + + + Optionally specify a context, defaults to default. + + + + + + + + + + + + + + + + + + + + + + + This application is used to listen to the audio from an Asterisk channel. This includes + the audio coming in and out of the channel being spied on. Only channels created by outgoing calls for the + specified extension will be selected for spying. If the optional context is not supplied, + the current channel's context will be used. + While spying, the following actions may be performed: + - Dialing # cycles the volume level. + - Dialing * will stop spying and look for another channel to spy on. + The X option supersedes the three features above in that if a valid + single digit extension exists in the correct context ChanSpy will exit to it. + This also disables choosing a channel based on chanprefix and a digit sequence. + + + + ***/ static const char *app_chan = "ChanSpy"; -static const char *desc_chan = -" ChanSpy([chanprefix][,options]): This application is used to listen to the\n" -"audio from an Asterisk channel. This includes the audio coming in and\n" -"out of the channel being spied on. If the 'chanprefix' parameter is specified,\n" -"only channels beginning with this string will be spied upon.\n" -" While spying, the following actions may be performed:\n" -" - Dialing # cycles the volume level.\n" -" - Dialing * will stop spying and look for another channel to spy on.\n" -" - Dialing a series of digits followed by # builds a channel name to append\n" -" to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing\n" -" the digits '1234#' while spying will begin spying on the channel\n" -" 'Agent/1234'. Note that this feature will be overriden if the 'd' option\n" -" is used\n" -" Note: The X option supersedes the three features above in that if a valid\n" -" single digit extension exists in the correct context ChanSpy will\n" -" exit to it. This also disables choosing a channel based on 'chanprefix'\n" -" and a digit sequence.\n" -" Options:\n" -" b - Only spy on channels involved in a bridged call.\n" -" B - Instead of whispering on a single channel barge in on both\n" -" channels involved in the call.\n" -" d - Override the typical numeric DTMF functionality and instead\n" -" use DTMF to switch between spy modes.\n" -" 4 = spy mode\n" -" 5 = whisper mode\n" -" 6 = barge mode\n" -" g(grp) - Only spy on channels in which one or more of the groups \n" -" listed in 'grp' matches one or more groups from the\n" -" SPYGROUP variable set on the channel to be spied upon.\n" -" Note that both 'grp' and SPYGROUP can contain either a\n" -" single group or a colon-delimited list of groups, such\n" -" as 'sales:support:accounting'.\n" -" n([mailbox][@context]) - Say the name of the person being spied on if that person has recorded\n" -" his/her name. If a context is specified, then that voicemail context will\n" -" be searched when retrieving the name, otherwise the \"default\" context\n" -" will be searched. If no mailbox is specified, then the channel name will\n" -" be used when searching for the name (i.e. if SIP/1000 is the channel being\n" -" spied on and no mailbox is specified, then \"1000\" will be used when searching\n" -" for the name).\n" -" q - Don't play a beep when beginning to spy on a channel, or speak the\n" -" selected channel name.\n" -" r[(basename)] - Record the session to the monitor spool directory. An\n" -" optional base for the filename may be specified. The\n" -" default is 'chanspy'.\n" -" s - Skip the playback of the channel type (i.e. SIP, IAX, etc) when\n" -" speaking the selected channel name.\n" -" v([value]) - Adjust the initial volume in the range from -4 to 4. A\n" -" negative value refers to a quieter setting.\n" -" w - Enable 'whisper' mode, so the spying channel can talk to\n" -" the spied-on channel.\n" -" W - Enable 'private whisper' mode, so the spying channel can\n" -" talk to the spied-on channel but cannot listen to that\n" -" channel.\n" -" o - Only listen to audio coming from this channel.\n" -" X - Allow the user to exit ChanSpy to a valid single digit\n" -" numeric extension in the current context or the context\n" -" specified by the SPY_EXIT_CONTEXT channel variable. The\n" -" name of the last channel that was spied on will be stored\n" -" in the SPY_CHANNEL variable.\n" -" e(ext) - Enable 'enforced' mode, so the spying channel can\n" -" only monitor extensions whose name is in the 'ext' : \n" -" delimited list.\n" -; static const char *app_ext = "ExtenSpy"; -static const char *desc_ext = -" ExtenSpy(exten[@context][,options]): This application is used to listen to the\n" -"audio from an Asterisk channel. This includes the audio coming in and\n" -"out of the channel being spied on. Only channels created by outgoing calls for the\n" -"specified extension will be selected for spying. If the optional context is not\n" -"supplied, the current channel's context will be used.\n" -" While spying, the following actions may be performed:\n" -" - Dialing # cycles the volume level.\n" -" - Dialing * will stop spying and look for another channel to spy on.\n" -" Note: The X option superseeds the two features above in that if a valid\n" -" single digit extension exists in the correct context it ChanSpy will\n" -" exit to it.\n" -" Options:\n" -" b - Only spy on channels involved in a bridged call.\n" -" B - Instead of whispering on a single channel barge in on both\n" -" channels involved in the call.\n" -" d - Override the typical numeric DTMF functionality and instead\n" -" use DTMF to switch between spy modes.\n" -" 4 = spy mode\n" -" 5 = whisper mode\n" -" 6 = barge mode\n" -" g(grp) - Only spy on channels in which one or more of the groups \n" -" listed in 'grp' matches one or more groups from the\n" -" SPYGROUP variable set on the channel to be spied upon.\n" -" Note that both 'grp' and SPYGROUP can contain either a\n" -" single group or a colon-delimited list of groups, such\n" -" as 'sales:support:accounting'.\n" -" n([mailbox][@context]) - Say the name of the person being spied on if that person has recorded\n" -" his/her name. If a context is specified, then that voicemail context will\n" -" be searched when retrieving the name, otherwise the \"default\" context\n" -" will be searched. If no mailbox is specified, then the channel name will\n" -" be used when searching for the name (i.e. if SIP/1000 is the channel being\n" -" spied on and no mailbox is specified, then \"1000\" will be used when searching\n" -" for the name).\n" -" q - Don't play a beep when beginning to spy on a channel, or speak the\n" -" selected channel name.\n" -" r[(basename)] - Record the session to the monitor spool directory. An\n" -" optional base for the filename may be specified. The\n" -" default is 'chanspy'.\n" -" s - Skip the playback of the channel type (i.e. SIP, IAX, etc) when\n" -" speaking the selected channel name.\n" -" v([value]) - Adjust the initial volume in the range from -4 to 4. A\n" -" negative value refers to a quieter setting.\n" -" w - Enable 'whisper' mode, so the spying channel can talk to\n" -" the spied-on channel.\n" -" W - Enable 'private whisper' mode, so the spying channel can\n" -" talk to the spied-on channel but cannot listen to that\n" -" channel.\n" -" o - Only listen to audio coming from this channel.\n" -" X - Allow the user to exit ChanSpy to a valid single digit\n" -" numeric extension in the current context or the context\n" -" specified by the SPY_EXIT_CONTEXT channel variable. The\n" -" name of the last channel that was spied on will be stored\n" -" in the SPY_CHANNEL variable.\n" -; enum { OPTION_QUIET = (1 << 0), /* Quiet, no announcement */ @@ -1103,8 +1213,8 @@ static int load_module(void) { int res = 0; - res |= ast_register_application(app_chan, chanspy_exec, tdesc, desc_chan); - res |= ast_register_application(app_ext, extenspy_exec, tdesc, desc_ext); + res |= ast_register_application_xml(app_chan, chanspy_exec); + res |= ast_register_application_xml(app_ext, extenspy_exec); return res; } diff --git a/apps/app_controlplayback.c b/apps/app_controlplayback.c index f79ab6d42..4d7432d9c 100644 --- a/apps/app_controlplayback.c +++ b/apps/app_controlplayback.c @@ -33,32 +33,67 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/module.h" +/*** DOCUMENTATION + + + Play a file with fast forward and rewind. + + + + + This is number of milliseconds to skip when rewinding or + fast-forwarding. + + + Fast-forward when this DTMF digit is received. (defaults to #) + + + Rewind when this DTMF digit is received. (defaults to *) + + + Stop playback when this DTMF digit is received. + + + Pause playback when this DTMF digit is received. + + + Restart playback when this DTMF digit is received. + + + + + + + + + This application will play back the given filename. + It sets the following channel variables upon completion: + + + Contains the status of the attempt as a text string + + + + + + Contains the offset in ms into the file where playback + was at when it stopped. -1 is end of file. + + + If the playback is stopped by the user this variable contains + the key that was pressed. + + + + + ***/ static const char *app = "ControlPlayback"; -static const char *synopsis = "Play a file with fast forward and rewind"; - -static const char *descrip = -" ControlPlayback(file[,skipms[,ff[,rew[,stop[,pause[,restart,options]]]]]]]):\n" -"This application will play back the given filename. By default, the '*' key\n" -"can be used to rewind, and the '#' key can be used to fast-forward.\n" -"Parameters:\n" -" skipms - This is number of milliseconds to skip when rewinding or\n" -" fast-forwarding.\n" -" ff - Fast-forward when this DTMF digit is received.\n" -" rew - Rewind when this DTMF digit is received.\n" -" stop - Stop playback when this DTMF digit is received.\n" -" pause - Pause playback when this DTMF digit is received.\n" -" restart - Restart playback when this DTMF digit is received.\n" -"Options:\n" -" o(#) - Start at # ms from the beginning of the file.\n" -"This application sets the following channel variables upon completion:\n" -" CPLAYBACKSTATUS - This variable contains the status of the attempt as a text\n" -" string, one of: SUCCESS | USERSTOPPED | ERROR\n" -" CPLAYBACKOFFSET - This contains the offset in ms into the file where\n" -" playback was at when it stopped. -1 is end of file.\n" -" CPLAYBACKSTOPKEY - If the playback is stopped by the user this variable contains\n" -" the key that was pressed.\n"; - enum { OPT_OFFSET = (1 << 1), }; @@ -185,7 +220,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, controlplayback_exec, synopsis, descrip); + return ast_register_application_xml(app, controlplayback_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Control Playback Application"); diff --git a/apps/app_dahdibarge.c b/apps/app_dahdibarge.c index f16b4dea6..cfa445acc 100644 --- a/apps/app_dahdibarge.c +++ b/apps/app_dahdibarge.c @@ -52,17 +52,26 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/utils.h" +/*** DOCUMENTATION + + + Barge in (monitor) DAHDI channel. + + + + Channel to barge. + + + + Barges in on a specified DAHDI channel or prompts + if one is not specified. Returns -1 when caller user hangs + up and is independent of the state of the channel being monitored. + + + + ***/ static char *app = "DAHDIBarge"; -static char *synopsis = "Barge in (monitor) DAHDI channel"; - -static char *descrip = -" DAHDIBarge([channel]): Barges in on a specified DAHDI\n" -"channel or prompts if one is not specified. Returns\n" -"-1 when caller user hangs up and is independent of the\n" -"state of the channel being monitored."; - - #define CONF_SIZE 160 static int careful_write(int fd, unsigned char *data, int len) @@ -293,7 +302,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, conf_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, conf_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Barge in on DAHDI channel application"); diff --git a/apps/app_dahdiras.c b/apps/app_dahdiras.c index 1671f8bdd..879868ea5 100644 --- a/apps/app_dahdiras.c +++ b/apps/app_dahdiras.c @@ -52,17 +52,28 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/app.h" -static char *app = "DAHDIRAS"; - -static char *synopsis = "Executes DAHDI ISDN RAS application"; +/*** DOCUMENTATION + + + Executes DAHDI ISDN RAS application. + + + + A list of parameters to pass to the pppd daemon, + separeted by , characters. + + + + Executes a RAS server using pppd on the given channel. + The channel must be a clear channel (i.e. PRI source) and a DAHDI + channel to be able to use this function (No modem emulation is included). + Your pppd must be patched to be DAHDI aware. + + -static char *descrip = -" DAHDIRAS(args): Executes a RAS server using pppd on the given channel.\n" -"The channel must be a clear channel (i.e. PRI source) and a DAHDI\n" -"channel to be able to use this function (No modem emulation is included).\n" -"Your pppd must be patched to be DAHDI aware. Arguments should be\n" -"separated by , characters.\n"; + ***/ +static char *app = "DAHDIRAS"; #define PPP_MAX_ARGS 32 #define PPP_EXEC "/usr/sbin/pppd" @@ -218,7 +229,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, dahdiras_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, dahdiras_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "DAHDI ISDN Remote Access Server"); diff --git a/apps/app_dahdiscan.c b/apps/app_dahdiscan.c index a8a939725..8251ffcbf 100644 --- a/apps/app_dahdiscan.c +++ b/apps/app_dahdiscan.c @@ -52,16 +52,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/options.h" +/*** DOCUMENTATION + + + Scan DAHDI channels to monitor calls. + + + + Limit scanning to a channel group by setting this option. + + + + Allows a call center manager to monitor DAHDI channels in a + convenient way. Use # to select the next channel and use * to exit. + + + ***/ static char *app = "DAHDIScan"; -static char *synopsis = "Scan DAHDI channels to monitor calls"; - -static char *descrip = -" DAHDIScan([group]) allows a call center manager to monitor DAHDI channels in\n" -"a convenient way. Use '#' to select the next channel and use '*' to exit\n" -"Limit scanning to a channel GROUP by setting the option group argument.\n"; - - #define CONF_SIZE 160 static struct ast_channel *get_dahdi_channel_locked(int num) { @@ -363,7 +371,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, conf_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, conf_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Scan DAHDI channels application"); diff --git a/apps/app_dial.c b/apps/app_dial.c index f0fd7463d..089523ef4 100644 --- a/apps/app_dial.c +++ b/apps/app_dial.c @@ -62,188 +62,396 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/global_datastores.h" #include "asterisk/dsp.h" -static char *app = "Dial"; +/*** DOCUMENTATION + + + Attempt to connect to another device or endpoint and bridge the call. + + + + + Specification of the device(s) to dial. These must be in the format of + Technology/Resource, where Technology + represents a particular channel driver, and Resource + represents a resource available to that particular channel driver. + + + Optional extra devices to dial in parallel + If you need more then one enter them as + Technology2/Resource2&Technology3/Resourse3&..... + + + + Specifies the number of seconds we attempt to dial the specified devices + If not specified, this defaults to 136 years. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The optional URL will be sent to the called party if the channel driver supports it. + + + + This application will place calls to one or more specified channels. As soon + as one of the requested channels answers, the originating channel will be + answered, if it has not already been answered. These two channels will then + be active in a bridged call. All other channels that were requested will then + be hung up. + + Unless there is a timeout specified, the Dial application will wait + indefinitely until one of the called channels answers, the user hangs up, or + if all of the called channels are busy or unavailable. Dialplan executing will + continue if no requested channels can be called, or if the timeout expires. + This application will report normal termination if the originating channel + hangs up, or if the call is bridged and either of the parties in the bridge + ends the call. + + If the OUTBOUND_GROUP variable is set, all peer channels created by this + application will be put into that group (as in Set(GROUP()=...). + If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this + application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP, + however, the variable will be unset after use. + + This application sets the following channel variables: + + + This is the time from dialing a channel until when it is disconnected. + + + This is the amount of time for actual call. + + + This is the status of the call + + + + + + + + For the Privacy and Screening Modes. + Will be set if the called party chooses to send the calling party to the 'Go Away' script. + + + For the Privacy and Screening Modes. + Will be set if the called party chooses to send the calling party to the 'torture' script. + + + + + + + + + Place a call, retrying on failure allowing an optional exit extension. + + + + Filename of sound that will be played when no channel can be reached + + + Number of seconds to wait after a dialattempt failed before a new attempt is made + + + Number of retries + When this is reached flow will continue at the next priority in the dialplan + + + Same format as arguments provided to the Dial application + + + + This application will attempt to place a call using the normal Dial application. + If no channel can be reached, the announce file will be played. + Then, it will wait sleep number of seconds before retrying the call. + After retries number of attempts, the calling channel will continue at the next priority in the dialplan. + If the retries setting is set to 0, this application will retry endlessly. + While waiting to retry a call, a 1 digit extension may be dialed. If that + extension exists in either the context defined in EXITCONTEXT or the current + one, The call will jump to that extension immediately. + The dialargs are specified in the same format that arguments are provided + to the Dial application. + + + ***/ -static char *synopsis = "Place a call and connect to the current channel"; - -static char *descrip = -" Dial(Technology/resource[&Tech2/resource2...][,timeout][,options][,URL]):\n" -"This application will place calls to one or more specified channels. As soon\n" -"as one of the requested channels answers, the originating channel will be\n" -"answered, if it has not already been answered. These two channels will then\n" -"be active in a bridged call. All other channels that were requested will then\n" -"be hung up.\n" -" Unless there is a timeout specified, the Dial application will wait\n" -"indefinitely until one of the called channels answers, the user hangs up, or\n" -"if all of the called channels are busy or unavailable. Dialplan executing will\n" -"continue if no requested channels can be called, or if the timeout expires.\n\n" -" This application sets the following channel variables upon completion:\n" -" DIALEDTIME - This is the time from dialing a channel until when it\n" -" is disconnected.\n" -" ANSWEREDTIME - This is the amount of time for actual call.\n" -" DIALSTATUS - This is the status of the call:\n" -" CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL\n" -" DONTCALL | TORTURE | INVALIDARGS\n" -" For the Privacy and Screening Modes, the DIALSTATUS variable will be set to\n" -"DONTCALL if the called party chooses to send the calling party to the 'Go Away'\n" -"script. The DIALSTATUS variable will be set to TORTURE if the called party\n" -"wants to send the caller to the 'torture' script.\n" -" This application will report normal termination if the originating channel\n" -"hangs up, or if the call is bridged and either of the parties in the bridge\n" -"ends the call.\n" -" The optional URL will be sent to the called party if the channel supports it.\n" -" If the OUTBOUND_GROUP variable is set, all peer channels created by this\n" -"application will be put into that group (as in Set(GROUP()=...).\n" -" If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this\n" -"application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP,\n" -"however, the variable will be unset after use.\n\n" -" Options:\n" -" A(x) - Play an announcement to the called party, using 'x' as the file.\n" -" C - Reset the CDR for this call.\n" -" c - If DIAL cancels this call, always set the flag to tell the channel\n" -" driver that the call is answered elsewhere.\n" -" d - Allow the calling user to dial a 1 digit extension while waiting for\n" -" a call to be answered. Exit to that extension if it exists in the\n" -" current context, or the context defined in the EXITCONTEXT variable,\n" -" if it exists.\n" -" D([called][:calling]) - Send the specified DTMF strings *after* the called\n" -" party has answered, but before the call gets bridged. The 'called'\n" -" DTMF string is sent to the called party, and the 'calling' DTMF\n" -" string is sent to the calling party. Both parameters can be used\n" -" alone.\n" -" e - execute the 'h' extension for peer after the call ends. This\n" -" operation will not be performed if the peer was parked\n" -" f - Force the callerid of the *calling* channel to be set as the\n" -" extension associated with the channel using a dialplan 'hint'.\n" -" For example, some PSTNs do not allow CallerID to be set to anything\n" -" other than the number assigned to the caller.\n" -" F(context^exten^pri) - When the caller hangs up, transfer the called party\n" -" to the specified context and extension and continue execution.\n" -" g - Proceed with dialplan execution at the current extension if the\n" -" destination channel hangs up.\n" -" G(context^exten^pri) - If the call is answered, transfer the calling party to\n" -" the specified priority and the called party to the specified priority+1.\n" -" Optionally, an extension, or extension and context may be specified. \n" -" Otherwise, the current extension is used. You cannot use any additional\n" -" action post answer options in conjunction with this option.\n" -" h - Allow the called party to hang up by sending the '*' DTMF digit, or\n" -" whatever sequence was defined in the featuremap section for\n" -" 'disconnect' in features.conf\n" -" H - Allow the calling party to hang up by hitting the '*' DTMF digit, or\n" -" whatever sequence was defined in the featuremap section for\n" -" 'disconnect' in features.conf\n" -" i - Asterisk will ignore any forwarding requests it may receive on this\n" -" dial attempt.\n" -" k - Allow the called party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in the featuremap section of features.conf.\n" -" K - Allow the calling party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in the featuremap section of features.conf.\n" -" L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are\n" -" left. Repeat the warning every 'z' ms. The following special\n" -" variables can be used with this option:\n" -" * LIMIT_PLAYAUDIO_CALLER yes|no (default yes)\n" -" Play sounds to the caller.\n" -" * LIMIT_PLAYAUDIO_CALLEE yes|no\n" -" Play sounds to the callee.\n" -" * LIMIT_TIMEOUT_FILE File to play when time is up.\n" -" * LIMIT_CONNECT_FILE File to play when call begins.\n" -" * LIMIT_WARNING_FILE File to play as warning if 'y' is defined.\n" -" The default is to say the time remaining.\n" -" m([class]) - Provide hold music to the calling party until a requested\n" -" channel answers. A specific MusicOnHold class can be\n" -" specified.\n" -" M(x[^arg]) - Execute the Macro for the *called* channel before connecting\n" -" to the calling channel. Arguments can be specified to the Macro\n" -" using '^' as a delimiter. The Macro can set the variable\n" -" MACRO_RESULT to specify the following actions after the Macro is\n" -" finished executing.\n" -" * ABORT Hangup both legs of the call.\n" -" * CONGESTION Behave as if line congestion was encountered.\n" -" * BUSY Behave as if a busy signal was encountered.\n" -" * CONTINUE Hangup the called party and allow the calling party\n" -" to continue dialplan execution at the next priority.\n" -" * GOTO:^^ - Transfer the call to the\n" -" specified priority. Optionally, an extension, or\n" -" extension and priority can be specified.\n" -" You cannot use any additional action post answer options in conjunction\n" -" with this option. Also, pbx services are not run on the peer (called) channel,\n" -" so you will not be able to set timeouts via the TIMEOUT() function in this macro.\n" -" n - This option is a modifier for the screen/privacy mode. It specifies\n" -" that no introductions are to be saved in the priv-callerintros\n" -" directory.\n" -" N - This option is a modifier for the screen/privacy mode. It specifies\n" -" that if callerID is present, do not screen the call.\n" -" o - Specify that the CallerID that was present on the *calling* channel\n" -" be set as the CallerID on the *called* channel. This was the\n" -" behavior of Asterisk 1.0 and earlier.\n" -" O([x]) - \"Operator Services\" mode (DAHDI channel to DAHDI channel\n" -" only, if specified on non-DAHDI interface, it will be ignored).\n" -" When the destination answers (presumably an operator services\n" -" station), the originator no longer has control of their line.\n" -" They may hang up, but the switch will not release their line\n" -" until the destination party hangs up (the operator). Specified\n" -" without an arg, or with 1 as an arg, the originator hanging up\n" -" will cause the phone to ring back immediately. With a 2 specified,\n" -" when the \"operator\" flashes the trunk, it will ring their phone\n" -" back.\n" -" p - This option enables screening mode. This is basically Privacy mode\n" -" without memory.\n" -" P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if\n" -" it is provided. The current extension is used if a database\n" -" family/key is not specified.\n" -" r - Indicate ringing to the calling party. Pass no audio to the calling\n" -" party until the called channel has answered.\n" -" S(x) - Hang up the call after 'x' seconds *after* the called party has\n" -" answered the call.\n" -" t - Allow the called party to transfer the calling party by sending the\n" -" DTMF sequence defined in the blindxfer setting in the featuremap section\n" -" of features.conf.\n" -" T - Allow the calling party to transfer the called party by sending the\n" -" DTMF sequence defined in the blindxfer setting in the featuremap section\n" -" of features.conf.\n" -" U(x[^arg]) - Execute via Gosub the routine 'x' for the *called* channel before connecting\n" -" to the calling channel. Arguments can be specified to the Gosub\n" -" using '^' as a delimiter. The Gosub routine can set the variable\n" -" GOSUB_RESULT to specify the following actions after the Gosub returns.\n" -" * ABORT Hangup both legs of the call.\n" -" * CONGESTION Behave as if line congestion was encountered.\n" -" * BUSY Behave as if a busy signal was encountered.\n" -" * CONTINUE Hangup the called party and allow the calling party\n" -" to continue dialplan execution at the next priority.\n" -" * GOTO:^^ - Transfer the call to the\n" -" specified priority. Optionally, an extension, or\n" -" extension and priority can be specified.\n" -" You cannot use any additional action post answer options in conjunction\n" -" with this option. Also, pbx services are not run on the peer (called) channel,\n" -" so you will not be able to set timeouts via the TIMEOUT() function in this routine.\n" -" w - Allow the called party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automon setting in the featuremap section\n" -" of features.conf.\n" -" W - Allow the calling party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automon setting in the featuremap section\n" -" of features.conf.\n" -" x - Allow the called party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automixmon setting in the featuremap section\n" -" of features.conf.\n" -" X - Allow the calling party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automixmon setting in the featuremap section\n" -" of features.conf.\n"; - -/* RetryDial App by Anthony Minessale II Jan/2005 */ +static char *app = "Dial"; static char *rapp = "RetryDial"; -static char *rsynopsis = "Place a call, retrying on failure allowing optional exit extension."; -static char *rdescrip = -" RetryDial(announce,sleep,retries,dialargs): This application will attempt to\n" -"place a call using the normal Dial application. If no channel can be reached,\n" -"the 'announce' file will be played. Then, it will wait 'sleep' number of\n" -"seconds before retrying the call. After 'retries' number of attempts, the\n" -"calling channel will continue at the next priority in the dialplan. If the\n" -"'retries' setting is set to 0, this application will retry endlessly.\n" -" While waiting to retry a call, a 1 digit extension may be dialed. If that\n" -"extension exists in either the context defined in ${EXITCONTEXT} or the current\n" -"one, The call will jump to that extension immediately.\n" -" The 'dialargs' are specified in the same format that arguments are provided\n" -"to the Dial application.\n"; enum { OPT_ANNOUNCE = (1 << 0), @@ -2187,8 +2395,8 @@ static int load_module(void) else ast_add_extension2(con, 1, "s", 1, NULL, NULL, "KeepAlive", ast_strdup(""), ast_free_ptr, "app_dial"); - res = ast_register_application(app, dial_exec, synopsis, descrip); - res |= ast_register_application(rapp, retrydial_exec, rsynopsis, rdescrip); + res = ast_register_application_xml(app, dial_exec); + res |= ast_register_application_xml(rapp, retrydial_exec); return res; } diff --git a/apps/app_dictate.c b/apps/app_dictate.c index 86ccad875..b780182e3 100644 --- a/apps/app_dictate.c +++ b/apps/app_dictate.c @@ -40,11 +40,22 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/app.h" -static char *app = "Dictate"; -static char *synopsis = "Virtual Dictation Machine"; -static char *desc = " Dictate([[,]])\n" -"Start dictation machine using optional base dir for files.\n"; +/*** DOCUMENTATION + + + Virtual Dictation Machine. + + + + + + + Start dictation machine using optional base_dir for files. + + + ***/ +static char *app = "Dictate"; typedef enum { DFLAG_RECORD = (1 << 0), @@ -332,7 +343,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, dictate_exec, synopsis, desc); + return ast_register_application_xml(app, dictate_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Virtual Dictation Machine"); diff --git a/apps/app_directed_pickup.c b/apps/app_directed_pickup.c index 1ead1d772..5f88df85d 100644 --- a/apps/app_directed_pickup.c +++ b/apps/app_directed_pickup.c @@ -43,23 +43,48 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define PICKUPMARK "PICKUPMARK" -static const char *app = "Pickup"; -static const char *synopsis = "Directed Call Pickup"; -static const char *descrip = -" Pickup([extension[@context][&extension2@[context]...]]): This application can\n" -"pickup any ringing channel that is calling the specified extension. If no\n" -"context is specified, the current context will be used. If you use the special\n" -"string \"PICKUPMARK\" for the context parameter, for example 10@PICKUPMARK,\n" -"this application tries to find a channel which has defined a ${PICKUPMARK}\n" -"channel variable with the same value as \"extension\" (in this example, \"10\").\n" -"When no parameter is specified, the application will pickup a channel matching\n" -"the pickup group of the active channel."; +/*** DOCUMENTATION + + + Directed extension call pickup. + + + + + + + + + + + + + This application can pickup any ringing channel that is calling + the specified extension. If no context + is specified, the current context will be used. If you use the special string PICKUPMARK + for the context parameter, for example 10@PICKUPMARK, this application + tries to find a channel which has defined a PICKUPMARK + channel variable with the same value as extension + (in this example, 10). When no parameter is specified, the application + will pickup a channel matching the pickup group of the active channel. + + + + + Pickup a ringing channel. + + + + + + + This will pickup a specified channel if ringing. + + + ***/ +static const char *app = "Pickup"; static const char *app2 = "PickupChan"; -static const char *synopsis2 = "Pickup a ringing channel"; -static const char *descrip2 = -" PickupChan(channel[&channel...]): This application can pickup any ringing channel\n"; - /*! \todo This application should return a result code, like PICKUPRESULT */ /* Perform actual pickup between two channels */ @@ -248,8 +273,8 @@ static int load_module(void) { int res; - res = ast_register_application(app, pickup_exec, synopsis, descrip); - res |= ast_register_application(app2, pickupchan_exec, synopsis2, descrip2); + res = ast_register_application_xml(app, pickup_exec); + res |= ast_register_application_xml(app2, pickupchan_exec); return res; } diff --git a/apps/app_directory.c b/apps/app_directory.c index b2a5741ed..2b0b6776c 100644 --- a/apps/app_directory.c +++ b/apps/app_directory.c @@ -42,50 +42,78 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/utils.h" -static char *app = "Directory"; +/*** DOCUMENTATION + + + Provide directory of voicemail extensions. + + + + This is the context within voicemail.conf to use for the Directory. If not specified and + searchcontexts=no in voicemail.conf, then default + will be assumed. + + + This is the dialplan context to use when looking for an + extension that the user has selected, or when jumping to the + o or a extension. + + + + + + + + + + + Only one of the f, l, or b + options may be specified. If more than one is specified, then Directory will act as + if b was specified. The number + of characters for the user to type defaults to 3. + + + + This application will present the calling channel with a directory of extensions from which they can search + by name. The list of names and corresponding extensions is retrieved from the + voicemail configuration file, voicemail.conf. + This application will immediately exit if one of the following DTMF digits are + received and the extension to jump to exists: + 0 - Jump to the 'o' extension, if it exists. + * - Jump to the 'a' extension, if it exists. + + -static char *synopsis = "Provide directory of voicemail extensions"; -static char *descrip = -" Directory([vm-context][,dial-context[,options]]): This application will present\n" -"the calling channel with a directory of extensions from which they can search\n" -"by name. The list of names and corresponding extensions is retrieved from the\n" -"voicemail configuration file, voicemail.conf.\n" -" This application will immediately exit if one of the following DTMF digits are\n" -"received and the extension to jump to exists:\n" -" 0 - Jump to the 'o' extension, if it exists.\n" -" * - Jump to the 'a' extension, if it exists.\n\n" -" Parameters:\n" -" vm-context - This is the context within voicemail.conf to use for the\n" -" Directory. If not specified and searchcontexts=no in\n" -" voicemail.conf, then \"default\" will be assumed.\n" -" Otherwise, in not specified, all contexts will be searched.\n" -" dial-context - This is the dialplan context to use when looking for an\n" -" extension that the user has selected, or when jumping to the\n" -" 'o' or 'a' extension.\n\n" -" Options:\n" -" e In addition to the name, also read the extension number to the\n" -" caller before presenting dialing options.\n" -" f[()] Allow the caller to enter the first name of a user in the\n" -" directory instead of using the last name. If specified, the\n" -" optional number argument will be used for the number of\n" -" characters the user should enter.\n" -" l[()] Allow the caller to enter the last name of a user in the\n" -" directory. This is the default. If specified, the\n" -" optional number argument will be used for the number of\n" -" characters the user should enter.\n" -" b[()] Allow the caller to enter either the first or the last name\n" -" of a user in the directory. If specified, the optional number\n" -" argument will be used for the number of characters the user\n" -" should enter.\n" -" m Instead of reading each name sequentially and asking for\n" -" confirmation, create a menu of up to 8 names.\n" -" p() Pause for n milliseconds after the digits are typed. This is\n" -" helpful for people with cellphones, who are not holding the\n" -" receiver to their ear while entering DTMF.\n" -"\n" -" Only one of the f, l, or b options may be specified. If more than one is\n" -" specified, then Directory will act as if 'b' was specified. The number\n" -" of characters for the user to type defaults to 3.\n"; + ***/ +static char *app = "Directory"; /* For simplicity, I'm keeping the format compatible with the voicemail config, but i'm open to suggestions for isolating it */ @@ -809,7 +837,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, directory_exec, synopsis, descrip); + return ast_register_application_xml(app, directory_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Extension Directory"); diff --git a/apps/app_disa.c b/apps/app_disa.c index 2ed5e15f7..515bdce9c 100644 --- a/apps/app_disa.c +++ b/apps/app_disa.c @@ -45,51 +45,69 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/callerid.h" #include "asterisk/stringfields.h" +/*** DOCUMENTATION + + + Direct Inward System Access. + + + + If you need to present a DISA dialtone without entering a password, + simply set passcode to no-password + You may specified a filename instead of a + passcode, this filename must contain individual passcodes + + + Specifies the dialplan context in which the user-entered extension + will be matched. If no context is specified, the DISA application defaults + to the disa context. Presumably a normal system will have a special + context set up for DISA use with some or a lot of restrictions. + + + Specifies a new (different) callerid to be used for this call. + + + Will cause a stutter-dialtone (indication dialrecall) + to be used, if the specified mailbox contains any new messages. + + + + + + + + + + + + The DISA, Direct Inward System Access, application allows someone from + outside the telephone switch (PBX) to obtain an internal system + dialtone and to place calls from it as if they were placing a call from + within the switch. + DISA plays a dialtone. The user enters their numeric passcode, followed by + the pound sign #. If the passcode is correct, the user is then given + system dialtone within context on which a call may be placed. + If the user enters an invalid extension and extension i exists in the specified + context, it will be used. + + Be aware that using this may compromise the security of your PBX. + The arguments to this application (in extensions.conf) allow either + specification of a single global passcode (that everyone uses), or + individual passcodes contained in a file (filename). + The file that contains the passcodes (if used) allows a complete + specification of all of the same arguments available on the command + line, with the sole exception of the options. The file may contain blank + lines, or comments starting with # or ;. + + + ***/ static char *app = "DISA"; -static char *synopsis = "DISA (Direct Inward System Access)"; - -static char *descrip = -"DISA([,[,[,mailbox[,options]]]]) or\n" -"DISA([,,,,options])\n" -"The DISA, Direct Inward System Access, application allows someone from \n" -"outside the telephone switch (PBX) to obtain an \"internal\" system \n" -"dialtone and to place calls from it as if they were placing a call from \n" -"within the switch.\n" -"DISA plays a dialtone. The user enters their numeric passcode, followed by\n" -"the pound sign (#). If the passcode is correct, the user is then given\n" -"system dialtone within on which a call may be placed. If the user\n" -"enters an invalid extension and extension \"i\" exists in the specified\n" -"context, it will be used.\n" -"\n" -"If you need to present a DISA dialtone without entering a password, simply\n" -"set to \"no-password\".\n" -"\n" -"Be aware that using this may compromise the security of your PBX.\n" -"\n" -"The arguments to this application (in extensions.conf) allow either\n" -"specification of a single global passcode (that everyone uses), or\n" -"individual passcodes contained in a file.\n" -"\n" -"The file that contains the passcodes (if used) allows a complete\n" -"specification of all of the same arguments available on the command\n" -"line, with the sole exception of the options. The file may contain blank\n" -"lines, or comments starting with \"#\" or \";\".\n" -"\n" -" specifies the dialplan context in which the user-entered extension\n" -"will be matched. If no context is specified, the DISA application defaults\n" -"the context to \"disa\". Presumably a normal system will have a special\n" -"context set up for DISA use with some or a lot of restrictions.\n" -"\n" -" specifies a new (different) callerid to be used for this call.\n" -"\n" -" will cause a stutter-dialtone (indication \"dialrecall\")\n" -"to be used, if the specified mailbox contains any new messages.\n" -"\n" -"The following options are available:\n" -" n - the DISA application will not answer initially.\n" -" p - the extension entered will be considered complete when a '#' is entered.\n"; - enum { NOANSWER_FLAG = (1 << 0), POUND_TO_END_FLAG = (1 << 1), @@ -363,7 +381,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, disa_exec, synopsis, descrip) ? + return ast_register_application_xml(app, disa_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_dumpchan.c b/apps/app_dumpchan.c index 7742633fd..e2300dbea 100644 --- a/apps/app_dumpchan.c +++ b/apps/app_dumpchan.c @@ -36,15 +36,26 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/channel.h" -static char *app = "DumpChan"; -static char *synopsis = "Dump Info About The Calling Channel"; -static char *desc = - " DumpChan([])\n" - "Displays information on channel and listing of all channel\n" - "variables. If min_verbose_level is specified, output is only\n" - "displayed when the verbose level is currently set to that number\n" - "or greater. \n"; +/*** DOCUMENTATION + + + Dump Info About The Calling Channel. + + + + Minimun verbose level + + + + Displays information on channel and listing of all channel + variables. If level is specified, output is only + displayed when the verbose level is currently set to that number + or greater. + + + ***/ +static char *app = "DumpChan"; static int serialize_showchan(struct ast_channel *c, char *buf, size_t size) { @@ -156,7 +167,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, dumpchan_exec, synopsis, desc); + return ast_register_application_xml(app, dumpchan_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Dump Info About The Calling Channel"); diff --git a/apps/app_echo.c b/apps/app_echo.c index 76c701cd7..8b0d21f06 100644 --- a/apps/app_echo.c +++ b/apps/app_echo.c @@ -33,15 +33,20 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/channel.h" -static char *app = "Echo"; - -static char *synopsis = "Echo audio, video, or DTMF back to the calling party"; - -static char *descrip = -" Echo(): This application will echo any audio, video, or DTMF frames read from\n" -"the calling channel back to itself. If the DTMF digit '#' is received, the\n" -"application will exit.\n"; +/*** DOCUMENTATION + + + Echo audio, video, DTMF back to the calling party + + + + Echos back any audio, video or DTMF frames read from the calling + channel back to itself. Note: If '#' detected application exits + + + ***/ +static char *app = "Echo"; static int echo_exec(struct ast_channel *chan, void *data) { @@ -81,7 +86,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, echo_exec, synopsis, descrip); + return ast_register_application_xml(app, echo_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Simple Echo Application"); diff --git a/apps/app_exec.c b/apps/app_exec.c index 285b8b2f0..b4a66962e 100644 --- a/apps/app_exec.c +++ b/apps/app_exec.c @@ -36,6 +36,80 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/app.h" +/*** DOCUMENTATION + + + Executes dialplan application. + + + + Application name and arguments of the dialplan application to execute. + + + + + Allows an arbitrary application to be invoked even when not + hardcoded into the dialplan. If the underlying application + terminates the dialplan, or if the application cannot be found, + Exec will terminate the dialplan. + To invoke external applications, see the application System. + If you would like to catch any error instead, see TryExec. + + + + + Executes dialplan application, always returning. + + + + + + + + Allows an arbitrary application to be invoked even when not + hardcoded into the dialplan. To invoke external applications + see the application System. Always returns to the dialplan. + The channel variable TRYSTATUS will be set to one of: + + + + + If the application returned zero. + + + If the application returned non-zero. + + + If the application was not found or was not specified. + + + + + + + + Executes dialplan application, conditionally. + + + + + + + + + + + + + + If expr is true, execute and return the + result of appiftrue(args). + If expr is true, but appiftrue is not found, + then the application will return a non-zero value. + + + ***/ + /* Maximum length of any variable */ #define MAXRESULT 1024 @@ -52,35 +126,8 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") */ static char *app_exec = "Exec"; -static char *exec_synopsis = "Executes dialplan application"; -static char *exec_descrip = -" Exec(appname(arguments)):\n" -"Allows an arbitrary application to be invoked even when not\n" -"hardcoded into the dialplan. If the underlying application\n" -"terminates the dialplan, or if the application cannot be found,\n" -"Exec will terminate the dialplan.\n" -" To invoke external applications, see the application System.\n" -" If you would like to catch any error instead, see TryExec.\n"; - static char *app_tryexec = "TryExec"; -static char *tryexec_synopsis = "Executes dialplan application, always returning"; -static char *tryexec_descrip = -" TryExec(appname(arguments)):\n" -"Allows an arbitrary application to be invoked even when not\n" -"hardcoded into the dialplan. To invoke external applications\n" -"see the application System. Always returns to the dialplan.\n" -"The channel variable TRYSTATUS will be set to one of:\n" -" SUCCESS if the application returned zero\n" -" FAILED if the application returned non-zero\n" -" NOAPP if the application was not found or was not specified\n"; - static char *app_execif = "ExecIf"; -static char *execif_synopsis = "Executes dialplan application, conditionally"; -static char *execif_descrip = -" ExecIF (?()[:()])\n" -"If is true, execute and return the result of ().\n" -"If is true, but is not found, then the application\n" -"will return a non-zero value.\n"; static int exec_exec(struct ast_channel *chan, void *data) { @@ -237,9 +284,9 @@ static int unload_module(void) static int load_module(void) { - int res = ast_register_application(app_exec, exec_exec, exec_synopsis, exec_descrip); - res |= ast_register_application(app_tryexec, tryexec_exec, tryexec_synopsis, tryexec_descrip); - res |= ast_register_application(app_execif, execif_exec, execif_synopsis, execif_descrip); + int res = ast_register_application_xml(app_exec, exec_exec); + res |= ast_register_application_xml(app_tryexec, tryexec_exec); + res |= ast_register_application_xml(app_execif, execif_exec); return res; } diff --git a/apps/app_fax.c b/apps/app_fax.c index 9d72f3fe1..41d76b4bf 100644 --- a/apps/app_fax.c +++ b/apps/app_fax.c @@ -41,60 +41,105 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/manager.h" -static char *app_sndfax_name = "SendFAX"; -static char *app_sndfax_synopsis = "Send a FAX"; -static char *app_sndfax_desc = -" SendFAX(filename[|options]):\n" -"Send a given TIFF file to the channel as a FAX.\n" -"The option string may contain zero or more of the following characters:\n" -" 'a' - makes the application behave as an answering machine\n" -" The default behaviour is to behave as a calling machine.\n" -"\n" -"This application uses following variables:\n" -" LOCALSTATIONID to identify itself to the remote end.\n" -" LOCALHEADERINFO to generate a header line on each page.\n" -"\n" -"This application sets the following channel variables upon completion:\n" -" FAXSTATUS - status of operation:\n" -" SUCCESS | FAILED\n" -" FAXERROR - Error when FAILED\n" -" FAXMODE - Mode used:\n" -" audio | T38\n" -" REMOTESTATIONID - CSID of the remote side.\n" -" FAXPAGES - number of pages sent.\n" -" FAXBITRATE - transmition rate.\n" -" FAXRESOLUTION - resolution.\n" -"\n" -"Returns -1 in case of user hang up or any channel error.\n" -"Returns 0 on success.\n"; +/*** DOCUMENTATION + + + Send a Fax + + + + Filename of TIFF file to fax + + + Makes the application behave as the answering machine + (Default behavior is as calling machine) + + + + Send a given TIFF file to the channel as a FAX. + This application sets the following channel variables: + + + To identify itself to the remote end + + + To generate a header line on each page + + + + + + + Cause of failure + + + The CSID of the remote side + + + Number of pages sent + + + Transmission rate + + + Resolution of sent fax + + + + + + + Receive a Fax + + + + Filename of TIFF file save incoming fax + + + Makes the application behave as the calling machine + (Default behavior is as answering machine) + + + + Receives a FAX from the channel into the given filename + overwriting the file if it already exists. + File created will be in TIFF format. + + This application sets the following channel variables: + + + To identify itself to the remote end + + + To generate a header line on each page + + + + + + + Cause of failure + + + The CSID of the remote side + + + Number of pages sent + + + Transmission rate + + + Resolution of sent fax + + + + + + ***/ +static char *app_sndfax_name = "SendFAX"; static char *app_rcvfax_name = "ReceiveFAX"; -static char *app_rcvfax_synopsis = "Receive a FAX"; -static char *app_rcvfax_desc = -" ReceiveFAX(filename[|options]):\n" -"Receives a fax from the channel into the given filename overwriting\n" -"the file if it already exists. File created will have TIFF format.\n" -"The option string may contain zero or more of the following characters:\n" -" 'c' -- makes the application behave as a calling machine\n" -" The default behaviour is to behave as an answering machine.\n" -"\n" -"This application uses following variables:\n" -" LOCALSTATIONID to identify itself to the remote end.\n" -" LOCALHEADERINFO to generate a header line on each page.\n" -"\n" -"This application sets the following channel variables upon completion:\n" -" FAXSTATUS - status of operation:\n" -" SUCCESS | FAILED\n" -" FAXERROR - Error when FAILED\n" -" FAXMODE - Mode used:\n" -" audio | T38\n" -" REMOTESTATIONID - CSID of the remote side.\n" -" FAXPAGES - number of pages sent.\n" -" FAXBITRATE - transmition rate.\n" -" FAXRESOLUTION - resolution.\n" -"\n" -"Returns -1 in case of user hang up or any channel error.\n" -"Returns 0 on success.\n"; #define MAX_SAMPLES 240 @@ -753,8 +798,8 @@ static int load_module(void) { int res ; - res = ast_register_application(app_sndfax_name, sndfax_exec, app_sndfax_synopsis, app_sndfax_desc); - res |= ast_register_application(app_rcvfax_name, rcvfax_exec, app_rcvfax_synopsis, app_rcvfax_desc); + res = ast_register_application_xml(app_sndfax_name, sndfax_exec); + res |= ast_register_application_xml(app_rcvfax_name, rcvfax_exec); /* The default SPAN message handler prints to stderr. It is something we do not want */ span_set_message_handler(NULL); diff --git a/apps/app_festival.c b/apps/app_festival.c index 4a929a3e5..82f1bddc5 100644 --- a/apps/app_festival.c +++ b/apps/app_festival.c @@ -53,15 +53,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define MAXLEN 180 #define MAXFESTLEN 2048 -static char *app = "Festival"; - -static char *synopsis = "Say text to the user"; - -static char *descrip = -" Festival(text[,intkeys]): Connect to Festival, send the argument, get back the waveform,\n" -"play it to the user, allowing any given interrupt keys to immediately terminate and return\n" -"the value, or 'any' to allow any number back (useful in dialplan)\n"; +/*** DOCUMENTATION + + + Say text to the user. + + + + + + + Connect to Festival, send the argument, get back the waveform, play it to the user, + allowing any given interrupt keys to immediately terminate and return the value, or + any to allow any number back (useful in dialplan). + + + ***/ +static char *app = "Festival"; static char *socket_receive_file_to_buff(int fd, int *size) { @@ -526,7 +535,7 @@ static int load_module(void) return AST_MODULE_LOAD_DECLINE; } ast_config_destroy(cfg); - return ast_register_application(app, festival_exec, synopsis, descrip); + return ast_register_application_xml(app, festival_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Simple Festival Interface"); diff --git a/apps/app_getcpeid.c b/apps/app_getcpeid.c index 6ff051899..9c1009242 100644 --- a/apps/app_getcpeid.c +++ b/apps/app_getcpeid.c @@ -36,15 +36,20 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/adsi.h" +/*** DOCUMENTATION + + + Get ADSI CPE ID. + + + + Obtains and displays ADSI CPE ID and other information in order + to properly setup dahdi.conf for on-hook operations. + + + ***/ static char *app = "GetCPEID"; -static char *synopsis = "Get ADSI CPE ID"; - -static char *descrip = -" GetCPEID(): Obtains and displays ADSI CPE ID and other information in order\n" -"to properly setup dahdi.conf for on-hook operations.\n"; - - static int cpeid_setstatus(struct ast_channel *chan, char *stuff[], int voice) { int justify[5] = { ADSI_JUST_CENT, ADSI_JUST_LEFT, ADSI_JUST_LEFT, ADSI_JUST_LEFT }; @@ -124,7 +129,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, cpeid_exec, synopsis, descrip); + return ast_register_application_xml(app, cpeid_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Get ADSI CPE ID"); diff --git a/apps/app_ices.c b/apps/app_ices.c index 1da17369b..4126ad7e9 100644 --- a/apps/app_ices.c +++ b/apps/app_ices.c @@ -45,21 +45,30 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/translate.h" #include "asterisk/app.h" +/*** DOCUMENTATION + + + Encode and stream using 'ices'. + + + + ICES configuration file. + + + + Streams to an icecast server using ices (available separately). + A configuration file must be supplied for ices (see contrib/asterisk-ices.xml). + ICES version 2 cient and server required. + + + + ***/ + #define path_BIN "/usr/bin/" #define path_LOCAL "/usr/local/bin/" static char *app = "ICES"; -static char *synopsis = "Encode and stream using 'ices'"; - -static char *descrip = -" ICES(config.xml) Streams to an icecast server using ices\n" -"(available separately). A configuration file must be supplied\n" -"for ices (see contrib/asterisk-ices.xml). \n" -"\n" -"- ICES version 2 cient and server required.\n"; - - static int icesencode(char *filename, int fd) { int res; @@ -199,7 +208,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, ices_exec, synopsis, descrip); + return ast_register_application_xml(app, ices_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Encode and Stream via icecast and ices"); diff --git a/apps/app_image.c b/apps/app_image.c index ac44495e3..e74397c0d 100644 --- a/apps/app_image.c +++ b/apps/app_image.c @@ -35,16 +35,35 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "SendImage"; -static char *synopsis = "Send an image file"; - -static char *descrip = -" SendImage(filename): Sends an image on a channel.\n" -"Result of transmission will be stored in SENDIMAGESTATUS\n" -"channel variable:\n" -" SUCCESS Transmission succeeded\n" -" FAILURE Transmission failed\n" -" UNSUPPORTED Image transmission not supported by channel\n"; - +/*** DOCUMENTATION + + + Sends an image file. + + + + Path of the filename (image) to send. + + + + Send an image file on a channel supporting it. + Result of transmission will be stored in SENDIMAGESTATUS + + + + Transmission succeeded. + + + Transmission failed. + + + Image transmission not supported by channel. + + + + + + ***/ static int sendimage_exec(struct ast_channel *chan, void *data) { @@ -76,7 +95,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, sendimage_exec, synopsis, descrip); + return ast_register_application_xml(app, sendimage_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Image Transmission Application"); diff --git a/apps/app_jack.c b/apps/app_jack.c index 4da4c9f8b..14546b3c4 100644 --- a/apps/app_jack.c +++ b/apps/app_jack.c @@ -73,18 +73,46 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") " running.\n" \ " c() - By default, Asterisk will use the channel name for the jack client\n" \ " name. Use this option to specify a custom client name.\n" - +/*** DOCUMENTATION + + + Jack Audio Connection Kit + + + + + + + + + + + + + When executing this application, two jack ports will be created; + one input and one output. Other applications can be hooked up to + these ports to access audio coming from, or being send to the channel. + + + ***/ static char *jack_app = "JACK"; -static char *jack_synopsis = -"JACK (Jack Audio Connection Kit) Application"; -static char *jack_desc = -"JACK([options])\n" -" When this application is executed, two jack ports will be created; one input\n" -"and one output. Other applications can be hooked up to these ports to access\n" -"the audio coming from, or being sent to the channel.\n" -" Valid options:\n" -COMMON_OPTIONS -""; struct jack_data { AST_DECLARE_STRING_FIELDS( @@ -982,7 +1010,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(jack_app, jack_exec, jack_synopsis, jack_desc)) { + if (ast_register_application_xml(jack_app, jack_exec)) { return AST_MODULE_LOAD_DECLINE; } diff --git a/apps/app_milliwatt.c b/apps/app_milliwatt.c index 89063096c..4c6a9ea4c 100644 --- a/apps/app_milliwatt.c +++ b/apps/app_milliwatt.c @@ -37,16 +37,29 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" #include "asterisk/pbx.h" -static char *app = "Milliwatt"; - -static char *synopsis = "Generate a Constant 1004Hz tone at 0dbm (mu-law)"; +/*** DOCUMENTATION + + + Generate a Constant 1004Hz tone at 0dbm (mu-law). + + + + + + + + + + Previous versions of this application generated the tone at 1000Hz. If for + some reason you would prefer that behavior, supply the o option to get the + old behavior. + + + ***/ -static char *descrip = -" Milliwatt([options]): Generate a Constant 1004Hz tone at 0dbm.\n" -"Previous versions of this application generated the tone at 1000Hz. If for\n" -"some reason you would prefer that behavior, supply the 'o' option to get the\n" -"old behavior.\n" -""; +static char *app = "Milliwatt"; static char digital_milliwatt[] = {0x1e,0x0b,0x0b,0x1e,0x9e,0x8b,0x8b,0x9e} ; @@ -161,7 +174,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, milliwatt_exec, synopsis, descrip); + return ast_register_application_xml(app, milliwatt_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Digital Milliwatt (mu-law) Test Application"); diff --git a/apps/app_mixmonitor.c b/apps/app_mixmonitor.c index 0adaa62fe..2955455d3 100644 --- a/apps/app_mixmonitor.c +++ b/apps/app_mixmonitor.c @@ -46,38 +46,78 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/channel.h" +/*** DOCUMENTATION + + + Record a call and mix the audio during the recording. + + + + + If filename is an absolute path, uses that path, otherwise + creates the file in the configured monitoring directory from asterisk.conf. + + + + + + + + + + + + + + Will be executed when the recording is over. + Any strings matching ^{X} will be unescaped to X. + All variables will be evaluated at the time MixMonitor is called. + + + + Records the audio on the current channel to the specified file. + + + Will contain the filename used to record. + + + + + + + Stop recording a call through MixMonitor. + + + + Stops the audio recording that was started with a call to MixMonitor() + on the current channel. + + + + ***/ + #define get_volfactor(x) x ? ((x > 0) ? (1 << x) : ((1 << abs(x)) * -1)) : 0 static const char *app = "MixMonitor"; -static const char *synopsis = "Record a call and mix the audio during the recording"; -static const char *desc = "" -" MixMonitor(.[,[,]]):\n" -"Records the audio on the current channel to the specified file.\n" -"If the filename is an absolute path, uses that path, otherwise\n" -"creates the file in the configured monitoring directory from\n" -"asterisk.conf.\n\n" -"Valid options:\n" -" a - Append to the file instead of overwriting it.\n" -" b - Only save audio to the file while the channel is bridged.\n" -" Note: Does not include conferences or sounds played to each bridged\n" -" party.\n" -" v() - Adjust the heard volume by a factor of (range -4 to 4)\n" -" V() - Adjust the spoken volume by a factor of (range -4 to 4)\n" -" W() - Adjust the both heard and spoken volumes by a factor of \n" -" (range -4 to 4)\n\n" -" will be executed when the recording is over\n" -"Any strings matching ^{X} will be unescaped to ${X}.\n" -"All variables will be evaluated at the time MixMonitor is called.\n" -"The variable MIXMONITOR_FILENAME will contain the filename used to record.\n" -""; static const char *stop_app = "StopMixMonitor"; -static const char *stop_synopsis = "Stop recording a call through MixMonitor"; -static const char *stop_desc = "" -" StopMixMonitor():\n" -"Stops the audio recording that was started with a call to MixMonitor()\n" -"on the current channel.\n" -""; struct module_symbols *me; @@ -415,8 +455,8 @@ static int load_module(void) int res; ast_cli_register_multiple(cli_mixmonitor, sizeof(cli_mixmonitor) / sizeof(struct ast_cli_entry)); - res = ast_register_application(app, mixmonitor_exec, synopsis, desc); - res |= ast_register_application(stop_app, stop_mixmonitor_exec, stop_synopsis, stop_desc); + res = ast_register_application_xml(app, mixmonitor_exec); + res |= ast_register_application_xml(stop_app, stop_mixmonitor_exec); return res; } diff --git a/apps/app_morsecode.c b/apps/app_morsecode.c index 455ee04c1..f9005296a 100644 --- a/apps/app_morsecode.c +++ b/apps/app_morsecode.c @@ -34,18 +34,33 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/indications.h" +/*** DOCUMENTATION + + + Plays morse code + + + + String to playback as morse code to channel + + + + Plays the Morse code equivalent of the passed string. + + This application uses the following variables: + + + Use this value in (ms) for length of dit + + + The pitch of the tone in (Hz), default is 800 + + + + + ***/ static char *app_morsecode = "Morsecode"; -static char *morsecode_synopsis = "Plays morse code"; - -static char *morsecode_descrip = -" Morsecode():\n" -"Plays the Morse code equivalent of the passed string. If the variable\n" -"MORSEDITLEN is set, it will use that value for the length (in ms) of the dit\n" -"(defaults to 80). Additionally, if MORSETONE is set, it will use that tone\n" -"(in Hz). The tone default is 800.\n"; - - static char *morsecode[] = { "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", /* 0-15 */ "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", /* 16-31 */ @@ -159,7 +174,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app_morsecode, morsecode_exec, morsecode_synopsis, morsecode_descrip); + return ast_register_application_xml(app_morsecode, morsecode_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Morse code"); diff --git a/apps/app_mp3.c b/apps/app_mp3.c index 23db94fbc..688be6a00 100644 --- a/apps/app_mp3.c +++ b/apps/app_mp3.c @@ -44,16 +44,26 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define LOCAL_MPG_123 "/usr/local/bin/mpg123" #define MPG_123 "/usr/bin/mpg123" +/*** DOCUMENTATION + + + Play an MP3 file or stream. + + + + Location of the file to be played. + (argument passed to mpg123) + + + + Executes mpg123 to play the given location, which typically would be a filename or a URL. + User can exit by pressing any key on the dialpad, or by hanging up. + + + + ***/ static char *app = "MP3Player"; -static char *synopsis = "Play an MP3 file or stream"; - -static char *descrip = -" MP3Player(location): Executes mpg123 to play the given location,\n" -"which typically would be a filename or a URL. User can exit by pressing\n" -"any key on the dialpad, or by hanging up."; - - static int mp3play(char *filename, int fd) { int res; @@ -221,7 +231,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, mp3_exec, synopsis, descrip); + return ast_register_application_xml(app, mp3_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Silly MP3 Application"); diff --git a/apps/app_nbscat.c b/apps/app_nbscat.c index 5bc920f50..dd071ef0e 100644 --- a/apps/app_nbscat.c +++ b/apps/app_nbscat.c @@ -43,6 +43,19 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/translate.h" #include "asterisk/app.h" +/*** DOCUMENTATION + + + Play an NBS local stream. + + + + Executes nbscat to listen to the local NBS stream. + User can exit by pressing any key. + + + ***/ + #define LOCAL_NBSCAT "/usr/local/bin/nbscat8k" #define NBSCAT "/usr/bin/nbscat8k" @@ -52,13 +65,6 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "NBScat"; -static char *synopsis = "Play an NBS local stream"; - -static char *descrip = -" NBScat(): Executes nbscat to listen to the local NBS stream.\n" -"User can exit by pressing any key.\n"; - - static int NBScatplay(int fd) { int res; @@ -204,7 +210,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, NBScat_exec, synopsis, descrip); + return ast_register_application_xml(app, NBScat_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Silly NBS Stream Application"); diff --git a/apps/app_page.c b/apps/app_page.c index 33ff1b489..7aacbd9d6 100644 --- a/apps/app_page.c +++ b/apps/app_page.c @@ -44,24 +44,57 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/devicestate.h" #include "asterisk/dial.h" +/*** DOCUMENTATION + + + Page series of phones + + + + + Specification of the device(s) to dial. These must be in the format of + Technology/Resource, where Technology + represents a particular channel driver, and Resource represents a resource + available to that particular channel driver. + + + Optional extra devices to dial inparallel + If you need more then one enter them as Technology2/Resource2& + Technology3/Resourse3&..... + + + + + + + + + + + + Specify the length of time that the system will attempt to connect a call. + After this duration, any intercom calls that have not been answered will be hung up by the + system. + + + + Places outbound calls to the given technology/resource + and dumps them into a conference bridge as muted participants. The original + caller is dumped into the conference as a speaker and the room is + destroyed when the original callers leaves. + + + ***/ static const char *app_page= "Page"; -static const char *page_synopsis = "Pages phones"; - -static const char *page_descrip = -"Page(Technology/Resource&Technology2/Resource2[,options][,timeout])\n" -" Places outbound calls to the given technology / resource and dumps\n" -"them into a conference bridge as muted participants. The original\n" -"caller is dumped into the conference as a speaker and the room is\n" -"destroyed when the original caller leaves. Valid options are:\n" -" d - full duplex audio\n" -" q - quiet, do not play beep to caller\n" -" r - record the page into a file (see 'r' for app_meetme)\n" -" s - only dial channel if devicestate says it is not in use\n" -"The timeout parameter specifies the length of time that the system\n" -"will attempt to connect a call. After this duration, any intercom\n" -"calls that have not been answered will be hung up by the system.\n"; - enum { PAGE_DUPLEX = (1 << 0), PAGE_QUIET = (1 << 1), @@ -216,7 +249,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app_page, page_exec, page_synopsis, page_descrip); + return ast_register_application_xml(app_page, page_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Page Multiple Phones"); diff --git a/apps/app_playback.c b/apps/app_playback.c index 4e6c3f530..63dd30857 100644 --- a/apps/app_playback.c +++ b/apps/app_playback.c @@ -39,26 +39,49 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" /* provides config-file based 'say' functions */ #include "asterisk/cli.h" -static char *app = "Playback"; - -static char *synopsis = "Play a file"; - -static char *descrip = -" Playback(filename[&filename2...][,option]): Plays back given filenames (do not put\n" -"extension). Options may also be included following a comma.\n" -"The 'skip' option causes the playback of the message to be skipped if the channel\n" -"is not in the 'up' state (i.e. it hasn't been answered yet). If 'skip' is \n" -"specified, the application will return immediately should the channel not be\n" -"off hook. Otherwise, unless 'noanswer' is specified, the channel will\n" -"be answered before the sound is played. Not all channels support playing\n" -"messages while still on hook.\n" -"This application sets the following channel variable upon completion:\n" -" PLAYBACKSTATUS The status of the playback attempt as a text string, one of\n" -" SUCCESS | FAILED\n" -"See Also: Background (application) -- for playing soundfiles that are interruptible\n" -" WaitExten (application) -- wait for digits from caller, optionally play music on hold\n" -; +/*** DOCUMENTATION + + + Play a file. + + + + + + + + Comma separated list of options + + + + + + + + Plays back given filenames (do not put extension of wav/alaw etc). + The playback command answer the channel if no options are specified. + If the file is non-existant it will fail + This application sets the following channel variable upon completion: + + + The status of the playback attempt as a text string. + + + + + See Also: Background (application) -- for playing soundfiles that are interruptible + WaitExten (application) -- wait for digits from caller, optionally play music on hold + + + ***/ +static char *app = "Playback"; static struct ast_config *say_cfg = NULL; /* save the say' api calls. @@ -520,7 +543,7 @@ static int load_module(void) } ast_cli_register_multiple(cli_playback, sizeof(cli_playback) / sizeof(struct ast_cli_entry)); - return ast_register_application(app, playback_exec, synopsis, descrip); + return ast_register_application_xml(app, playback_exec); } AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Sound File Playback Application", diff --git a/apps/app_privacy.c b/apps/app_privacy.c index 09f698861..71811de1c 100644 --- a/apps/app_privacy.c +++ b/apps/app_privacy.c @@ -41,25 +41,41 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/config.h" -static char *app = "PrivacyManager"; - -static char *synopsis = "Require phone number to be entered, if no CallerID sent"; +/*** DOCUMENTATION + + + Require phone number to be entered, if no CallerID sent + + + + Total tries caller is allowed to input a callerid. Defaults to 3. + + + Minimum allowable digits in the input callerid number. Defaults to 10. + + + Context to check the given callerid against patterns. + + + + If no Caller*ID is sent, PrivacyManager answers the channel and asks + the caller to enter their phone number. The caller is given + maxretries attempts to do so. The application does + nothing if Caller*ID was received on the channel. + The application sets the following channel variable upon completion: + + + The status of the privacy manager's attempt to collect a phone number from the user. + + + + + + + ***/ -static char *descrip = - " PrivacyManager([maxretries][,minlength][,context]): If no Caller*ID \n" - "is sent, PrivacyManager answers the channel and asks the caller to\n" - "enter their phone number. The caller is given 'maxretries' attempts to do so.\n" - "The application does nothing if Caller*ID was received on the channel.\n" - " maxretries default 3 -maximum number of attempts the caller is allowed \n" - " to input a callerid.\n" - " minlength default 10 -minimum allowable digits in the input callerid number.\n" - " context context to check the given Caller*ID against patterns.\n" - "The application sets the following channel variable upon completion: \n" - "PRIVACYMGRSTATUS The status of the privacy manager's attempt to collect \n" - " a phone number from the user. A text string that is either:\n" - " SUCCESS | FAILED \n" -; +static char *app = "PrivacyManager"; static int privacy_exec (struct ast_channel *chan, void *data) { @@ -178,7 +194,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, privacy_exec, synopsis, descrip); + return ast_register_application_xml(app, privacy_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Require phone number to be entered, if no CallerID sent"); diff --git a/apps/app_queue.c b/apps/app_queue.c index 5733d0bc4..bc04deb46 100644 --- a/apps/app_queue.c +++ b/apps/app_queue.c @@ -108,6 +108,344 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") * to this order! */ +/*** DOCUMENTATION + + + Queue a call for a call queue. + + + + + + + + + + + + + + + + + + + + + + + + URL will be sent to the called party if the channel supports it. + + + + Will cause the queue to fail out after a specified number of + seconds, checked between each queues.conf timeout and + retry cycle. + + + Will setup an AGI script to be executed on the calling party's channel once they are + connected to a queue member. + + + Will run a macro on the calling party's channel once they are connected to a queue member. + + + Will run a gosub on the calling party's channel once they are connected to a queue member. + + + Will cause the queue's defaultrule to be overridden by the rule specified. + + + + In addition to transferring the call, a call may be parked and then picked + up by another user. + This application will return to the dialplan if the queue does not exist, or + any of the join options cause the caller to not enter the queue. + This application sets the following channel variable upon completion: + + + The status of the call as a text string. + + + + + + + + + + + + + + Dynamically adds queue members. + + + + + + + + + + + Dynamically adds interface to an existing queue. If the interface is + already in the queue it will return an error. + This application sets the following channel variable upon completion: + + + The status of the attempt to add a queue member as a text string. + + + + + + + + + + Dynamically removes queue members. + + + + + + + + If the interface is NOT in the queue it will return an error. + This application sets the following channel variable upon completion: + + + + + + + + Example: RemoveQueueMember(techsupport,SIP/3000) + + + + + Pauses a queue member. + + + + + + + Is used to add extra information to the appropriate queue_log entries and manager events. + + + + Pauses (blocks calls for) a queue member. The given interface will be paused in the given queue. + This prevents any calls from being sent from the queue to the interface until it is + unpaused with UnpauseQueueMember or the manager interface. If no queuename is given, + the interface is paused in every queue it is a member of. The application will fail if the + interface is not found. + This application sets the following channel variable upon completion: + + + The status of the attempt to pause a queue member as a text string. + + + + + Example: PauseQueueMember(,SIP/3000) + + + + + Unpauses a queue member. + + + + + + + Is used to add extra information to the appropriate queue_log entries and manager events. + + + + Unpauses (resumes calls to) a queue member. This is the counterpart to PauseQueueMember() + and operates exactly the same way, except it unpauses instead of pausing the given interface. + This application sets the following channel variable upon completion: + + + The status of the attempt to unpause a queue member as a text string. + + + + + Example: UnpauseQueueMember(,SIP/3000) + + + + + Writes to the queue_log file. + + + + + + + + + + Allows you to write your own events into the queue log. + Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600) + + + + + Return Queue information in variables. + + + + + + Maxmimum number of calls allowed. + + + The strategy of the queue. + + + Number of calls currently in the queue. + + + Current average hold time. + + + Number of completed calls for the queue. + + + Number of abandoned calls. + + + Queue service level. + + + Current service level performance. + + + + + + Makes the following queue variables available. + Returns 0 if queue is found and setqueuevar is defined, -1 otherwise. + + + + + Count number of members answering a queue. + + + + + + + Returns the number of logged-in members for the specified queue. + + + Returns the number of logged-in members for the specified queue available to take a call. + + + Returns the total number of members for the specified queue. + + + + + + Returns the number of members currently associated with the specified queuename. + + + + + Count number of members answering a queue. + + + + + + Returns the number of members currently associated with the specified queuename. + This function has been deprecated in favor of the QUEUE_MEMBER() function + + + + + Count number of calls currently waiting in a queue. + + + + + + Returns the number of callers currently waiting in the specified queuename. + + + + + Returns a list of interfaces on a queue. + + + + + + Returns a comma-separated list of members associated with the specified queuename. + + + + + Gets or sets queue members penalty. + + + + + + + Gets or sets queue members penalty. + + + + ***/ + enum { QUEUE_STRATEGY_RINGALL = 0, QUEUE_STRATEGY_LEASTRECENT, @@ -150,128 +488,15 @@ static struct ast_taskprocessor *devicestate_tps; static char *app = "Queue"; -static char *synopsis = "Queue a call for a call queue"; - -static char *descrip = -" Queue(queuename[,options[,URL][,announceoverride][,timeout][,AGI][,macro][,gosub][,rule]):\n" -"Queues an incoming call in a particular call queue as defined in queues.conf.\n" -"This application will return to the dialplan if the queue does not exist, or\n" -"any of the join options cause the caller to not enter the queue.\n" -"The option string may contain zero or more of the following characters:\n" -" 'c' -- continue in the dialplan if the callee hangs up.\n" -" 'd' -- data-quality (modem) call (minimum delay).\n" -" 'h' -- allow callee to hang up by hitting '*', or whatver disconnect sequence\n" -" that is defined in the featuremap section in features.conf.\n" -" 'H' -- allow caller to hang up by hitting '*', or whatever disconnect sequence\n" -" that is defined in the featuremap section in features.conf.\n" -" 'n' -- no retries on the timeout; will exit this application and \n" -" go to the next step.\n" -" 'i' -- ignore call forward requests from queue members and do nothing\n" -" when they are requested.\n" -" 'r' -- ring instead of playing MOH. Periodic Announcements are still made, if applicable.\n" -" 't' -- allow the called user transfer the calling user by pressing '#' or\n" -" whatever blindxfer sequence defined in the featuremap section in\n" -" features.conf\n" -" 'T' -- to allow the calling user to transfer the call by pressing '#' or\n" -" whatever blindxfer sequence defined in the featuremap section in\n" -" features.conf\n" -" 'w' -- allow the called user to write the conversation to disk via Monitor\n" -" by pressing the automon sequence defined in the featuremap section in\n" -" features.conf\n" -" 'W' -- allow the calling user to write the conversation to disk via Monitor\n" -" by pressing the automon sequence defined in the featuremap section in\n" -" features.conf\n" -" 'k' -- Allow the called party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in features.conf.\n" -" 'K' -- Allow the calling party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in features.conf.\n" -" 'x' -- allow the called user to write the conversation to disk via MixMonitor\n" -" by pressing the automixmon sequence defined in the featuremap section in\n" -" features.conf\n" -" 'X' -- allow the calling user to write the conversation to disk via MixMonitor\n" -" by pressing the automixmon sequence defined in the featuremap section in\n" -" features.conf\n" -" The optional URL will be sent to the called party if the channel supports\n" -"it.\n" -" The optional AGI parameter will setup an AGI script to be executed on the \n" -"calling party's channel once they are connected to a queue member.\n" -" The optional macro parameter will run a macro on the \n" -"calling party's channel once they are connected to a queue member.\n" -" The optional gosub parameter will run a gosub on the \n" -"calling party's channel once they are connected to a queue member.\n" -" The optional rule parameter will cause the queue's defaultrule to be\n" -"overridden by the rule specified.\n" -" The timeout will cause the queue to fail out after a specified number of\n" -"seconds, checked between each queues.conf 'timeout' and 'retry' cycle.\n" -" This application sets the following channel variable upon completion:\n" -" QUEUESTATUS The status of the call as a text string, one of\n" -" TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL | CONTINUE\n"; - static char *app_aqm = "AddQueueMember" ; -static char *app_aqm_synopsis = "Dynamically adds queue members" ; -static char *app_aqm_descrip = -" AddQueueMember(queuename[,interface[,penalty[,options[,membername[,stateinterface]]]]]):\n" -"Dynamically adds interface to an existing queue.\n" -"If the interface is already in the queue it will return an error.\n" -" This application sets the following channel variable upon completion:\n" -" AQMSTATUS The status of the attempt to add a queue member as a \n" -" text string, one of\n" -" ADDED | MEMBERALREADY | NOSUCHQUEUE \n" -"Example: AddQueueMember(techsupport,SIP/3000)\n" -""; static char *app_rqm = "RemoveQueueMember" ; -static char *app_rqm_synopsis = "Dynamically removes queue members" ; -static char *app_rqm_descrip = -" RemoveQueueMember(queuename[,interface[,options]]):\n" -"Dynamically removes interface to an existing queue\n" -"If the interface is NOT in the queue it will return an error.\n" -" This application sets the following channel variable upon completion:\n" -" RQMSTATUS The status of the attempt to remove a queue member as a\n" -" text string, one of\n" -" REMOVED | NOTINQUEUE | NOSUCHQUEUE \n" -"Example: RemoveQueueMember(techsupport,SIP/3000)\n" -""; static char *app_pqm = "PauseQueueMember" ; -static char *app_pqm_synopsis = "Pauses a queue member" ; -static char *app_pqm_descrip = -" PauseQueueMember([queuename],interface[,options[,reason]]):\n" -"Pauses (blocks calls for) a queue member.\n" -"The given interface will be paused in the given queue. This prevents\n" -"any calls from being sent from the queue to the interface until it is\n" -"unpaused with UnpauseQueueMember or the manager interface. If no\n" -"queuename is given, the interface is paused in every queue it is a\n" -"member of. The application will fail if the interface is not found.\n" -"The reason string is entirely optional and is used to add extra information\n" -"to the appropriate queue_log entries and manager events.\n" -" This application sets the following channel variable upon completion:\n" -" PQMSTATUS The status of the attempt to pause a queue member as a\n" -" text string, one of\n" -" PAUSED | NOTFOUND\n" -"Example: PauseQueueMember(,SIP/3000)\n"; static char *app_upqm = "UnpauseQueueMember" ; -static char *app_upqm_synopsis = "Unpauses a queue member" ; -static char *app_upqm_descrip = -" UnpauseQueueMember([queuename],interface[,options[,reason]]):\n" -"Unpauses (resumes calls to) a queue member.\n" -"This is the counterpart to PauseQueueMember and operates exactly the\n" -"same way, except it unpauses instead of pausing the given interface.\n" -"The reason string is entirely optional and is used to add extra information\n" -"to the appropriate queue_log entries and manager events.\n" -" This application sets the following channel variable upon completion:\n" -" UPQMSTATUS The status of the attempt to unpause a queue \n" -" member as a text string, one of\n" -" UNPAUSED | NOTFOUND\n" -"Example: UnpauseQueueMember(,SIP/3000)\n"; static char *app_ql = "QueueLog" ; -static char *app_ql_synopsis = "Writes to the queue_log" ; -static char *app_ql_descrip = -" QueueLog(queuename,uniqueid,agent,event[,additionalinfo]):\n" -"Allows you to write your own events into the queue log\n" -"Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)\n"; /*! \brief Persistent Members astdb family */ static const char *pm_family = "Queue/PersistentMembers"; @@ -5088,69 +5313,31 @@ static int queue_function_memberpenalty_write(struct ast_channel *chan, const ch static struct ast_custom_function queuevar_function = { .name = "QUEUE_VARIABLES", - .synopsis = "Return Queue information in variables", - .syntax = "QUEUE_VARIABLES()", - .desc = -"Makes the following queue variables available.\n" -"QUEUEMAX maxmimum number of calls allowed\n" -"QUEUESTRATEGY the strategy of the queue\n" -"QUEUECALLS number of calls currently in the queue\n" -"QUEUEHOLDTIME current average hold time\n" -"QUEUECOMPLETED number of completed calls for the queue\n" -"QUEUEABANDONED number of abandoned calls\n" -"QUEUESRVLEVEL queue service level\n" -"QUEUESRVLEVELPERF current service level performance\n" -"Returns 0 if queue is found and setqueuevar is defined, -1 otherwise", .read = queue_function_var, }; static struct ast_custom_function queuemembercount_function = { .name = "QUEUE_MEMBER", - .synopsis = "Count number of members answering a queue", - .syntax = "QUEUE_MEMBER(,