Asterisk - The Open Source Telephony Project GIT-master-d856a3e
stasis_app_recording.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_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 */
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 * \retval NULL on error.
47 */
49 struct stasis_app_stored_recording *recording);
50
51/*!
52 * \brief Returns the full filename, with extension, for this recording.
53 * \since 14.0.0
54 *
55 * \param recording Recording to query.
56 *
57 * \return Absolute path to the recording file, with the extension.
58 * \retval NULL on error
59 */
61 struct stasis_app_stored_recording *recording);
62
63/*!
64 * \brief Returns the extension for this recording.
65 * \since 14.0.0
66 *
67 * \param recording Recording to query.
68 *
69 * \return The extension associated with this recording.
70 * \retval NULL on error
71 */
73 struct stasis_app_stored_recording *recording);
74
75/*!
76 * \brief Convert stored recording info to JSON.
77 *
78 * \param recording Recording to convert.
79 * \return JSON representation.
80 * \retval NULL on error.
81 */
83 struct stasis_app_stored_recording *recording);
84
85/*!
86 * \brief Find all stored recordings on disk.
87 *
88 * \return Container of \ref stasis_app_stored_recording objects.
89 * \retval NULL on error.
90 */
92
93/*!
94 * \brief Creates a stored recording object, with the given name.
95 *
96 * \param name Name of the recording.
97 * \return New recording object.
98 * \retval NULL if recording is not found. \c errno is set to indicate why
99 * - \c ENOMEM - out of memeory
100 * - \c EACCES - file permissions (or recording is outside the config dir)
101 * - Any of the error codes for stat(), opendir(), readdir()
102 */
104 const char *name);
105
106/*!
107 * \brief Copy a recording.
108 *
109 * \param src_recording The recording to copy
110 * \param dst The destination of the recording to make
111 * \param dst_recording If successful, the stored recording created as a result of the copy
112 *
113 * \retval 0 on success
114 * \retval Non-zero on error
115 */
116int stasis_app_stored_recording_copy(struct stasis_app_stored_recording *src_recording, const char *dst,
117 struct stasis_app_stored_recording **dst_recording);
118
119/*!
120 * \brief Delete a recording from disk.
121 *
122 * \param recording Recording to delete.
123 * \return 0 on success.
124 * \return Non-zero on error.
125 */
127 struct stasis_app_stored_recording *recording);
128
129/*! @} */
130
131/*! @{ */
132
133/*! Opaque struct for handling the recording of media to a file. */
135
136/*! State of a recording operation */
138 /*! The recording has not started yet */
140 /*! The media is currently recording */
142 /*! The media is currently paused */
144 /*! The media has stopped recording */
146 /*! The media has stopped recording, with error */
148 /*! The media has stopped recording, discard the recording file */
150 /*! Sentinel */
152};
153
154/*! Valid operation for controlling a recording. */
156 /*! Stop the recording, deleting the media file(s) */
158 /*! Stop the recording. */
160 /*! Pause the recording */
162 /*! Unpause the recording */
164 /*! Mute the recording (record silence) */
166 /*! Unmute the recording */
168 /*! Sentinel */
170};
171
172#define STASIS_APP_RECORDING_TERMINATE_INVALID 0
173#define STASIS_APP_RECORDING_TERMINATE_NONE -1
174#define STASIS_APP_RECORDING_TERMINATE_ANY -2
175
178 AST_STRING_FIELD(name); /*!< name Name of the recording. */
179 AST_STRING_FIELD(format); /*!< Format to be recorded (wav, gsm, etc.) */
180 AST_STRING_FIELD(target); /*!< URI of what is being recorded */
181 );
182 /*! Number of seconds of silence before ending the recording. */
184 /*! Maximum recording duration. 0 for no maximum. */
186 /*! Which DTMF to use to terminate the recording
187 * \c STASIS_APP_RECORDING_TERMINATE_NONE to terminate only on hangup
188 * \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF
189 */
191 /*! How to handle recording when a file already exists */
193 /*! If true, a beep is played at the start of recording */
194 int beep:1;
195};
196
197/*!
198 * \brief Allocate a recording options object.
199 *
200 * Clean up with ao2_cleanup().
201 *
202 * \param name Name of the recording.
203 * \param format Format to record in.
204 * \return Newly allocated options object.
205 * \retval NULL on error.
206 */
208 const char *name, const char *format);
209
210/*!
211 * \brief Parse a string into the recording termination enum.
212 *
213 * \param str String to parse.
214 * \return DTMF value to terminate on.
215 * \retval STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
216 * \retval STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
217 * \retval STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
218 */
220
221/*!
222 * \brief Parse a string into the if_exists enum.
223 *
224 * \param str String to parse.
225 * \return How to handle an existing file.
226 * \return -1 on error.
227 */
229 const char *str);
230
231/*!
232 * \brief Record media from a channel.
233 *
234 * A reference to the \a options object may be kept, so it MUST NOT be modified
235 * after calling this function.
236 *
237 * On error, \c errno is set to indicate the failure reason.
238 * - \c EINVAL: Invalid input.
239 * - \c EEXIST: A recording with that name is in session.
240 * - \c ENOMEM: Out of memory.
241 *
242 * \param control Control for \c res_stasis.
243 * \param options Recording options.
244 * \return Recording control object.
245 * \retval NULL on error.
246 */
250
251/*!
252 * \brief Gets the current state of a recording operation.
253 *
254 * \param recording Recording control object.
255 * \return The state of the \a recording object.
256 */
258 struct stasis_app_recording *recording);
259
260/*!
261 * \brief Gets the unique name of a recording object.
262 *
263 * \param recording Recording control object.
264 * \return \a recording's name.
265 * \retval NULL if \a recording ic \c NULL
266 */
268 struct stasis_app_recording *recording);
269
270/*!
271 * \brief Finds the recording object with the given name.
272 *
273 * \param name Name of the recording object to find.
274 * \return Associated \ref stasis_app_recording object.
275 * \retval NULL if \a name not found.
276 */
278
279/*!
280 * \brief Construct a JSON model of a recording.
281 *
282 * \param recording Recording to conver.
283 * \return JSON model.
284 * \retval NULL on error.
285 */
287 const struct stasis_app_recording *recording);
288
289/*!
290 * \brief Possible results from a recording operation.
291 */
293 /*! Operation completed successfully. */
295 /*! Operation failed. */
297 /*! Operation failed b/c recording is not in session. */
299};
300
301/*!
302 * \brief Controls the media for a given recording operation.
303 *
304 * \param recording Recording control object.
305 * \param operation Media control operation.
306 * \retval STASIS_APP_RECORDING_OPER_OK on success.
307 * \return \ref stasis_app_recording_oper_results indicating failure.
308 */
310 struct stasis_app_recording *recording,
312
313/*!
314 * \brief Message type for recording updates. The data is an
315 * \ref ast_channel_blob.
316 */
318
319/*! @} */
320
321#endif /* _ASTERISK_STASIS_APP_RECORDING_H */
const char * str
Definition: app_jack.c:147
static const char name[]
Definition: format_mp3.c:68
Application convenience functions, designed to give consistent look and feel to Asterisk apps.
ast_record_if_exists
Stasis Application API. See Stasis Application API for detailed documentation.
const char * stasis_app_stored_recording_get_filename(struct stasis_app_stored_recording *recording)
Returns the full filename, with extension, for this recording.
Definition: stored.c:62
const char * stasis_app_stored_recording_get_file(struct stasis_app_stored_recording *recording)
Returns the filename for this recording, for use with streamfile.
Definition: stored.c:53
struct stasis_app_recording_options * stasis_app_recording_options_create(const char *name, const char *format)
Allocate a recording options object.
struct stasis_message_type * stasis_app_recording_snapshot_type(void)
Message type for recording updates. The data is an ast_channel_blob.
struct ast_json * stasis_app_recording_to_json(const struct stasis_app_recording *recording)
Construct a JSON model of a recording.
struct ao2_container * stasis_app_stored_recording_find_all(void)
Find all stored recordings on disk.
Definition: stored.c:297
enum stasis_app_recording_state stasis_app_recording_get_state(struct stasis_app_recording *recording)
Gets the current state of a recording operation.
struct ast_json * stasis_app_stored_recording_to_json(struct stasis_app_stored_recording *recording)
Convert stored recording info to JSON.
Definition: stored.c:455
struct stasis_app_stored_recording * stasis_app_stored_recording_find_by_name(const char *name)
Creates a stored recording object, with the given name.
Definition: stored.c:318
struct stasis_app_recording * stasis_app_recording_find_by_name(const char *name)
Finds the recording object with the given name.
int stasis_app_stored_recording_delete(struct stasis_app_stored_recording *recording)
Delete a recording from disk.
Definition: stored.c:448
enum stasis_app_recording_oper_results stasis_app_recording_operation(struct stasis_app_recording *recording, enum stasis_app_recording_media_operation operation)
Controls the media for a given recording operation.
stasis_app_recording_oper_results
Possible results from a recording operation.
@ STASIS_APP_RECORDING_OPER_NOT_RECORDING
@ STASIS_APP_RECORDING_OPER_FAILED
@ STASIS_APP_RECORDING_OPER_OK
const char * stasis_app_stored_recording_get_extension(struct stasis_app_stored_recording *recording)
Returns the extension for this recording.
Definition: stored.c:71
struct stasis_app_recording * stasis_app_control_record(struct stasis_app_control *control, struct stasis_app_recording_options *options)
Record media from a channel.
enum ast_record_if_exists stasis_app_recording_if_exists_parse(const char *str)
Parse a string into the if_exists enum.
stasis_app_recording_state
@ STASIS_APP_RECORDING_STATE_CANCELED
@ STASIS_APP_RECORDING_STATE_FAILED
@ STASIS_APP_RECORDING_STATE_COMPLETE
@ STASIS_APP_RECORDING_STATE_RECORDING
@ STASIS_APP_RECORDING_STATE_PAUSED
@ STASIS_APP_RECORDING_STATE_QUEUED
@ STASIS_APP_RECORDING_STATE_MAX
char stasis_app_recording_termination_parse(const char *str)
Parse a string into the recording termination enum.
int stasis_app_stored_recording_copy(struct stasis_app_stored_recording *src_recording, const char *dst, struct stasis_app_stored_recording **dst_recording)
Copy a recording.
Definition: stored.c:398
stasis_app_recording_media_operation
@ STASIS_APP_RECORDING_PAUSE
@ STASIS_APP_RECORDING_UNPAUSE
@ STASIS_APP_RECORDING_UNMUTE
@ STASIS_APP_RECORDING_STOP
@ STASIS_APP_RECORDING_OPER_MAX
@ STASIS_APP_RECORDING_MUTE
@ STASIS_APP_RECORDING_CANCEL
const char * stasis_app_recording_get_name(struct stasis_app_recording *recording)
Gets the unique name of a recording object.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Generic container type.
Abstract JSON element (object, array, string, int, ...).
enum ast_record_if_exists if_exists
struct stasis_app_control * control
static struct test_options options