diff --git a/ChangeLog b/ChangeLog index 7e6b987ef5..045906116a 100755 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2005-11-11 Russell Bryant + + * many files in apps/: Clean up application descriptions. Clarify some wording and make sure they wrap at 80 characters. + 2005-11-10 Mark Spencer * rtp.c (ast_rtp_raw_write): use unsigned int for return value from calc_txstamp() (issue #5595) @@ -44,12 +48,14 @@ * app.c (ast_app_parse_options): don't increment 's' until after checking for NULL (related to issue #5630) - * apps/app_rpt.c: solve a memory leak (config structure was not freed) (issue #5706 + * apps/app_rpt.c: solve a memory leak (config structure was not freed) (issue #5706) 2005-11-10 Russell Bryant * app.c (ast_app_separate_args): Don't consider the open parenthesis as part of the arguments to an option. (issue #5630) + * many files: Change all references to ast_separate_app_args to ast_app_separate_args + * many files in apps/: Clean up some application descriptions. Make sure all descriptions in changed files are wrapped at 80 characters. 2005-11-09 Russell Bryant diff --git a/apps/app_controlplayback.c b/apps/app_controlplayback.c index 6cd577d7f3..dab0c156c1 100755 --- a/apps/app_controlplayback.c +++ b/apps/app_controlplayback.c @@ -48,18 +48,22 @@ static const char *app = "ControlPlayback"; static const char *synopsis = "Play a file with fast forward and rewind"; static const char *descrip = -"ControlPlayback(filename[|skipms[|ffchar[|rewchar[|stopchar[|pausechar[|restartchar[|option]]]]]]]):\n" -" Plays back a given filename (do not put extension). Options may also\n" -" be included following a pipe symbol. You can use * and # to rewind and\n" -" fast forward the playback specified. If 'stopchar' is added the file will\n" -" terminate playback when 'stopchar' is pressed. If 'restartchar' is added, the file\n" -" will restart when 'restartchar' is pressed.\n" -" The option string may contain the following character:\n" -" 'j' -- jump to +101 priority if the file requested isn't found.\n" -" This application sets the following channel variable upon completion:\n" -" CPLAYBACKSTATUS The status of the attempt as a text string, one of\n" -" SUCCESS | USERSTOPPED | ERROR\n" -" Example: exten => 1234,1,ControlPlayback(file|4000|*|#|1|0|5)\n\n"; +" 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" +" j - Jump to priority n+101 if the requested file is not found.\n" +"This application sets the following channel variable upon completion:\n" +" CPLAYBACKSTATUS - This variable contains the status of the attempt as a text\n" +" string, one of: SUCCESS | USERSTOPPED | ERROR\n"; STANDARD_LOCAL_USER; diff --git a/apps/app_curl.c b/apps/app_curl.c index ebe664e6e7..5cf4b167df 100755 --- a/apps/app_curl.c +++ b/apps/app_curl.c @@ -48,10 +48,14 @@ static char *app = "Curl"; static char *synopsis = "Load an external URL"; static char *descrip = -" Curl(URL[|postdata]): Requests the URL. Mainly used for signalling\n" -"external applications of an event. Curl will fail on fatal errors. \n" -"Argument specified treated as POST data. Also sets CURL variable with the\n" -"resulting page.\n"; +" Curl(URL[|postdata]): This application will request the specified URL.\n" +"It is mainly used for signalling external applications of an event.\n" +"Parameters:\n" +" URL - This is the external URL to request.\n" +" postdata - This information will be treated as POST data.\n" +"This application will set the following variable:\n" +" CURL - This variable will contain the resulting page.\n" +"This application has been deprecated in favor of the CURL function.\n"; STANDARD_LOCAL_USER; diff --git a/apps/app_cut.c b/apps/app_cut.c index 718583ec73..4eb6e552e0 100755 --- a/apps/app_cut.c +++ b/apps/app_cut.c @@ -42,29 +42,32 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") /* Maximum length of any variable */ #define MAXRESULT 1024 -static char *tdesc = "String manipulation"; +static char *tdesc = "Cut out information from a string"; static char *app_cut = "Cut"; -static char *cut_synopsis = "Splits a variable's content using the specified delimiter"; +static char *cut_synopsis = "Splits a variable's contents using the specified delimiter"; static char *cut_descrip = -"Usage: Cut(newvar=varname,delimiter,fieldspec)\n" +" Cut(newvar=varname,delimiter,fieldspec): This applicaiton will split the\n" +"contents of a variable based on the given delimeter and store the result in\n" +"a new variable.\n" +"Parameters:\n" " newvar - new variable created from result string\n" " varname - variable you want cut\n" " delimiter - defaults to '-'\n" " fieldspec - number of the field you want (1-based offset)\n" -" may also be specified as a range (with -)\n" -" or group of ranges and fields (with &)\n" -" The process with complete on success or fail on hangup or error\n"; +" may also be specified as a range (with -)\n" +" or group of ranges and fields (with &)\n" +"This application has been deprecated in favor of the CUT function.\n"; static char *app_sort = "Sort"; static char *app_sort_synopsis = "Sorts a list of keywords and values"; static char *app_sort_descrip = -" Sort(=:[,:[[...],:]])\n" -"Sorts the list provided by using the value as a float to order the list of\n" -"keywords in ascending order. Sets the variable provided to the list of\n" -"sorted keywords. \n"; +" Sort(newvar=key1:val1[,key2:val2[[...],keyN:valN]]): This application will\n" +"sort the list provided in ascending order. The result will be stored in the\n" +"specified variable name.\n" +" This applicaiton has been deprecated in favor of the SORT function.\n"; STANDARD_LOCAL_USER; diff --git a/apps/app_datetime.c b/apps/app_datetime.c index 4adb646ff8..b10ad97e63 100755 --- a/apps/app_datetime.c +++ b/apps/app_datetime.c @@ -46,8 +46,7 @@ static char *app = "DateTime"; static char *synopsis = "Say the date and time"; static char *descrip = -" DateTime(): Says the current date and time. Terminates on hangup or\n" -"completion.\n"; +" DateTime(): This application will say the current date and time.\n"; STANDARD_LOCAL_USER; diff --git a/apps/app_db.c b/apps/app_db.c index 659f9686e7..245c8d3caf 100755 --- a/apps/app_db.c +++ b/apps/app_db.c @@ -45,27 +45,30 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/lock.h" #include "asterisk/options.h" -static char *tdesc = "Database access functions for Asterisk extension logic"; +static char *tdesc = "Database Access Functions"; static char *g_descrip = - " DBget(varname=family/key[|options]): Retrieves a value from the Asterisk\n" - "database and stores it in the given variable.\n" - " The option string may contain the following character:\n" - " 'j' -- jump to +101 priority if the requested family/key isn't found.\n" - " This application sets the following channel variable upon completion:\n" - " DBGETSTATUS The status of the attempt as a text string, one of\n" - " FOUND | NOTFOUND \n"; +" DBget(varname=family/key[|options]): This application will retrieve a value\n" +"from the Asterisk database and store it in the given variable.\n" +" Options:\n" +" j - Jump to priority n+101 if the requested family/key isn't found.\n" +" This application sets the following channel variable upon completion:\n" +" DBGETSTATUS - This variable will contain the status of the attempt\n" +" FOUND | NOTFOUND \n" +" This application has been deprecated in favor of the DB function.\n"; static char *p_descrip = - " DBput(family/key=value): Stores the given value in the Asterisk\n" - "database.\n"; +" DBput(family/key=value): This application will store the given value in the\n" +"specified location in the Asterisk database.\n" +" This application has been deprecated in favor of the DB function.\n"; static char *d_descrip = - " DBdel(family/key): Deletes a key from the Asterisk database.\n"; +" DBdel(family/key): This applicaiton will delete a key from the Asterisk\n" +"database.\n"; static char *dt_descrip = - " DBdeltree(family[/keytree]): Deletes a family or keytree from the Asterisk\n" - "database.\n"; +" DBdeltree(family[/keytree]): This application will delete a family or keytree\n" +"from the Asterisk database\n"; static char *g_app = "DBget"; static char *p_app = "DBput"; diff --git a/apps/app_dial.c b/apps/app_dial.c index 4851e98ab1..97196bc8cd 100755 --- a/apps/app_dial.c +++ b/apps/app_dial.c @@ -63,97 +63,127 @@ static char *app = "Dial"; static char *synopsis = "Place a call and connect to the current channel"; static char *descrip = -" Dial(Technology/resource[&Technology2/resource2...][|timeout][|options][|URL]):\n" -"Requests one or more channels and places specified outgoing calls on them.\n" -"As soon as a channel answers, the Dial app will answer the originating\n" -"channel (if it needs to be answered) and will bridge a call with the channel\n" -"which first answered. All other calls placed by the Dial app will be hung up.\n" -"If a timeout is not specified, the Dial application will wait indefinitely\n" -"until either one of the called channels answers, the user hangs up, or all\n" -"channels return busy or error. The dialplan will continue execution if the\n" -"the calls cannot be placed, or if the timeout expires.\n" -" For the Privacy and Screening Modes, the DIALSTATUS variable will be set to DONTCALL, \n" -"if the called party chooses to send the calling party to the 'Go Away' script, and \n" -"the DIALSTATUS variable will be set to TORTURE, if the called party wants to send the caller to \n" -"the TORTURE scripts\n" -" This application will report normal termination if the originating channel hangs up, or if the\n" -"call is bridged and either of the parties in the bridge ends the call.\n" -"The option string may contain zero or more of the following characters:\n" -" 'A(x)' -- play an announcement to the called party, using x as file\n" -" 'C' -- reset call detail record for this call.\n" -" 'd' -- allow the calling user to dial a 1 digit extension while waiting for a call to\n" -" be answered exiting to that extension if it exists in the context defined by\n" -" ${EXITCONTEXT} or the current context.\n" -" 'D([called][:calling])' -- Send DTMF strings *after* called party has answered, but before the\n" -" call gets bridged. The 'called' DTMF string is sent to the called party, and the\n" -" 'calling' DTMF string is sent to the calling party. Both parameters can be used alone.\n" -" 'f' -- Forces callerid to be set as the extension of the line \n" -" making/redirecting the outgoing call. For example, some PSTNs\n" -" don't allow callerid set to numbers that are not assigned to you.\n" -" 'g' -- goes on in context if the destination channel hangs up\n" -" 'G(context^exten^pri)' -- If the call is answered transfer both parties to the specified exten.\n" -" 'h' -- allow callee to hang up by hitting *.\n" -" 'H' -- allow caller to hang up by hitting *.\n" -" 'j' -- Jump to n+101 if all of the channels were busy.\n" -" 'L(x[:y][:z])' -- Limit the call to 'x' ms warning when 'y' ms are left\n" -" repeated every 'z' ms) Only 'x' is required, 'y' and 'z' are optional.\n" -" The following special variables are optional:\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" -" 'timeleft' is a special sound macro to auto-say the time \n" -" left and is the default.\n" -" 'm[(class)]' -- provide hold music to the calling party until answered (optionally\n" -" with the specified class.\n" -" 'M(x[^arg])' -- Executes the macro (x with ^ delim arg list) upon connect of the call.\n" -" Also, the macro can set the MACRO_RESULT variable to do the following:\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+101 only if those options are set)\n" -" -- CONTINUE - Hangup the called party and continue on in the dialplan.\n" -" -- GOTO:^^ - Transfer the call.\n" -" 'n' -- modifier for screen/privacy mode. No intros are to be saved in the priv-callerintros dir.\n" -" 'N' -- modifier for screen/privacy mode. if callerID is present, do not screen the call.\n" -" 'o' -- Original (inbound) Caller*ID should be placed on the outbound leg of the call\n" -" instead of using the destination extension (old style asterisk behavior)\n" -" 'p' -- screening mode. Basically Privacy mode without memory.\n" -" 'P[(x)]' -- privacy mode, using 'x' as database if provided, or the extension is used if not provided.\n" -" 'r' -- indicate ringing to the calling party, pass no audio until answered.\n" -" 'S(x)' -- hangup the call after x seconds AFTER called party picked up\n" -" 't' -- allow the called user to transfer the calling user by hitting the key sequence defiend in features.conf.\n" -" 'T' -- allow the calling user to transfer the call by hitting the key sequence defined in features.conf.\n" -" 'w' -- allow the called user to write the conversation to disk via Monitor\n" -" 'W' -- allow the calling user to write the conversation to disk via Monitor\n\n" -" In addition to transferring the call, a call may be parked and then picked\n" -"up by another user.\n" +" Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL]):\n" +"This applicaiton 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" +" This application sets the following channel variables upon completion:\n" +" DIALEDTIME - This is the time from dialing a channel until when it\n" +" answers.\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\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 SetGroup).\n" -" This application sets the following channel variables upon completion:\n" -" DIALEDTIME Time from dial to answer\n" -" ANSWEREDTIME Time for actual call\n" -" DIALSTATUS The status of the call as a text string, one of\n" -" CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL | DONTCALL | TORTURE\n" -""; +"application will be put into that group (as in Set(GROUP()=...).\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" +" 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" +" 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" +" 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 both parties to\n" +" the specified priority. Optionally, an extension, or extension and\n" +" context may be specified. Otherwise, the current extension is used.\n" +" h - Allow the called party to hang up by sending the '*' DTMF digit.\n" +" H - Allow the calling party to hang up by hitting the '*' DTMF digit.\n" +" j - Jump to priority n+101 if all of the requested channels were busy.\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 delimeter. 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. This will also\n" +" have the application jump to priority n+101 if the\n" +" 'j' option is set.\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" +" 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" +" 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 defiend in features.conf.\n" +" T - Allow the calling party to transfer the called party by sending the\n" +" DTMF sequence defined in features.conf.\n" +" w - Allow the called party to enable recording of the call by sending\n" +" the DTMF sequence defined for one-touch recording in features.conf.\n" +" W - Allow the calling party to enable recording of the call by sending\n" +" the DTMF sequence defined for one-touch recording in features.conf.\n"; /* RetryDial App by Anthony Minessale II Jan/2005 */ static char *rapp = "RetryDial"; static char *rsynopsis = "Place a call, retrying on failure allowing optional exit extension."; static char *rdescrip = -" RetryDial(announce|sleep|loops|Technology/resource[&Technology2/resource2...][|timeout][|options][|URL]):\n" -"Attempt to place a call. If no channel can be reached, play the file defined by 'announce'\n" -"waiting 'sleep' seconds to retry the call. If the specified number of attempts matches \n" -"'loops' the call will continue in the dialplan. If 'loops' is set to 0, the call will retry endlessly.\n\n" -"While waiting, a 1 digit extension may be dialed. If that extension exists in either\n" -"the context defined in ${EXITCONTEXT} or the current one, The call will transfer\n" -"to that extension immmediately.\n\n" -"All arguments after 'loops' are passed directly to the Dial() application.\n" -""; - +" 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 'annonce' file will be played. Then, it will wait 'sleep' number of\n" +"seconds before retying the call. After 'retires' 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),