ARI - channel recording support
[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 /*! Opaque struct for handling the recording of media to a file. */
35 struct stasis_app_recording;
36
37 /*! State of a recording operation */
38 enum stasis_app_recording_state {
39         /*! The recording has not started yet */
40         STASIS_APP_RECORDING_STATE_QUEUED,
41         /*! The media is currently recording */
42         STASIS_APP_RECORDING_STATE_RECORDING,
43         /*! The media is currently paused */
44         STASIS_APP_RECORDING_STATE_PAUSED,
45         /*! The media has stopped recording */
46         STASIS_APP_RECORDING_STATE_COMPLETE,
47         /*! The media has stopped playing */
48         STASIS_APP_RECORDING_STATE_FAILED,
49 };
50
51 /*! Valid operation for controlling a recording. */
52 enum stasis_app_recording_media_operation {
53         /*! Stop the recording operation. */
54         STASIS_APP_RECORDING_STOP,
55 };
56
57 #define STASIS_APP_RECORDING_TERMINATE_INVALID 0
58 #define STASIS_APP_RECORDING_TERMINATE_NONE -1
59 #define STASIS_APP_RECORDING_TERMINATE_ANY -2
60
61 struct stasis_app_recording_options {
62         AST_DECLARE_STRING_FIELDS(
63                 AST_STRING_FIELD(name); /*!< name Name of the recording. */
64                 AST_STRING_FIELD(format);       /*!< Format to be recorded (wav, gsm, etc.) */
65                 );
66         /*! Number of seconds of silence before ending the recording. */
67         int max_silence_seconds;
68         /*! Maximum recording duration. 0 for no maximum. */
69         int max_duration_seconds;
70         /*! Which DTMF to use to terminate the recording
71          *  \c STASIS_APP_RECORDING_TERMINATE_NONE to terminate only on hangup
72          *  \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF
73          */
74         char terminate_on;
75         /*! How to handle recording when a file already exists */
76         enum ast_record_if_exists if_exists;
77         /*! If true, a beep is played at the start of recording */
78         int beep:1;
79 };
80
81 /*!
82  * \brief Allocate a recording options object.
83  *
84  * Clean up with ao2_cleanup().
85  *
86  * \param name Name of the recording.
87  * \param format Format to record in.
88  * \return Newly allocated options object.
89  * \return \c NULL on error.
90  */
91 struct stasis_app_recording_options *stasis_app_recording_options_create(
92         const char *name, const char *format);
93
94 /*!
95  * \brief Parse a string into the recording termination enum.
96  *
97  * \param str String to parse.
98  * \return DTMF value to terminate on.
99  * \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
100  * \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
101  * \return \c STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
102  */
103 char stasis_app_recording_termination_parse(const char *str);
104
105 /*!
106  * \brief Parse a string into the if_exists enum.
107  *
108  * \param str String to parse.
109  * \return How to handle an existing file.
110  * \return -1 on error.
111  */
112 enum ast_record_if_exists stasis_app_recording_if_exists_parse(
113         const char *str);
114
115 /*!
116  * \brief Record media from a channel.
117  *
118  * A reference to the \a options object may be kept, so it MUST NOT be modified
119  * after calling this function.
120  *
121  * On error, \c errno is set to indicate the failure reason.
122  *  - \c EINVAL: Invalid input.
123  *  - \c EEXIST: A recording with that name is in session.
124  *  - \c ENOMEM: Out of memory.
125  *
126  * \param control Control for \c res_stasis.
127  * \param options Recording options.
128  * \return Recording control object.
129  * \return \c NULL on error.
130  */
131 struct stasis_app_recording *stasis_app_control_record(
132         struct stasis_app_control *control,
133         struct stasis_app_recording_options *options);
134
135 /*!
136  * \brief Gets the current state of a recording operation.
137  *
138  * \param recording Recording control object.
139  * \return The state of the \a recording object.
140  */
141 enum stasis_app_recording_state stasis_app_recording_get_state(
142         struct stasis_app_recording *recording);
143
144 /*!
145  * \brief Gets the unique name of a recording object.
146  *
147  * \param recording Recording control object.
148  * \return \a recording's name.
149  * \return \c NULL if \a recording ic \c NULL
150  */
151 const char *stasis_app_recording_get_name(
152         struct stasis_app_recording *recording);
153
154 /*!
155  * \brief Finds the recording object with the given name.
156  *
157  * \param name Name of the recording object to find.
158  * \return Associated \ref stasis_app_recording object.
159  * \return \c NULL if \a name not found.
160  */
161 struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name);
162
163 /*!
164  * \brief Construct a JSON model of a recording.
165  *
166  * \param recording Recording to conver.
167  * \return JSON model.
168  * \return \c NULL on error.
169  */
170 struct ast_json *stasis_app_recording_to_json(
171         const struct stasis_app_recording *recording);
172
173 /*!
174  * \brief Possible results from a recording operation.
175  */
176 enum stasis_app_recording_oper_results {
177         /*! Operation completed successfully. */
178         STASIS_APP_RECORDING_OPER_OK,
179         /*! Operation failed. */
180         STASIS_APP_RECORDING_OPER_FAILED,
181         /*! Operation failed b/c recording is not in session. */
182         STASIS_APP_RECORDING_OPER_NOT_RECORDING,
183 };
184
185 /*!
186  * \brief Controls the media for a given recording operation.
187  *
188  * \param recording Recording control object.
189  * \param control Media control operation.
190  * \return \c STASIS_APP_RECORDING_OPER_OK on success.
191  * \return \ref stasis_app_recording_oper_results indicating failure.
192  */
193 enum stasis_app_recording_oper_results stasis_app_recording_operation(
194         struct stasis_app_recording *recording,
195         enum stasis_app_recording_media_operation operation);
196
197 /*!
198  * \brief Message type for recording updates. The data is an
199  * \ref ast_channel_blob.
200  */
201 struct stasis_message_type *stasis_app_recording_snapshot_type(void);
202
203 #endif /* _ASTERISK_STASIS_APP_RECORDING_H */