add doxygen documentation and fix various issues with ast_dtmf_stream

(discussed in issue #6087)


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@7969 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 52 insertions, 38 deletions

diff --git a/app.c b/app.c
index 40dbc75af..18c2ab043 100644
--- a/app.c
+++ b/app.c
@@ -279,53 +279,57 @@ int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs)
 	return 0;
 }
 
-int ast_dtmf_stream(struct ast_channel *chan,struct ast_channel *peer,char *digits,int between) 
+int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between) 
 {
-	char *ptr;
+	const char *ptr;
 	int res = 0;
-	struct ast_frame f;
+	struct ast_frame f = {
+		.frametype = AST_FRAME_DTMF,
+		.src = "ast_dtmf_stream"
+	};
+
 	if (!between)
 		between = 100;
 
 	if (peer)
 		res = ast_autoservice_start(peer);
 
-	if (!res) {
-		res = ast_waitfor(chan,100);
-		if (res > -1) {
-			for (ptr=digits; *ptr; ptr++) {
-				if (*ptr == 'w') {
-					res = ast_safe_sleep(chan, 500);
-					if (res) 
-						break;
-					continue;
-				}
-				memset(&f, 0, sizeof(f));
-				f.frametype = AST_FRAME_DTMF;
+	if (!res)
+		res = ast_waitfor(chan, 100);
+
+	/* ast_waitfor will return the number of remaining ms on success */
+	if (res < 0)
+		return res;
+
+	for (ptr = digits; *ptr; ptr++) {
+		if (*ptr == 'w') {
+			/* 'w' -- wait half a second */
+			if ((res = ast_safe_sleep(chan, 500)))
+				break;
+		} else if (strchr("0123456789*#abcdfABCDF", *ptr)) {
+			/* Character represents valid DTMF */
+			if (*ptr == 'f' || *ptr == 'F') {
+				/* ignore return values if not supported by channel */
+				ast_indicate(chan, AST_CONTROL_FLASH);
+			} else {
 				f.subclass = *ptr;
-				f.src = "ast_dtmf_stream";
-				if (strchr("0123456789*#abcdfABCDF",*ptr)==NULL) {
-					ast_log(LOG_WARNING, "Illegal DTMF character '%c' in string. (0-9*#aAbBcCdDfF allowed)\n",*ptr);
-				} else {
-					if (*ptr == 'f' || *ptr == 'F') {
-						/* ignore return values if not supported by channel */
-						ast_indicate(chan, AST_CONTROL_FLASH);
-						res = 0;
-					} else {
-						res = ast_write(chan, &f);
-					}
-					if (res) 
-						break;
-					/* pause between digits */
-					res = ast_safe_sleep(chan,between);
-					if (res) 
-						break;
-				}
+				if ((res = ast_write(chan, &f)))
+					break;
 			}
-		}
-		if (peer)
-			res = ast_autoservice_stop(peer);
+			/* pause between digits */
+			if ((res = ast_safe_sleep(chan, between)))
+				break;
+		} else
+			ast_log(LOG_WARNING, "Illegal DTMF character '%c' in string. (0-9*#aAbBcCdD allowed)\n",*ptr);
 	}
+
+	if (peer) {
+		/* Stop autoservice on the peer channel, but don't overwrite any error condition 
+		   that has occurred previously while acting on the primary channel */
+		if (ast_autoservice_stop(peer) && !res)
+			res = -1;
+	}
+
 	return res;
 }
 
diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index b40c2ce4c..4cae463e8 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -118,8 +118,18 @@ int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs);
 */
 extern int ast_safe_system(const char *s);
 
-/*! Send DTMF to chan (optionally entertain peer)   */
-int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, char *digits, int between);
+/*!
+  \brief Send DTMF to a channel
+
+  \param chan    The channel that will receive the DTMF frames
+  \param peer    (optional) Peer channel that will be autoserviced while the primary
+                 channel is receiving DTMF
+  \param digits  This is a string of characters representing the DTMF digits to be sent
+                 to the channel.  Valid characters are "0123456789*#abcdABCD".
+  \param between This is the number of milliseconds to wait in between each DTMF digit.
+                 If zero milliseconds is specified, then the default value of 100 will be used.
+*/
+int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between);
 
 /*! Stream a filename (or file descriptor) as a generator. */
 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);