Merged revisions 329528 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/10

................
  r329528 | jrose | 2011-07-26 08:52:34 -0500 (Tue, 26 Jul 2011) | 24 lines
  
  Merged revisions 329527 via svnmerge from 
  https://origsvn.digium.com/svn/asterisk/branches/1.8
  
  ........
    r329527 | jrose | 2011-07-26 08:25:35 -0500 (Tue, 26 Jul 2011) | 17 lines
    
    Fixes some voicemail forwarding behavior based around prepend mode.
    
    Formerly, prepend forwarding would have the user record a message with no useful prompt
    and an expectation for the user to push a button on the phone when finished recording.
    If a length of silence was detected instead, the recording would be canceled and the user
    would re-enter the voicemail forwarding menu. Subsequent time-outs in prepend recording
    would also bug out in the sense that they would write over the original message and get
    sent to the recipient regardless of whether they timed out or were accepted. This patch
    fixes this issue and adds a prompt which will be played after a timeout informing the
    user that they needed to press a button. Currently, the sound files that we have are
    somewhat inadquate for this, so after the call we simply have Allison say "Please try
    again. Then press pound." which actually relies on two separate sound files. Just one
    would be more appropriate.
    
    reporter: Vlad Povorozniuc
    Review: https://reviewboard.asterisk.org/r/1327/ 
  ........
................


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

1 files changed, 58 insertions, 8 deletions

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 850afcd83..fe74e0bdd 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -270,18 +270,68 @@ int ast_control_streamfile(struct ast_channel *chan, const char *file, const cha
 /*! \brief Play a stream and wait for a digit, returning the digit that was pressed */
 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
 
+/*!
+ * \brief Record a file based on input from a channel
+ *        This function will play "auth-thankyou" upon successful recording.
+ *
+ * \param chan the channel being recorded
+ * \param playfile Filename of sound to play before recording begins
+ * \param recordfile Filename to save the recording
+ * \param maxtime_sec Longest possible message length in seconds
+ * \param fmt string containing all formats to be recorded delimited by '|'
+ * \param duration pointer to integer for storing length of the recording
+ * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
+ * \param maxsilence_ms Length of time in milliseconds which will trigger a timeout from silence, -1 for default
+ * \param path Optional filesystem path to unlock
+ * \param acceptdtmf Character of DTMF to end and accept the recording
+ * \param canceldtmf Character of DTMF to end and cancel the recording
+ *
+ * \retval -1 failure or hangup
+ * \retval 'S' Recording ended from silence timeout
+ * \retval 't' Recording ended from the message exceeding the maximum duration
+ * \retval dtmfchar Recording ended via the return value's DTMF character for either cancel or accept.
+ */
 int ast_play_and_record_full(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf);
 
-/*! \brief Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum
- \n
- permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
-     calls ast_unlock_path() on 'path' if passed */
+/*!
+ * \brief Record a file based on input from a channel. Use default accept and cancel DTMF.
+ *        This function will play "auth-thankyou" upon successful recording.
+ *
+ * \param chan the channel being recorded
+ * \param playfile Filename of sound to play before recording begins
+ * \param recordfile Filename to save the recording
+ * \param maxtime_sec Longest possible message length in seconds
+ * \param fmt string containing all formats to be recorded delimited by '|'
+ * \param duration pointer to integer for storing length of the recording
+ * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
+ * \param maxsilence_ms length of time in milliseconds which will trigger a timeout from silence, -1 for default
+ * \param path Optional filesystem path to unlock
+ *
+ * \retval -1 failure or hangup
+ * \retval 'S' Recording ended from silence timeout
+ * \retval 't' Recording ended from the message exceeding the maximum duration
+ * \retval dtmfchar Recording ended via the return value's DTMF character for either cancel or accept.
+ */
 int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
 
-/*! \brief Record a message and prepend the message to the given record file after
-    playing the optional playfile (or a beep), storing the duration in
-    'duration' and with a maximum permitted silence time in milliseconds of 'maxsilence' under
-    'silencethreshold' or use '-1' for either or both parameters for defaults. */
+/*!
+ * \brief Record a file based on input frm a channel. Recording is performed in 'prepend' mode which works a little differently from normal recordings
+ *        This function will not play a success message due to post-recording control in the application this was added for.
+ *
+ * \param chan the channel being recorded
+ * \param playfile Filename of sound to play before recording begins
+ * \param recordfile Filename to save the recording
+ * \param maxtime_sec Longest possible message length in seconds
+ * \param fmt string containing all formats to be recorded delimited by '|'
+ * \param duration pointer to integer for storing length of the recording
+ * \param beep whether to play a beep to prompt the recording
+ * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
+ * \param maxsilence_ms length of time in milliseconds which will trigger a timeout from silence, -1 for default.
+ *
+ * \retval -1 failure or hangup
+ * \retval 'S' Recording ended from silence timeout
+ * \retval 't' Recording either exceeded maximum duration or the call was ended via DTMF
+ */
 int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
 
 enum ast_getdata_result {