This patch adds support for controlling a playback operation from the

Asterisk REST interface.

This adds the /playback/{playbackId}/control resource, which may be
POSTed to to pause, unpause, reverse, forward or restart the media
playback.

Attempts to control a playback that is not currently playing will
either return a 404 Not Found (because the playback object no longer
exists) or a 409 Conflict (because the playback object is still in the
queue to be played).

This patch also adds skipms and offsetms parameters to the
/channels/{channelId}/play resource.

(closes issue ASTERISK-21587)
Review: https://reviewboard.asterisk.org/r/2559


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

4 files changed, 64 insertions, 13 deletions

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 2089bced9..6cfb38004 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -653,6 +653,17 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in
 int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms);
 
 /*!
+ * \brief Version of ast_control_streamfile() which allows the language of the
+ * media file to be specified.
+ *
+ * \retval 0 on success
+ * \retval Non-zero on failure
+ */
+int ast_control_streamfile_lang(struct ast_channel *chan, const char *file,
+	const char *fwd, const char *rev, const char *stop, const char *suspend,
+	const char *restart, int skipms, const char *lang, long *offsetms);
+
+/*!
  * \brief Stream a file with fast forward, pause, reverse, restart.
  * \param chan
  * \param file filename
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 91373cfbd..b27183e7c 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -1203,7 +1203,7 @@ int ast_queue_hangup(struct ast_channel *chan);
 int ast_queue_hangup_with_cause(struct ast_channel *chan, int cause);
 
 /*!
- * \brief Queue a control frame with payload
+ * \brief Queue a control frame without payload
  *
  * \param chan channel to queue frame onto
  * \param control type of control frame
diff --git a/include/asterisk/stasis_app.h b/include/asterisk/stasis_app.h
index 8d3fb097c..27b3502f3 100644
--- a/include/asterisk/stasis_app.h
+++ b/include/asterisk/stasis_app.h
@@ -175,6 +175,18 @@ void stasis_app_control_publish(
 	struct stasis_app_control *control, struct stasis_message *message);
 
 /*!
+ * \brief Queue a control frame without payload.
+ *
+ * \param control Control to publish to.
+ * \param frame_type type of control frame.
+ *
+ * \return zero on success
+ * \return non-zero on failure
+ */
+int stasis_app_control_queue_control(struct stasis_app_control *control,
+	enum ast_control_frame_type frame_type);
+
+/*!
  * \brief Increment the res_stasis reference count.
  *
  * This ensures graceful shutdown happens in the proper order.
diff --git a/include/asterisk/stasis_app_playback.h b/include/asterisk/stasis_app_playback.h
index 598c6be59..59c2aab49 100644
--- a/include/asterisk/stasis_app_playback.h
+++ b/include/asterisk/stasis_app_playback.h
@@ -39,18 +39,34 @@ enum stasis_app_playback_state {
 	STASIS_PLAYBACK_STATE_QUEUED,
 	/*! The media is currently playing */
 	STASIS_PLAYBACK_STATE_PLAYING,
+	/*! The media is currently playing */
+	STASIS_PLAYBACK_STATE_PAUSED,
 	/*! The media has stopped playing */
 	STASIS_PLAYBACK_STATE_COMPLETE,
+	/*! The playback was canceled. */
+	STASIS_PLAYBACK_STATE_CANCELED,
+	/*! The playback was stopped. */
+	STASIS_PLAYBACK_STATE_STOPPED,
+	/*! Enum end sentinel. */
+	STASIS_PLAYBACK_STATE_MAX,
 };
 
-enum stasis_app_playback_media_control {
+/*! Valid operation for controlling a playback. */
+enum stasis_app_playback_media_operation {
+	/*! Stop the playback operation. */
 	STASIS_PLAYBACK_STOP,
+	/*! Restart the media from the beginning. */
+	STASIS_PLAYBACK_RESTART,
+	/*! Pause playback. */
 	STASIS_PLAYBACK_PAUSE,
-	STASIS_PLAYBACK_PLAY,
-	STASIS_PLAYBACK_REWIND,
-	STASIS_PLAYBACK_FAST_FORWARD,
-	STASIS_PLAYBACK_SPEED_UP,
-	STASIS_PLAYBACK_SLOW_DOWN,
+	/*! Resume paused playback. */
+	STASIS_PLAYBACK_UNPAUSE,
+	/*! Rewind playback. */
+	STASIS_PLAYBACK_REVERSE,
+	/*! Fast forward playback. */
+	STASIS_PLAYBACK_FORWARD,
+	/*! Enum end sentinel. */
+	STASIS_PLAYBACK_MEDIA_OP_MAX,
 };
 
 /*!
@@ -62,12 +78,15 @@ enum stasis_app_playback_media_control {
  *
  * \param control Control for \c res_stasis.
  * \param file Base filename for the file to play.
+ * \param language Selects the file based on language.
+ * \param skipms Number of milliseconds to skip for forward/reverse operations.
+ * \param offsetms Number of milliseconds to skip before playing.
  * \return Playback control object.
  * \return \c NULL on error.
  */
 struct stasis_app_playback *stasis_app_control_play_uri(
 	struct stasis_app_control *control, const char *file,
-	const char *language);
+	const char *language, int skipms, long offsetms);
 
 /*!
  * \brief Gets the current state of a playback operation.
@@ -95,18 +114,27 @@ const char *stasis_app_playback_get_id(
  * \return Associated \ref stasis_app_playback object.
  * \return \c NULL if \a id not found.
  */
-struct ast_json *stasis_app_playback_find_by_id(const char *id);
+struct stasis_app_playback *stasis_app_playback_find_by_id(const char *id);
+
+struct ast_json *stasis_app_playback_to_json(
+	const struct stasis_app_playback *playback);
 
+enum stasis_playback_oper_results {
+	STASIS_PLAYBACK_OPER_OK,
+	STASIS_PLAYBACK_OPER_FAILED,
+	STASIS_PLAYBACK_OPER_NOT_PLAYING,
+};
 /*!
  * \brief Controls the media for a given playback operation.
  *
  * \param playback Playback control object.
  * \param control Media control operation.
- * \return 0 on success
- * \return non-zero on error.
+ * \return \c STASIS_PLAYBACK_OPER_OK on success.
+ * \return \ref stasis_playback_oper_results indicating failure.
  */
-int stasis_app_playback_control(struct stasis_app_playback *playback,
-	enum stasis_app_playback_media_control control);
+enum stasis_playback_oper_results stasis_app_playback_operation(
+	struct stasis_app_playback *playback,
+	enum stasis_app_playback_media_operation operation);
 
 /*!
  * \brief Message type for playback updates. The data is an