Asterisk - The Open Source Telephony Project  21.4.1
stasis_app_playback.h
Go to the documentation of this file.
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 */
38  /*! The playback has not started yet */
40  /*! The media is currently playing */
42  /*! The media is currently playing */
44  /*! The media is transitioning to the next in the list */
46  /*! The media has stopped playing */
48  /*! The media has stopped because of an error playing the file */
50  /*! The playback was canceled. */
52  /*! The playback was stopped. */
54  /*! Enum end sentinel. */
56 };
57 
58 /*! Valid operation for controlling a playback. */
60  /*! Stop the playback operation. */
62  /*! Restart the media from the beginning. */
64  /*! Pause playback. */
66  /*! Resume paused playback. */
68  /*! Rewind playback. */
70  /*! Fast forward playback. */
72  /*! Enum end sentinel. */
74 };
75 
77  /*! The target is a channel */
79  /*! The target is a bridge */
81 };
82 
83 /*!
84  * \brief Play a file to the control's channel.
85  *
86  * Note that the file isn't the full path to the file. Asterisk's internal
87  * playback mechanism will automagically select the best format based on the
88  * available codecs for the channel.
89  *
90  * \param control Control for \c res_stasis.
91  * \param media Array of const char * media files to play.
92  * \param media_count The number of media files in \c media.
93  * \param language Selects the file based on language.
94  * \param target_id ID of the target bridge or channel.
95  * \param target_type What the target type is
96  * \param skipms Number of milliseconds to skip for forward/reverse operations.
97  * \param offsetms Number of milliseconds to skip before playing.
98  * \param id ID to assign the new playback or NULL for default.
99  * \return Playback control object.
100  * \retval NULL on error.
101  */
103  struct stasis_app_control *control, const char **media,
104  size_t media_count, const char *language, const char *target_id,
105  enum stasis_app_playback_target_type target_type,
106  int skipms, long offsetms, const char *id);
107 
108 /*!
109  * \brief Gets the current state of a playback operation.
110  *
111  * \param playback Playback control object.
112  * \return The state of the \a playback object.
113  */
115  struct stasis_app_playback *playback);
116 
117 /*!
118  * \brief Gets the unique id of a playback object.
119  *
120  * \param playback Playback control object.
121  * \return \a playback's id.
122  * \retval NULL if \a playback ic \c NULL
123  */
124 const char *stasis_app_playback_get_id(
125  struct stasis_app_playback *playback);
126 
127 /*!
128  * \brief Finds the playback object with the given id.
129  *
130  * \param id Id of the playback object to find.
131  * \return Associated \ref stasis_app_playback object.
132  * \retval NULL if \a id not found.
133  */
135 
136 /*!
137  * \brief Convert a playback to its JSON representation
138  *
139  * \param playback The playback object to convert to JSON
140  *
141  * \retval NULL on error
142  * \return A JSON object on success
143  */
145  const struct stasis_app_playback *playback);
146 
147 enum stasis_playback_oper_results {
148  STASIS_PLAYBACK_OPER_OK,
149  STASIS_PLAYBACK_OPER_FAILED,
150  STASIS_PLAYBACK_OPER_NOT_PLAYING,
151 };
152 /*!
153  * \brief Controls the media for a given playback operation.
154  *
155  * \param playback Playback control object.
156  * \param operation Media control operation.
157  * \retval STASIS_PLAYBACK_OPER_OK on success.
158  * \return \ref stasis_playback_oper_results indicating failure.
159  */
160 enum stasis_playback_oper_results stasis_app_playback_operation(
161  struct stasis_app_playback *playback,
162  enum stasis_app_playback_media_operation operation);
163 
164 /*!
165  * \brief Message type for playback updates. The data is an
166  * \ref ast_channel_blob.
167  */
169 
170 #endif /* _ASTERISK_STASIS_APP_PLAYBACK_H */
enum stasis_playback_oper_results stasis_app_playback_operation(struct stasis_app_playback *playback, enum stasis_app_playback_media_operation operation)
Controls the media for a given playback operation.
stasis_app_playback_target_type
stasis_app_playback_media_operation
struct ast_json * stasis_app_playback_to_json(const struct stasis_app_playback *playback)
Convert a playback to its JSON representation.
struct stasis_app_playback * stasis_app_playback_find_by_id(const char *id)
Finds the playback object with the given id.
struct stasis_app_control * control
const char * stasis_app_playback_get_id(struct stasis_app_playback *playback)
Gets the unique id of a playback object.
const ast_string_field media
enum stasis_app_playback_state stasis_app_playback_get_state(struct stasis_app_playback *playback)
Gets the current state of a playback operation.
struct stasis_message_type * stasis_app_playback_snapshot_type(void)
Message type for playback updates. The data is an ast_channel_blob.
struct stasis_app_playback * stasis_app_control_play_uri(struct stasis_app_control *control, const char **media, size_t media_count, const char *language, const char *target_id, enum stasis_app_playback_target_type target_type, int skipms, long offsetms, const char *id)
Play a file to the control's channel.
stasis_app_playback_state
Abstract JSON element (object, array, string, int, ...).
Stasis Application API. See Stasis Application API for detailed documentation.
const ast_string_field language