375b2dd9db4b786c1a3e0d00e7a9df35119c9af9
[asterisk/asterisk.git] / include / asterisk / audiohook.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2007, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@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 /*! \file
20  * \brief Audiohooks Architecture
21  */
22
23 #ifndef _ASTERISK_AUDIOHOOK_H
24 #define _ASTERISK_AUDIOHOOK_H
25
26 #if defined(__cplusplus) || defined(c_plusplus)
27 extern "C" {
28 #endif
29
30 /* these two are used in struct ast_audiohook */
31 #include "asterisk/lock.h"
32 #include "asterisk/linkedlists.h"
33 #include "asterisk/slinfactory.h"
34
35 enum ast_audiohook_type {
36         AST_AUDIOHOOK_TYPE_SPY = 0,    /*!< Audiohook wants to receive audio */
37         AST_AUDIOHOOK_TYPE_WHISPER,    /*!< Audiohook wants to provide audio to be mixed with existing audio */
38         AST_AUDIOHOOK_TYPE_MANIPULATE, /*!< Audiohook wants to manipulate the audio */
39 };
40
41 enum ast_audiohook_status {
42         AST_AUDIOHOOK_STATUS_NEW = 0,  /*!< Audiohook was just created, not in use yet */
43         AST_AUDIOHOOK_STATUS_RUNNING,  /*!< Audiohook is running on a channel */
44         AST_AUDIOHOOK_STATUS_SHUTDOWN, /*!< Audiohook is being shutdown */
45         AST_AUDIOHOOK_STATUS_DONE,     /*!< Audiohook has shutdown and is not running on a channel any longer */
46 };
47
48 enum ast_audiohook_direction {
49         AST_AUDIOHOOK_DIRECTION_READ = 0, /*!< Reading audio in */
50         AST_AUDIOHOOK_DIRECTION_WRITE,    /*!< Writing audio out */
51         AST_AUDIOHOOK_DIRECTION_BOTH,     /*!< Both reading audio in and writing audio out */
52 };
53
54 enum ast_audiohook_flags {
55         AST_AUDIOHOOK_TRIGGER_MODE  = (3 << 0), /*!< When audiohook should be triggered to do something */
56         AST_AUDIOHOOK_TRIGGER_READ  = (1 << 0), /*!< Audiohook wants to be triggered when reading audio in */
57         AST_AUDIOHOOK_TRIGGER_WRITE = (2 << 0), /*!< Audiohook wants to be triggered when writing audio out */
58         AST_AUDIOHOOK_WANTS_DTMF    = (1 << 2), /*!< Audiohook also wants to receive DTMF frames */
59         AST_AUDIOHOOK_TRIGGER_SYNC  = (1 << 3), /*!< Audiohook wants to be triggered when both sides have combined audio available */
60         /*! Audiohooks with this flag set will not allow for a large amount of samples to build up on its
61          * slinfactories. We will flush the factories if they contain too many samples.
62          */
63         AST_AUDIOHOOK_SMALL_QUEUE   = (1 << 4),
64         AST_AUDIOHOOK_MUTE_READ     = (1 << 5), /*!< audiohook should be mute frames read */
65         AST_AUDIOHOOK_MUTE_WRITE    = (1 << 6), /*!< audiohook should be mute frames written */
66 };
67
68 enum ast_audiohook_init_flags {
69         /*! Audiohook manipulate callback is capable of handling slinear at any sample rate.
70          * Without enabling this flag on initialization the manipulation callback is guaranteed
71          * 8khz audio only. */
72         AST_AUDIOHOOK_MANIPULATE_ALL_RATES = (1 << 0),
73 };
74
75 struct ast_audiohook;
76
77 /*! \brief Callback function for manipulate audiohook type
78  * \param audiohook Audiohook structure
79  * \param chan Channel
80  * \param frame Frame of audio to manipulate
81  * \param direction Direction frame came from
82  * \return Returns 0 on success, -1 on failure.
83  * \note An audiohook does not have any reference to a private data structure for manipulate
84  *       types. It is up to the manipulate callback to store this data via it's own method.
85  *       An example would be datastores.
86  * \note The input frame should never be freed or corrupted during a manipulate callback.
87  *       If the callback has the potential to corrupt the frame's data during manipulation,
88  *       local data should be used for the manipulation and only copied to the frame on
89  *       success.
90  * \note A failure return value indicates that the frame was not manipulated and that
91  *       is being returned in its original state.
92  */
93 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
94
95 struct ast_audiohook_options {
96         int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
97         int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
98 };
99
100 struct ast_audiohook {
101         ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
102         ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
103         enum ast_audiohook_type type;                          /*!< Type of audiohook */
104         enum ast_audiohook_status status;                      /*!< Status of the audiohook */
105         enum ast_audiohook_init_flags init_flags;              /*!< Init flags */
106         const char *source;                                    /*!< Who this audiohook ultimately belongs to */
107         unsigned int flags;                                    /*!< Flags on the audiohook */
108         struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
109         struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
110         struct timeval read_time;                              /*!< Last time read factory was fed */
111         struct timeval write_time;                             /*!< Last time write factory was fed */
112         struct ast_format *format;                             /*!< Format translation path is setup as */
113         struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
114         ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
115         struct ast_audiohook_options options;                  /*!< Applicable options */
116         unsigned int hook_internal_samp_rate;                           /*!< internal read/write sample rate on the audiohook.*/
117         AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
118 };
119
120 struct ast_audiohook_list;
121
122 /*! \brief Initialize an audiohook structure
123  * \param audiohook Audiohook structure
124  * \param type Type of audiohook to initialize this as
125  * \param source Who is initializing this audiohook
126  * \param init flags
127  * \return Returns 0 on success, -1 on failure
128  */
129 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags);
130
131 /*! \brief Destroys an audiohook structure
132  * \param audiohook Audiohook structure
133  * \return Returns 0 on success, -1 on failure
134  */
135 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
136
137 /*! \brief Writes a frame into the audiohook structure
138  * \param audiohook Audiohook structure
139  * \param direction Direction the audio frame came from
140  * \param frame Frame to write in
141  * \return Returns 0 on success, -1 on failure
142  */
143 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
144
145 /*! \brief Reads a frame in from the audiohook structure
146  * \param audiohook Audiohook structure
147  * \param samples Number of samples wanted
148  * \param direction Direction the audio frame came from
149  * \param format Format of frame remote side wants back
150  * \return Returns frame on success, NULL on failure
151  */
152 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, struct ast_format *format);
153
154 /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments.
155  * \param audiohook Audiohook structure
156  * \param samples Number of samples wanted
157  * \param ast_format Format of frame remote side wants back
158  * \param read_frame if available, we'll copy the read buffer to this.
159  * \param write_frame if available, we'll copy the write buffer to this.
160  * \param direction
161  * \return Returns frame on success, NULL on failure
162  */
163 struct ast_frame *ast_audiohook_read_frame_all(struct ast_audiohook *audiohook, size_t samples, struct ast_format *format, struct ast_frame **read_frame, struct ast_frame **write_frame);
164
165 /*! \brief Attach audiohook to channel
166  * \param chan Channel
167  * \param audiohook Audiohook structure
168  * \return Returns 0 on success, -1 on failure
169  */
170 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
171
172 /*! \brief Detach audiohook from channel
173  * \param audiohook Audiohook structure
174  * \return Returns 0 on success, -1 on failure
175  */
176 int ast_audiohook_detach(struct ast_audiohook *audiohook);
177
178 /*!
179  * \brief Detach audiohooks from list and destroy said list
180  * \param audiohook_list List of audiohooks (NULL tolerant)
181  * \return Nothing
182  */
183 void ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
184
185 /*! \brief Move an audiohook from one channel to a new one
186  *
187  * \todo Currently only the first audiohook of a specific source found will be moved.
188  * We should add the capability to move multiple audiohooks from a single source as well.
189  *
190  * \note It is required that both old_chan and new_chan are locked prior to calling
191  * this function. Besides needing to protect the data within the channels, not locking
192  * these channels can lead to a potential deadlock
193  *
194  * \param old_chan The source of the audiohook to move
195  * \param new_chan The destination to which we want the audiohook to move
196  * \param source The source of the audiohook we want to move
197  */
198 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
199
200 /*! \brief Move all audiohooks from one channel to another
201  *
202  * \note It is required that both old_chan and new_chan are locked prior to calling
203  * this function. Besides needing to protect the data within the channels, not locking
204  * these channels can lead to a potential deadlock.
205  *
206  * \param old_chan The source of the audiohooks being moved
207  * \param new_chan The destination channel for the audiohooks to be moved to
208  */
209 void ast_audiohook_move_all(struct ast_channel *old_chan, struct ast_channel *new_chan);
210
211 /*!
212  * \brief Detach specified source audiohook from channel
213  *
214  * \param chan Channel to detach from
215  * \param source Name of source to detach
216  *
217  * \return Returns 0 on success, -1 on failure
218  *
219  * \note The channel does not need to be locked before calling this function.
220  */
221 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
222
223 /*!
224  * \brief Remove an audiohook from a specified channel
225  *
226  * \param chan Channel to remove from
227  * \param audiohook Audiohook to remove
228  *
229  * \return Returns 0 on success, -1 on failure
230  *
231  * \note The channel does not need to be locked before calling this function
232  */
233 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
234
235 /*!
236  * \brief Determine if a audiohook_list is empty or not.
237  *
238  * \param audiohook Audiohook to check.  (NULL also means empty)
239  *
240  * retval 0 false, 1 true
241  */
242 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
243
244 /*! \brief Pass a frame off to be handled by the audiohook core
245  * \param chan Channel that the list is coming off of
246  * \param audiohook_list List of audiohooks
247  * \param direction Direction frame is coming in from
248  * \param frame The frame itself
249  * \return Return frame on success, NULL on failure
250  */
251 struct ast_frame *ast_audiohook_write_list(struct ast_channel *chan, struct ast_audiohook_list *audiohook_list, enum ast_audiohook_direction direction, struct ast_frame *frame);
252
253 /*! \brief Update audiohook's status
254  * \param audiohook Audiohook structure
255  * \param audiohook status enum
256  *
257  * \note once status is updated to DONE, this function can not be used to set the
258  * status back to any other setting.  Setting DONE effectively locks the status as such.
259  */
260 void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status);
261
262 /*! \brief Wait for audiohook trigger to be triggered
263  * \param audiohook Audiohook to wait on
264  */
265 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
266
267 /*!
268   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
269   \param chan The channel on which to find the spies
270   \param source The audiohook's source
271   \param type The type of audiohook
272   \return Return the number of audiohooks which are from the source specified
273
274   Note: Function performs nlocking.
275 */
276 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
277
278 /*!
279   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
280   \param chan The channel on which to find the spies
281   \param source The source of the audiohook
282   \param type The type of spy to look for
283   \return Return the number of running audiohooks which are from the source specified
284
285   Note: Function performs no locking.
286 */
287 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
288
289 /*! \brief Lock an audiohook
290  * \param ah Audiohook structure
291  */
292 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
293
294 /*! \brief Unlock an audiohook
295  * \param ah Audiohook structure
296  */
297 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
298
299 /*!
300  * \brief Adjust the volume on frames read from or written to a channel
301  * \param chan Channel to muck with
302  * \param direction Direction to set on
303  * \param volume Value to adjust the volume by
304  * \return Returns 0 on success, -1 on failure
305  * \since 1.6.1
306  */
307 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
308
309 /*!
310  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
311  * \param chan Channel to retrieve volume adjustment from
312  * \param direction Direction to retrieve
313  * \return Returns adjustment value
314  * \since 1.6.1
315  */
316 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
317
318 /*!
319  * \brief Adjust the volume on frames read from or written to a channel
320  * \param chan Channel to muck with
321  * \param direction Direction to increase
322  * \param volume Value to adjust the adjustment by
323  * \return Returns 0 on success, -1 on failure
324  * \since 1.6.1
325  */
326 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
327
328 /*! \brief Mute frames read from or written to a channel
329  * \param chan Channel to muck with
330  * \param source Type of audiohook
331  * \param flag which direction to set / clear
332  * \param clear set or clear muted frames on direction based on flag parameter
333  * \retval 0 success
334  * \retval -1 failure
335  */
336 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear);
337
338 #if defined(__cplusplus) || defined(c_plusplus)
339 }
340 #endif
341
342 #endif /* _ASTERISK_AUDIOHOOK_H */