Asterisk - The Open Source Telephony Project  18.5.0
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 <[email protected]>
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 <[email protected]>
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  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
216  * \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
217  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c 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  * \return \c 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 control Media control operation.
306  * \return \c 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:446
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:337
const char * str
Definition: app_jack.c:147
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:290
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:299
const char * stasis_app_stored_recording_get_extension(struct stasis_app_stored_recording *recording)
Returns the extension for this recording.
Definition: stored.c:71
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_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.
static const char name[]
Definition: cdr_mysql.c:74
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:439
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:389
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:310
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.
static struct test_options options
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.