diff options
author | David M. Lee <dlee@digium.com> | 2013-05-23 20:11:35 +0000 |
---|---|---|
committer | David M. Lee <dlee@digium.com> | 2013-05-23 20:11:35 +0000 |
commit | 10ba6bf8a8114278ca974861ecebcb3a827d8d5b (patch) | |
tree | 1406ede124cf9665cb9f9244f9339b6cb522aa8b /include | |
parent | 3464e0919afe398717b93b20fff37560c6d4478f (diff) |
This patch implements the REST API's for POST /channels/{channelId}/play
and GET /playback/{playbackId}.
This allows an external application to initiate playback of a sound on a
channel while the channel is in the Stasis application.
/play commands are issued asynchronously, and return immediately with
the URL of the associated /playback resource. Playback commands queue up,
playing in succession. The /playback resource shows the state of a
playback operation as enqueued, playing or complete. (Although the
operation will only be in the 'complete' state for a very short time,
since it is almost immediately freed up).
(closes issue ASTERISK-21283)
(closes issue ASTERISK-21586)
Review: https://reviewboard.asterisk.org/r/2531/
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@389587 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/app.h | 11 | ||||
-rw-r--r-- | include/asterisk/stasis_app_playback.h | 117 | ||||
-rw-r--r-- | include/asterisk/stasis_channels.h | 37 | ||||
-rw-r--r-- | include/asterisk/stasis_http.h | 6 |
4 files changed, 168 insertions, 3 deletions
diff --git a/include/asterisk/app.h b/include/asterisk/app.h index 75d1fbb7e..2089bced9 100644 --- a/include/asterisk/app.h +++ b/include/asterisk/app.h @@ -636,14 +636,19 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in /*! * \brief Stream a file with fast forward, pause, reverse, restart. - * \param chan - * \param file filename - * \param fwd, rev, stop, pause, restart, skipms, offsetms + * \param chan Channel + * \param file File to play. + * \param fwd, rev, stop, pause, restart DTMF keys for media control + * \param skipms Number of milliseconds to skip for fwd/rev. + * \param offsetms Number of milliseconds to skip when starting the media. * * Before calling this function, set this to be the number * of ms to start from the beginning of the file. When the function * returns, it will be the number of ms from the beginning where the * playback stopped. Pass NULL if you don't care. + * + * \retval 0 on success + * \retval Non-zero on failure */ 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); diff --git a/include/asterisk/stasis_app_playback.h b/include/asterisk/stasis_app_playback.h new file mode 100644 index 000000000..598c6be59 --- /dev/null +++ b/include/asterisk/stasis_app_playback.h @@ -0,0 +1,117 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2013, Digium, Inc. + * + * David M. Lee, II <dlee@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +#ifndef _ASTERISK_STASIS_APP_PLAYBACK_H +#define _ASTERISK_STASIS_APP_PLAYBACK_H + +/*! \file + * + * \brief Stasis Application Playback API. See \ref res_stasis "Stasis + * Application API" for detailed documentation. + * + * \author David M. Lee, II <dlee@digium.com> + * \since 12 + */ + +#include "asterisk/stasis_app.h" + +/*! Opaque struct for handling the playback of a single file */ +struct stasis_app_playback; + +/*! State of a playback operation */ +enum stasis_app_playback_state { + /*! The playback has not started yet */ + STASIS_PLAYBACK_STATE_QUEUED, + /*! The media is currently playing */ + STASIS_PLAYBACK_STATE_PLAYING, + /*! The media has stopped playing */ + STASIS_PLAYBACK_STATE_COMPLETE, +}; + +enum stasis_app_playback_media_control { + STASIS_PLAYBACK_STOP, + STASIS_PLAYBACK_PAUSE, + STASIS_PLAYBACK_PLAY, + STASIS_PLAYBACK_REWIND, + STASIS_PLAYBACK_FAST_FORWARD, + STASIS_PLAYBACK_SPEED_UP, + STASIS_PLAYBACK_SLOW_DOWN, +}; + +/*! + * \brief Play a file to the control's channel. + * + * Note that the file isn't the full path to the file. Asterisk's internal + * playback mechanism will automagically select the best format based on the + * available codecs for the channel. + * + * \param control Control for \c res_stasis. + * \param file Base filename for the file to play. + * \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); + +/*! + * \brief Gets the current state of a playback operation. + * + * \param playback Playback control object. + * \return The state of the \a playback object. + */ +enum stasis_app_playback_state stasis_app_playback_get_state( + struct stasis_app_playback *playback); + +/*! + * \brief Gets the unique id of a playback object. + * + * \param playback Playback control object. + * \return \a playback's id. + * \return \c NULL if \a playback ic \c NULL + */ +const char *stasis_app_playback_get_id( + struct stasis_app_playback *playback); + +/*! + * \brief Finds the playback object with the given id. + * + * \param id Id of the playback object to find. + * \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); + +/*! + * \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. + */ +int stasis_app_playback_control(struct stasis_app_playback *playback, + enum stasis_app_playback_media_control control); + +/*! + * \brief Message type for playback updates. The data is an + * \ref ast_channel_blob. + */ +struct stasis_message_type *stasis_app_playback_snapshot_type(void); + +#endif /* _ASTERISK_STASIS_APP_PLAYBACK_H */ diff --git a/include/asterisk/stasis_channels.h b/include/asterisk/stasis_channels.h index 5ead93d3a..dace99af5 100644 --- a/include/asterisk/stasis_channels.h +++ b/include/asterisk/stasis_channels.h @@ -54,6 +54,7 @@ struct ast_channel_snapshot { AST_STRING_FIELD(caller_number); /*!< Caller ID Number */ AST_STRING_FIELD(connected_name); /*!< Connected Line Name */ AST_STRING_FIELD(connected_number); /*!< Connected Line Number */ + AST_STRING_FIELD(language); /*!< The default spoken language for the channel */ ); struct timeval creationtime; /*!< The time of channel creation */ @@ -124,6 +125,17 @@ struct ast_channel_snapshot *ast_channel_snapshot_create( /*! * \since 12 + * \brief Get the most recent snapshot for channel with the given \a uniqueid. + * + * \param uniqueid Uniqueid of the snapshot to fetch. + * \return Most recent channel snapshot + * \return \c NULL on error + */ +struct ast_channel_snapshot *ast_channel_snapshot_get_latest( + const char *uniqueid); + +/*! + * \since 12 * \brief Creates a \ref ast_channel_blob message. * * The given \a blob should be treated as immutable and not modified after it is @@ -142,6 +154,23 @@ struct stasis_message *ast_channel_blob_create(struct ast_channel *chan, /*! * \since 12 + * \brief Create a \ref ast_channel_blob message, pulling channel state from + * the cache. + * + * \param uniqueid Uniqueid of the channel. + * \param type Message type for this blob. + * \param blob JSON object representing the data, or \c NULL for no data. If + * \c NULL, ast_json_null() is put into the object. + * + * \return \ref ast_channel_blob message. + * \return \c NULL on error + */ +struct stasis_message *ast_channel_blob_create_from_cache( + const char *uniqueid, struct stasis_message_type *type, + struct ast_json *blob); + +/*! + * \since 12 * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message. * * The given \a blob should be treated as immutable and not modified after it is @@ -223,6 +252,14 @@ void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj, /*! * \since 12 + * \brief Publish a \ref ast_channel_snapshot for a channel. + * + * \param chan Channel to publish. + */ +void ast_channel_publish_snapshot(struct ast_channel *chan); + +/*! + * \since 12 * \brief Publish a \ref ast_channel_varset for a channel. * * \param chan Channel to pulish the event for, or \c NULL for 'none'. diff --git a/include/asterisk/stasis_http.h b/include/asterisk/stasis_http.h index cc0ceeee4..f81a206e6 100644 --- a/include/asterisk/stasis_http.h +++ b/include/asterisk/stasis_http.h @@ -163,6 +163,12 @@ void stasis_http_response_ok(struct stasis_http_response *response, void stasis_http_response_no_content(struct stasis_http_response *response); /*! + * \brief Fill in a <tt>Created</tt> (201) \a stasis_http_response. + */ +void stasis_http_response_created(struct stasis_http_response *response, + const char *url); + +/*! * \brief Fill in \a response with a 500 message for allocation failures. * \param response Response to fill in. */ |