Asterisk - The Open Source Telephony Project  21.4.1
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  */
116 int 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. */
134 struct stasis_app_recording;
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  */
219 char stasis_app_recording_termination_parse(const char *str);
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  */
248  struct stasis_app_control *control,
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,
311  enum stasis_app_recording_media_operation operation);
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 */
stasis_app_recording_media_operation
struct stasis_app_control * control
ast_record_if_exists
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 ast_json * stasis_app_stored_recording_to_json(struct stasis_app_stored_recording *recording)
Convert stored recording info to JSON.
Definition: stored.c:450
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
char stasis_app_recording_termination_parse(const char *str)
Parse a string into the recording termination enum.
struct ao2_container * stasis_app_stored_recording_find_all(void)
Find all stored recordings on disk.
Definition: stored.c:294
struct ast_json * stasis_app_recording_to_json(const struct stasis_app_recording *recording)
Construct a JSON model of a recording.
const char * stasis_app_recording_get_name(struct stasis_app_recording *recording)
Gets the unique name of a recording object.
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
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
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_options * options
enum ast_record_if_exists stasis_app_recording_if_exists_parse(const char *str)
Parse a string into the if_exists enum.
const ast_string_field name
Definition: stored.c:41
stasis_app_recording_oper_results
Possible results from a recording operation.
struct stasis_message_type * stasis_app_recording_snapshot_type(void)
Message type for recording updates. The data is an ast_channel_blob.
struct stasis_app_recording_options * stasis_app_recording_options_create(const char *name, const char *format)
Allocate a recording options object.
int stasis_app_stored_recording_delete(struct stasis_app_stored_recording *recording)
Delete a recording from disk.
Definition: stored.c:443
stasis_app_recording_state
enum ast_record_if_exists if_exists
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:393
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:314
Abstract JSON element (object, array, string, int, ...).
struct stasis_app_recording * stasis_app_recording_find_by_name(const char *name)
Finds the recording object with the given name.
Stasis Application API. See Stasis Application API for detailed documentation.
Generic container type.
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
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.
enum stasis_app_recording_state stasis_app_recording_get_state(struct stasis_app_recording *recording)
Gets the current state of a recording operation.
struct stasis_app_recording * stasis_app_control_record(struct stasis_app_control *control, struct stasis_app_recording_options *options)
Record media from a channel.