ARI: Add recording controls

This patch implements the controls from ARI recordings. The controls
are:

 * DELETE /recordings/live/{recordingName} - stop recording and
   discard it
 * POST /recordings/live/{recordingName}/stop - stop recording
 * POST /recordings/live/{recordingName}/pause - pause recording
 * POST /recordings/live/{recordingName}/unpause - resume recording
 * POST /recordings/live/{recordingName}/mute - mute recording (record
   silence to the file)
 * POST /recordings/live/{recordingName}/unmute - unmute recording.

Since this underlying functionality did not already exist, is was
added to app.c by a set of control frames, similar to how playback
control works. The pause/mute control frames are toggles, even though
the ARI controls are idempotent, to be consistent with the playback
control frames.

(closes issue ASTERISK-22181)
Review: https://reviewboard.asterisk.org/r/2697/


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

3 files changed, 26 insertions, 5 deletions

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 251288546..06b903e2f 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -709,11 +709,12 @@ enum ast_record_if_exists {
  *        skip_confirmation_sound is false.
  *
  * \param chan the channel being recorded
- * \param playfile Filename of sound to play before recording begins
+ * \param playfile Filename of sound to play before recording begins. A beep is also played when playfile completes, before the 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 If true, play a beep before recording begins (and doesn't play \a playfile)
  * \param sound_duration pointer to integer for storing length of the recording minus all silence
  * \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
@@ -728,7 +729,7 @@ enum ast_record_if_exists {
  * \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 *sound_duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf, int skip_confirmation_sound, enum ast_record_if_exists if_exists);
+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 *sound_duration, int beep, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf, int skip_confirmation_sound, enum ast_record_if_exists if_exists);
 
 /*!
  * \brief Record a file based on input from a channel. Use default accept and cancel DTMF.
diff --git a/include/asterisk/frame.h b/include/asterisk/frame.h
index bedc3a25d..1cb7d591f 100644
--- a/include/asterisk/frame.h
+++ b/include/asterisk/frame.h
@@ -278,7 +278,11 @@ enum ast_control_frame_type {
 	AST_CONTROL_STREAM_RESTART = 1002,	/*!< Indicate to a channel in playback to restart the stream */
 	AST_CONTROL_STREAM_REVERSE = 1003,	/*!< Indicate to a channel in playback to rewind */
 	AST_CONTROL_STREAM_FORWARD = 1004,	/*!< Indicate to a channel in playback to fast forward */
-
+	/* Control frames to manipulate recording on a channel. */
+	AST_CONTROL_RECORD_CANCEL = 1100,	/*!< Indicated to a channel in record to stop recording and discard the file */
+	AST_CONTROL_RECORD_STOP = 1101,	/*!< Indicated to a channel in record to stop recording */
+	AST_CONTROL_RECORD_SUSPEND = 1102,	/*!< Indicated to a channel in record to suspend/unsuspend recording */
+	AST_CONTROL_RECORD_MUTE = 1103,	/*!< Indicated to a channel in record to mute/unmute (i.e. write silence) recording */
 };
 
 enum ast_frame_read_action {
diff --git a/include/asterisk/stasis_app_recording.h b/include/asterisk/stasis_app_recording.h
index 9c9930406..e8b4558ab 100644
--- a/include/asterisk/stasis_app_recording.h
+++ b/include/asterisk/stasis_app_recording.h
@@ -44,14 +44,30 @@ enum stasis_app_recording_state {
 	STASIS_APP_RECORDING_STATE_PAUSED,
 	/*! The media has stopped recording */
 	STASIS_APP_RECORDING_STATE_COMPLETE,
-	/*! The media has stopped playing */
+	/*! The media has stopped recording, with error */
 	STASIS_APP_RECORDING_STATE_FAILED,
+	/*! The media has stopped recording, discard the recording file */
+	STASIS_APP_RECORDING_STATE_CANCELED,
+	/*! Sentinel */
+	STASIS_APP_RECORDING_STATE_MAX,
 };
 
 /*! Valid operation for controlling a recording. */
 enum stasis_app_recording_media_operation {
-	/*! Stop the recording operation. */
+	/*! Stop the recording, deleting the media file(s) */
+	STASIS_APP_RECORDING_CANCEL,
+	/*! Stop the recording. */
 	STASIS_APP_RECORDING_STOP,
+	/*! Pause the recording */
+	STASIS_APP_RECORDING_PAUSE,
+	/*! Unpause the recording */
+	STASIS_APP_RECORDING_UNPAUSE,
+	/*! Mute the recording (record silence) */
+	STASIS_APP_RECORDING_MUTE,
+	/*! Unmute the recording */
+	STASIS_APP_RECORDING_UNMUTE,
+	/*! Sentinel */
+	STASIS_APP_RECORDING_OPER_MAX,
 };
 
 #define STASIS_APP_RECORDING_TERMINATE_INVALID 0