ari: Add a copy operation for stored recordings
[asterisk/asterisk.git] / include / asterisk / stasis_app_recording.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_RECORDING_H
20 #define _ASTERISK_STASIS_APP_RECORDING_H
21
22 /*! \file
23  *
24  * \brief Stasis Application Recording 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/app.h"
32 #include "asterisk/stasis_app.h"
33
34 /*! @{ */
35
36 /*! \brief Structure representing a recording stored on disk */
37 struct stasis_app_stored_recording;
38
39 /*!
40  * \brief Returns the filename for this recording, for use with streamfile.
41  *
42  * The returned string will be valid until the \a recording object is freed.
43  *
44  * \param recording Recording to query.
45  * \return Absolute path to the recording file, without the extension.
46  * \return \c NULL on error.
47  */
48 const char *stasis_app_stored_recording_get_file(
49         struct stasis_app_stored_recording *recording);
50
51 /*!
52  * \brief Convert stored recording info to JSON.
53  *
54  * \param recording Recording to convert.
55  * \return JSON representation.
56  * \return \c NULL on error.
57  */
58 struct ast_json *stasis_app_stored_recording_to_json(
59         struct stasis_app_stored_recording *recording);
60
61 /*!
62  * \brief Find all stored recordings on disk.
63  *
64  * \return Container of \ref stasis_app_stored_recording objects.
65  * \return \c NULL on error.
66  */
67 struct ao2_container *stasis_app_stored_recording_find_all(void);
68
69 /*!
70  * \brief Creates a stored recording object, with the given name.
71  *
72  * \param name Name of the recording.
73  * \return New recording object.
74  * \return \c NULL if recording is not found. \c errno is set to indicate why
75  *      - \c ENOMEM - out of memeory
76  *      - \c EACCES - file permissions (or recording is outside the config dir)
77  *      - Any of the error codes for stat(), opendir(), readdir()
78  */
79 struct stasis_app_stored_recording *stasis_app_stored_recording_find_by_name(
80         const char *name);
81
82 /*!
83  * \brief Copy a recording.
84  *
85  * \param src_recording The recording to copy
86  * \param dst The destination of the recording to make
87  * \param dst_recording If successful, the stored recording created as a result of the copy
88  *
89  * \retval 0 on success
90  * \retval Non-zero on error
91  */
92 int stasis_app_stored_recording_copy(struct stasis_app_stored_recording *src_recording, const char *dst,
93         struct stasis_app_stored_recording **dst_recording);
94
95 /*!
96  * \brief Delete a recording from disk.
97  *
98  * \param recording Recording to delete.
99  * \return 0 on success.
100  * \return Non-zero on error.
101  */
102 int stasis_app_stored_recording_delete(
103         struct stasis_app_stored_recording *recording);
104
105 /*! @} */
106
107 /*! @{ */
108
109 /*! Opaque struct for handling the recording of media to a file. */
110 struct stasis_app_recording;
111
112 /*! State of a recording operation */
113 enum stasis_app_recording_state {
114         /*! The recording has not started yet */
115         STASIS_APP_RECORDING_STATE_QUEUED,
116         /*! The media is currently recording */
117         STASIS_APP_RECORDING_STATE_RECORDING,
118         /*! The media is currently paused */
119         STASIS_APP_RECORDING_STATE_PAUSED,
120         /*! The media has stopped recording */
121         STASIS_APP_RECORDING_STATE_COMPLETE,
122         /*! The media has stopped recording, with error */
123         STASIS_APP_RECORDING_STATE_FAILED,
124         /*! The media has stopped recording, discard the recording file */
125         STASIS_APP_RECORDING_STATE_CANCELED,
126         /*! Sentinel */
127         STASIS_APP_RECORDING_STATE_MAX,
128 };
129
130 /*! Valid operation for controlling a recording. */
131 enum stasis_app_recording_media_operation {
132         /*! Stop the recording, deleting the media file(s) */
133         STASIS_APP_RECORDING_CANCEL,
134         /*! Stop the recording. */
135         STASIS_APP_RECORDING_STOP,
136         /*! Pause the recording */
137         STASIS_APP_RECORDING_PAUSE,
138         /*! Unpause the recording */
139         STASIS_APP_RECORDING_UNPAUSE,
140         /*! Mute the recording (record silence) */
141         STASIS_APP_RECORDING_MUTE,
142         /*! Unmute the recording */
143         STASIS_APP_RECORDING_UNMUTE,
144         /*! Sentinel */
145         STASIS_APP_RECORDING_OPER_MAX,
146 };
147
148 #define STASIS_APP_RECORDING_TERMINATE_INVALID 0
149 #define STASIS_APP_RECORDING_TERMINATE_NONE -1
150 #define STASIS_APP_RECORDING_TERMINATE_ANY -2
151
152 struct stasis_app_recording_options {
153         AST_DECLARE_STRING_FIELDS(
154                 AST_STRING_FIELD(name); /*!< name Name of the recording. */
155                 AST_STRING_FIELD(format);       /*!< Format to be recorded (wav, gsm, etc.) */
156                 AST_STRING_FIELD(target); /*!< URI of what is being recorded */
157                 );
158         /*! Number of seconds of silence before ending the recording. */
159         int max_silence_seconds;
160         /*! Maximum recording duration. 0 for no maximum. */
161         int max_duration_seconds;
162         /*! Which DTMF to use to terminate the recording
163          *  \c STASIS_APP_RECORDING_TERMINATE_NONE to terminate only on hangup
164          *  \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF
165          */
166         char terminate_on;
167         /*! How to handle recording when a file already exists */
168         enum ast_record_if_exists if_exists;
169         /*! If true, a beep is played at the start of recording */
170         int beep:1;
171 };
172
173 /*!
174  * \brief Allocate a recording options object.
175  *
176  * Clean up with ao2_cleanup().
177  *
178  * \param name Name of the recording.
179  * \param format Format to record in.
180  * \return Newly allocated options object.
181  * \return \c NULL on error.
182  */
183 struct stasis_app_recording_options *stasis_app_recording_options_create(
184         const char *name, const char *format);
185
186 /*!
187  * \brief Parse a string into the recording termination enum.
188  *
189  * \param str String to parse.
190  * \return DTMF value to terminate on.
191  * \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
192  * \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
193  * \return \c STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
194  */
195 char stasis_app_recording_termination_parse(const char *str);
196
197 /*!
198  * \brief Parse a string into the if_exists enum.
199  *
200  * \param str String to parse.
201  * \return How to handle an existing file.
202  * \return -1 on error.
203  */
204 enum ast_record_if_exists stasis_app_recording_if_exists_parse(
205         const char *str);
206
207 /*!
208  * \brief Record media from a channel.
209  *
210  * A reference to the \a options object may be kept, so it MUST NOT be modified
211  * after calling this function.
212  *
213  * On error, \c errno is set to indicate the failure reason.
214  *  - \c EINVAL: Invalid input.
215  *  - \c EEXIST: A recording with that name is in session.
216  *  - \c ENOMEM: Out of memory.
217  *
218  * \param control Control for \c res_stasis.
219  * \param options Recording options.
220  * \return Recording control object.
221  * \return \c NULL on error.
222  */
223 struct stasis_app_recording *stasis_app_control_record(
224         struct stasis_app_control *control,
225         struct stasis_app_recording_options *options);
226
227 /*!
228  * \brief Gets the current state of a recording operation.
229  *
230  * \param recording Recording control object.
231  * \return The state of the \a recording object.
232  */
233 enum stasis_app_recording_state stasis_app_recording_get_state(
234         struct stasis_app_recording *recording);
235
236 /*!
237  * \brief Gets the unique name of a recording object.
238  *
239  * \param recording Recording control object.
240  * \return \a recording's name.
241  * \return \c NULL if \a recording ic \c NULL
242  */
243 const char *stasis_app_recording_get_name(
244         struct stasis_app_recording *recording);
245
246 /*!
247  * \brief Finds the recording object with the given name.
248  *
249  * \param name Name of the recording object to find.
250  * \return Associated \ref stasis_app_recording object.
251  * \return \c NULL if \a name not found.
252  */
253 struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name);
254
255 /*!
256  * \brief Construct a JSON model of a recording.
257  *
258  * \param recording Recording to conver.
259  * \return JSON model.
260  * \return \c NULL on error.
261  */
262 struct ast_json *stasis_app_recording_to_json(
263         const struct stasis_app_recording *recording);
264
265 /*!
266  * \brief Possible results from a recording operation.
267  */
268 enum stasis_app_recording_oper_results {
269         /*! Operation completed successfully. */
270         STASIS_APP_RECORDING_OPER_OK,
271         /*! Operation failed. */
272         STASIS_APP_RECORDING_OPER_FAILED,
273         /*! Operation failed b/c recording is not in session. */
274         STASIS_APP_RECORDING_OPER_NOT_RECORDING,
275 };
276
277 /*!
278  * \brief Controls the media for a given recording operation.
279  *
280  * \param recording Recording control object.
281  * \param control Media control operation.
282  * \return \c STASIS_APP_RECORDING_OPER_OK on success.
283  * \return \ref stasis_app_recording_oper_results indicating failure.
284  */
285 enum stasis_app_recording_oper_results stasis_app_recording_operation(
286         struct stasis_app_recording *recording,
287         enum stasis_app_recording_media_operation operation);
288
289 /*!
290  * \brief Message type for recording updates. The data is an
291  * \ref ast_channel_blob.
292  */
293 struct stasis_message_type *stasis_app_recording_snapshot_type(void);
294
295 /*! @} */
296
297 #endif /* _ASTERISK_STASIS_APP_RECORDING_H */