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