Change Read to set READSTATUS as an indication of the result

Also, some cleanup to CHANGES.
Reported by: michael-fig
Patch by: michael-fig,tilghman
(Closes issue #11004)


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@89489 f38db490-d61c-443f-a65b-d21fe96a405b

3 files changed, 79 insertions, 51 deletions

diff --git a/CHANGES b/CHANGES
index e878cacbf..193f24f80 100644
--- a/CHANGES
+++ b/CHANGES
@@ -52,6 +52,9 @@ CLI Changes
   * Added 'core show channels count' CLI command.
   * Added the ability to set the core debug and verbose values on a per-file basis.
   * Added 'queue pause member' and 'queue unpause member' CLI commands
+  * Ability to set process limits ("ulimit") without restarting Asterisk
+  * Enhanced "agi debug" to print the channel name as a prefix to the debug
+     output to make debugging on busy systems much easier.
 
 SIP changes
 -----------
@@ -99,6 +102,7 @@ IAX2 changes
 Skinny changes
 -------------
   * Added skinny show device, skinny show line, and skinny show settings CLI commands.
+  * Proper codec support in chan_skinny.
 
 DUNDi changes
 -------------
@@ -199,6 +203,27 @@ MeetMe Changes
   * Added the ability to specify the music on hold class used to play into the
      conference when there is only one member and the M option is used.
 
+Other Dialplan Application Changes
+----------------------------------
+  * Argument support for Gosub application
+  * From the to-do lists: straighten out the app timeout args:
+     Wait() app now really does 0.3 seconds- was truncating arg to an int.
+     WaitExten() same as Wait().
+     Congestion() - Now takes floating pt. argument.
+     Busy() - now takes floating pt. argument.
+     Read() - timeout now can be floating pt.
+     WaitForRing() now takes floating pt timeout arg.
+     SpeechBackground() -- clarified in the docstrings that the timeout is an integer seconds.
+  * Added 's' option to Page application.
+  * Added 'E' and 'V' commands to ExternalIVR.
+  * Added 'o' and 'X' options to Chanspy.
+  * Added a new dialplan application, Bridge, which allows you to bridge the
+     calling channel to any other active channel on the system.
+  * Added the ability to specify a music on hold class to play instead of ringing
+     for the SLATrunk application.
+  * The Read application no longer exits the dialplan on error.  Instead, it sets
+     READSTATUS to ERROR, which you can catch and handle separately.
+
 Music On Hold Changes
 ---------------------
   * A new option, "digit", has been added for music on hold classes in 
@@ -271,37 +296,27 @@ Language Support Changes
 Miscellaneous 
 -------------
   * Added the bindaddr option to gtalk.conf.
-  * Argument support for Gosub application
-  * Ability to set process limits without restarting Asterisk
-  * Proper codec support in chan_skinny.
   * Ability to use libcap to set high ToS bits when non-root
      on Linux. If configure is unable to find libcap then you
      can use --with-cap to specify the path.
-  * Added rotatetimestamp option to logger.conf which will use
-     the time to name the logger files instead of sequence number.
+  * Added rotatestrategy option to logger.conf, along with two new options:
+     "timestamp" which will use the time to name the logger files instead of
+     sequence number; and "rotate", which rotates the names of the logfiles,
+     similar to the way syslog rotates files.
+  * Added exec_after_rotate option to logger.conf, which allows a system
+     command to be run after rotation.  This is primarily useful with
+     rotatestrategry=rotate, to allow a limit on the number of logfiles kept
+     and to ensure that the oldest log file gets deleted.
   * Added Masquerade manager event for when a masquerade happens between
      two channels.
-  * From the to-do lists: straighten out the app timeout args:
-     Wait() app now really does 0.3 seconds- was truncating arg to an int.
-     WaitExten() same as Wait().
-     Congestion() - Now takes floating pt. argument.
-     Busy() - now takes floating pt. argument.
-     Read() - timeout now can be floating pt.
-     WaitForRing() now takes floating pt timeout arg.
-     SpeechBackground() -- clarified in the docstrings that the timeout is an integer seconds.
   * Added maxfiles option to options section of asterisk.conf which allows you to specify
      what Asterisk should set as the maximum number of open files when it loads.
   * Added the jittertargetextra configuration option.
   * Added G729 passthrough support to chan_phone for Sigma Designs boards.
-  * Added 's' option to Page application.
-  * Added 'E' and 'V' commands to ExternalIVR.
-  * Added 'o' and 'X' options to Chanspy.
   * Added a new CDR module, cdr_sqlite3_custom.
   * The cdr_manager module has a [mappings] feature, like cdr_custom,
     to add fields to the manager event from the CDR variables.
   * Added a new realtime configuration module, res_config_sqlite
-  * Added a new dialplan application, Bridge, which allows you to bridge the
-     calling channel to any other active channel on the system.
   * Added support for setting the CoS for VLAN traffic (802.1p).  See the sample
      configuration files for the IP channel drivers.  The new option is "cos".
      This information is also documented in doc/qos.tex, or the IP Quality of Service
@@ -321,10 +336,6 @@ Miscellaneous
      It allows you to configure a prefix for auto-monitor recordings.
   * Added support for writing and running your dialplan in lua.  See
      configs/extensions.lua.sample for examples of how to do this.
- * Added a new channel driver, chan_unistim.  See doc/unistim.txt and
-    configs/unistim.conf.sample for details.  This new channel driver allows
-    you to use Nortel i2002, i2004, and i2050 phones with Asterisk.
- * Enhanced "agi debug" to print the channel name as a prefix to the debug
-    output to make debugging on busy systems much easier.
-  * Added the ability to specify a music on hold class to play instead of ringing
-     for the SLATrunk application.
+  * Added a new channel driver, chan_unistim.  See doc/unistim.txt and
+     configs/unistim.conf.sample for details.  This new channel driver allows
+     you to use Nortel i2002, i2004, and i2050 phones with Asterisk.
diff --git a/UPGRADE.txt b/UPGRADE.txt
index 2e4de04d2..7d8eb6a42 100644
--- a/UPGRADE.txt
+++ b/UPGRADE.txt
@@ -78,6 +78,9 @@ Applications:
   introduced dialplan functions LOCK(), TRYLOCK(), and UNLOCK().  You may use
   these functions in any location where you desire to ensure that only one
   channel is executing that path at any one time.
+* Read() now sets a READSTATUS variable on exit.  It does NOT automatically
+  return -1 (and hangup) anymore on error.  If you want to hangup on error,
+  you need to do so explicitly in your dialplan.
 
 Dialplan Functions:
 
diff --git a/apps/app_read.c b/apps/app_read.c
index 81eb95ba9..c6a7e45df 100644
--- a/apps/app_read.c
+++ b/apps/app_read.c
@@ -73,8 +73,11 @@ static char *descrip =
 "  attempts   -- if greater than 1, that many attempts will be made in the \n"
 "                event no data is entered.\n"
 "  timeout    -- The number of seconds to wait for a digit response. If greater\n"
-"                than 0, that value will override the default timeout. Can be floating point.\n\n"
-"Read should disconnect if the function fails or errors out.\n";
+"                than 0, that value will override the default timeout. Can be floating point.\n"
+"This application sets the following channel variable upon completion:\n"
+"    READSTATUS - This is the status of the read operation.\n"
+"                 Possible values are:\n"
+"                 OK | ERROR | HANGUP | INTERRUPTED | SKIPPED | TIMEOUT\n";
 
 
 #define ast_next_data(instr,ptr,delim) if((ptr=strchr(instr,delim))) { *(ptr) = '\0' ; ptr++;}
@@ -87,10 +90,11 @@ static int read_exec(struct ast_channel *chan, void *data)
 	int tries = 1, to = 0, x = 0;
 	double tosec;
 	char *argcopy = NULL;
-	struct ind_tone_zone_sound *ts;
+	struct ind_tone_zone_sound *ts = NULL;
 	struct ast_flags flags = {0};
+	const char *status = "ERROR";
 
-	 AST_DECLARE_APP_ARGS(arglist,
+	AST_DECLARE_APP_ARGS(arglist,
 		AST_APP_ARG(variable);
 		AST_APP_ARG(filename);
 		AST_APP_ARG(maxdigits);
@@ -99,9 +103,10 @@ static int read_exec(struct ast_channel *chan, void *data)
 		AST_APP_ARG(timeout);
 	);
 	
+	pbx_builtin_setvar_helper(chan, "READSTATUS", status);
 	if (ast_strlen_zero(data)) {
 		ast_log(LOG_WARNING, "Read requires an argument (variable)\n");
-		return -1;
+		return 0;
 	}
 	
 	argcopy = ast_strdupa(data);
@@ -122,14 +127,8 @@ static int read_exec(struct ast_channel *chan, void *data)
 		tosec = atof(arglist.timeout);
 		if (tosec <= 0)
 			to = 0;
-		else {
+		else
 			to = tosec * 1000.0;
-			if (to <= 0) {
-				/* Make sure we don't use the default timeout. */
-				ast_log(LOG_WARNING, "Read timeout less than 1 ms, assuming 1 ms timeout\n");
-				to = 1;
-			}
-		}
 	}
 
 	if (ast_strlen_zero(arglist.filename)) {
@@ -137,27 +136,27 @@ static int read_exec(struct ast_channel *chan, void *data)
 	}
 	if (!ast_strlen_zero(arglist.maxdigits)) {
 		maxdigits = atoi(arglist.maxdigits);
-		if ((maxdigits<1) || (maxdigits>255)) {
-    			maxdigits = 255;
+		if ((maxdigits < 1) || (maxdigits > 255)) {
+			maxdigits = 255;
 		} else
 			ast_verb(3, "Accepting a maximum of %d digits.\n", maxdigits);
 	}
 	if (ast_strlen_zero(arglist.variable)) {
 		ast_log(LOG_WARNING, "Invalid! Usage: Read(variable[,filename][,maxdigits][,option][,attempts][,timeout])\n\n");
-		return -1;
+		return 0;
 	}
-	ts=NULL;
-	if (ast_test_flag(&flags,OPT_INDICATION)) {
-		if (!ast_strlen_zero(arglist.filename)) {
-			ts = ast_get_indication_tone(chan->zone,arglist.filename);
+	if (ast_test_flag(&flags, OPT_INDICATION)) {
+		if (! ast_strlen_zero(arglist.filename)) {
+			ts = ast_get_indication_tone(chan->zone, arglist.filename);
 		}
 	}
 	if (chan->_state != AST_STATE_UP) {
-		if (ast_test_flag(&flags,OPT_SKIP)) {
+		if (ast_test_flag(&flags, OPT_SKIP)) {
 			/* At the user's option, skip if the line is not up */
-			pbx_builtin_setvar_helper(chan, arglist.variable, "\0");
+			pbx_builtin_setvar_helper(chan, arglist.variable, "");
+			pbx_builtin_setvar_helper(chan, "READSTATUS", "SKIPPED");
 			return 0;
-		} else if (!ast_test_flag(&flags,OPT_NOANSWER)) {
+		} else if (!ast_test_flag(&flags, OPT_NOANSWER)) {
 			/* Otherwise answer unless we're supposed to read while on-hook */
 			res = ast_answer(chan);
 		}
@@ -173,17 +172,29 @@ static int read_exec(struct ast_channel *chan, void *data)
 					res = ast_waitfordigit(chan, to);
 					ast_playtones_stop(chan);
 					if (res < 1) {
+						if (res == 0)
+							status = "TIMEOUT";
 						tmp[x]='\0';
 						break;
 					}
 					tmp[x++] = res;
 					if (tmp[x-1] == '#') {
 						tmp[x-1] = '\0';
+						status = "OK";
 						break;
 					}
+					if (x >= maxdigits) {
+						status = "OK";
+					}
 				}
 			} else {
 				res = ast_app_getdata(chan, arglist.filename, tmp, maxdigits, to);
+				if (res == 0)
+					status = "OK";
+				else if (res == 1)
+					status = "TIMEOUT";
+				else if (res == 2)
+					status = "INTERRUPTED";
 			}
 			if (res > -1) {
 				pbx_builtin_setvar_helper(chan, arglist.variable, tmp);
@@ -192,11 +203,11 @@ static int read_exec(struct ast_channel *chan, void *data)
 					tries = 0;
 				} else {
 					tries--;
-						if (tries)
+					if (tries)
 						ast_verb(3, "User entered nothing, %d chance%s left\n", tries, (tries != 1) ? "s" : "");
-						else
+					else
 						ast_verb(3, "User entered nothing.\n");
-					}
+				}
 				res = 0;
 			} else {
 				pbx_builtin_setvar_helper(chan, arglist.variable, tmp);
@@ -205,7 +216,10 @@ static int read_exec(struct ast_channel *chan, void *data)
 		}
 	}
 
-	return res;
+	if (ast_check_hangup(chan))
+		status = "HANGUP";
+	pbx_builtin_setvar_helper(chan, "READSTATUS", status);
+	return 0;
 }
 
 static int unload_module(void)