598c6be5980a04cae0ce058338ee893d42818052
[asterisk/asterisk.git] / include / asterisk / stasis_app_playback.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _ASTERISK_STASIS_APP_PLAYBACK_H
20 #define _ASTERISK_STASIS_APP_PLAYBACK_H
21
22 /*! \file
23  *
24  * \brief Stasis Application Playback API. See \ref res_stasis "Stasis
25  * Application API" for detailed documentation.
26  *
27  * \author David M. Lee, II <dlee@digium.com>
28  * \since 12
29  */
30
31 #include "asterisk/stasis_app.h"
32
33 /*! Opaque struct for handling the playback of a single file */
34 struct stasis_app_playback;
35
36 /*! State of a playback operation */
37 enum stasis_app_playback_state {
38         /*! The playback has not started yet */
39         STASIS_PLAYBACK_STATE_QUEUED,
40         /*! The media is currently playing */
41         STASIS_PLAYBACK_STATE_PLAYING,
42         /*! The media has stopped playing */
43         STASIS_PLAYBACK_STATE_COMPLETE,
44 };
45
46 enum stasis_app_playback_media_control {
47         STASIS_PLAYBACK_STOP,
48         STASIS_PLAYBACK_PAUSE,
49         STASIS_PLAYBACK_PLAY,
50         STASIS_PLAYBACK_REWIND,
51         STASIS_PLAYBACK_FAST_FORWARD,
52         STASIS_PLAYBACK_SPEED_UP,
53         STASIS_PLAYBACK_SLOW_DOWN,
54 };
55
56 /*!
57  * \brief Play a file to the control's channel.
58  *
59  * Note that the file isn't the full path to the file. Asterisk's internal
60  * playback mechanism will automagically select the best format based on the
61  * available codecs for the channel.
62  *
63  * \param control Control for \c res_stasis.
64  * \param file Base filename for the file to play.
65  * \return Playback control object.
66  * \return \c NULL on error.
67  */
68 struct stasis_app_playback *stasis_app_control_play_uri(
69         struct stasis_app_control *control, const char *file,
70         const char *language);
71
72 /*!
73  * \brief Gets the current state of a playback operation.
74  *
75  * \param playback Playback control object.
76  * \return The state of the \a playback object.
77  */
78 enum stasis_app_playback_state stasis_app_playback_get_state(
79         struct stasis_app_playback *playback);
80
81 /*!
82  * \brief Gets the unique id of a playback object.
83  *
84  * \param playback Playback control object.
85  * \return \a playback's id.
86  * \return \c NULL if \a playback ic \c NULL
87  */
88 const char *stasis_app_playback_get_id(
89         struct stasis_app_playback *playback);
90
91 /*!
92  * \brief Finds the playback object with the given id.
93  *
94  * \param id Id of the playback object to find.
95  * \return Associated \ref stasis_app_playback object.
96  * \return \c NULL if \a id not found.
97  */
98 struct ast_json *stasis_app_playback_find_by_id(const char *id);
99
100 /*!
101  * \brief Controls the media for a given playback operation.
102  *
103  * \param playback Playback control object.
104  * \param control Media control operation.
105  * \return 0 on success
106  * \return non-zero on error.
107  */
108 int stasis_app_playback_control(struct stasis_app_playback *playback,
109         enum stasis_app_playback_media_control control);
110
111 /*!
112  * \brief Message type for playback updates. The data is an
113  * \ref ast_channel_blob.
114  */
115 struct stasis_message_type *stasis_app_playback_snapshot_type(void);
116
117 #endif /* _ASTERISK_STASIS_APP_PLAYBACK_H */