f67c204ef67dd92dfc7595af5b64f0c7b27940e8
[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 Delete a recording from disk.
84  *
85  * \param recording Recording to delete.
86  * \return 0 on success.
87  * \return Non-zero on error.
88  */
89 int stasis_app_stored_recording_delete(
90         struct stasis_app_stored_recording *recording);
91
92 /*! @} */
93
94 /*! @{ */
95
96 /*! Opaque struct for handling the recording of media to a file. */
97 struct stasis_app_recording;
98
99 /*! State of a recording operation */
100 enum stasis_app_recording_state {
101         /*! The recording has not started yet */
102         STASIS_APP_RECORDING_STATE_QUEUED,
103         /*! The media is currently recording */
104         STASIS_APP_RECORDING_STATE_RECORDING,
105         /*! The media is currently paused */
106         STASIS_APP_RECORDING_STATE_PAUSED,
107         /*! The media has stopped recording */
108         STASIS_APP_RECORDING_STATE_COMPLETE,
109         /*! The media has stopped recording, with error */
110         STASIS_APP_RECORDING_STATE_FAILED,
111         /*! The media has stopped recording, discard the recording file */
112         STASIS_APP_RECORDING_STATE_CANCELED,
113         /*! Sentinel */
114         STASIS_APP_RECORDING_STATE_MAX,
115 };
116
117 /*! Valid operation for controlling a recording. */
118 enum stasis_app_recording_media_operation {
119         /*! Stop the recording, deleting the media file(s) */
120         STASIS_APP_RECORDING_CANCEL,
121         /*! Stop the recording. */
122         STASIS_APP_RECORDING_STOP,
123         /*! Pause the recording */
124         STASIS_APP_RECORDING_PAUSE,
125         /*! Unpause the recording */
126         STASIS_APP_RECORDING_UNPAUSE,
127         /*! Mute the recording (record silence) */
128         STASIS_APP_RECORDING_MUTE,
129         /*! Unmute the recording */
130         STASIS_APP_RECORDING_UNMUTE,
131         /*! Sentinel */
132         STASIS_APP_RECORDING_OPER_MAX,
133 };
134
135 #define STASIS_APP_RECORDING_TERMINATE_INVALID 0
136 #define STASIS_APP_RECORDING_TERMINATE_NONE -1
137 #define STASIS_APP_RECORDING_TERMINATE_ANY -2
138
139 struct stasis_app_recording_options {
140         AST_DECLARE_STRING_FIELDS(
141                 AST_STRING_FIELD(name); /*!< name Name of the recording. */
142                 AST_STRING_FIELD(format);       /*!< Format to be recorded (wav, gsm, etc.) */
143                 AST_STRING_FIELD(target); /*!< URI of what is being recorded */
144                 );
145         /*! Number of seconds of silence before ending the recording. */
146         int max_silence_seconds;
147         /*! Maximum recording duration. 0 for no maximum. */
148         int max_duration_seconds;
149         /*! Which DTMF to use to terminate the recording
150          *  \c STASIS_APP_RECORDING_TERMINATE_NONE to terminate only on hangup
151          *  \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF
152          */
153         char terminate_on;
154         /*! How to handle recording when a file already exists */
155         enum ast_record_if_exists if_exists;
156         /*! If true, a beep is played at the start of recording */
157         int beep:1;
158 };
159
160 /*!
161  * \brief Allocate a recording options object.
162  *
163  * Clean up with ao2_cleanup().
164  *
165  * \param name Name of the recording.
166  * \param format Format to record in.
167  * \return Newly allocated options object.
168  * \return \c NULL on error.
169  */
170 struct stasis_app_recording_options *stasis_app_recording_options_create(
171         const char *name, const char *format);
172
173 /*!
174  * \brief Parse a string into the recording termination enum.
175  *
176  * \param str String to parse.
177  * \return DTMF value to terminate on.
178  * \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
179  * \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
180  * \return \c STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
181  */
182 char stasis_app_recording_termination_parse(const char *str);
183
184 /*!
185  * \brief Parse a string into the if_exists enum.
186  *
187  * \param str String to parse.
188  * \return How to handle an existing file.
189  * \return -1 on error.
190  */
191 enum ast_record_if_exists stasis_app_recording_if_exists_parse(
192         const char *str);
193
194 /*!
195  * \brief Record media from a channel.
196  *
197  * A reference to the \a options object may be kept, so it MUST NOT be modified
198  * after calling this function.
199  *
200  * On error, \c errno is set to indicate the failure reason.
201  *  - \c EINVAL: Invalid input.
202  *  - \c EEXIST: A recording with that name is in session.
203  *  - \c ENOMEM: Out of memory.
204  *
205  * \param control Control for \c res_stasis.
206  * \param options Recording options.
207  * \return Recording control object.
208  * \return \c NULL on error.
209  */
210 struct stasis_app_recording *stasis_app_control_record(
211         struct stasis_app_control *control,
212         struct stasis_app_recording_options *options);
213
214 /*!
215  * \brief Gets the current state of a recording operation.
216  *
217  * \param recording Recording control object.
218  * \return The state of the \a recording object.
219  */
220 enum stasis_app_recording_state stasis_app_recording_get_state(
221         struct stasis_app_recording *recording);
222
223 /*!
224  * \brief Gets the unique name of a recording object.
225  *
226  * \param recording Recording control object.
227  * \return \a recording's name.
228  * \return \c NULL if \a recording ic \c NULL
229  */
230 const char *stasis_app_recording_get_name(
231         struct stasis_app_recording *recording);
232
233 /*!
234  * \brief Finds the recording object with the given name.
235  *
236  * \param name Name of the recording object to find.
237  * \return Associated \ref stasis_app_recording object.
238  * \return \c NULL if \a name not found.
239  */
240 struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name);
241
242 /*!
243  * \brief Construct a JSON model of a recording.
244  *
245  * \param recording Recording to conver.
246  * \return JSON model.
247  * \return \c NULL on error.
248  */
249 struct ast_json *stasis_app_recording_to_json(
250         const struct stasis_app_recording *recording);
251
252 /*!
253  * \brief Possible results from a recording operation.
254  */
255 enum stasis_app_recording_oper_results {
256         /*! Operation completed successfully. */
257         STASIS_APP_RECORDING_OPER_OK,
258         /*! Operation failed. */
259         STASIS_APP_RECORDING_OPER_FAILED,
260         /*! Operation failed b/c recording is not in session. */
261         STASIS_APP_RECORDING_OPER_NOT_RECORDING,
262 };
263
264 /*!
265  * \brief Controls the media for a given recording operation.
266  *
267  * \param recording Recording control object.
268  * \param control Media control operation.
269  * \return \c STASIS_APP_RECORDING_OPER_OK on success.
270  * \return \ref stasis_app_recording_oper_results indicating failure.
271  */
272 enum stasis_app_recording_oper_results stasis_app_recording_operation(
273         struct stasis_app_recording *recording,
274         enum stasis_app_recording_media_operation operation);
275
276 /*!
277  * \brief Message type for recording updates. The data is an
278  * \ref ast_channel_blob.
279  */
280 struct stasis_message_type *stasis_app_recording_snapshot_type(void);
281
282 /*! @} */
283
284 #endif /* _ASTERISK_STASIS_APP_RECORDING_H */