app_directory: add ability to specify configuration file
[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         AST_AUDIOHOOK_COMPATIBLE    = (1 << 7), /*!< is the audiohook native slin compatible */
67
68         AST_AUDIOHOOK_SUBSTITUTE_SILENCE = (1 << 8), /*!< Substitute silence for missing audio */
69 };
70
71 enum ast_audiohook_init_flags {
72         /*! Audiohook manipulate callback is capable of handling slinear at any sample rate.
73          * Without enabling this flag on initialization the manipulation callback is guaranteed
74          * 8khz audio only. */
75         AST_AUDIOHOOK_MANIPULATE_ALL_RATES = (1 << 0),
76 };
77
78 struct ast_audiohook;
79
80 /*! \brief Callback function for manipulate audiohook type
81  * \param audiohook
82  * \param chan
83  * \param frame Frame of audio to manipulate
84  * \param direction Direction frame came from
85  * \retval 0 on success
86  * \retval -1 on failure
87  * \note An audiohook does not have any reference to a private data structure for manipulate
88  *       types. It is up to the manipulate callback to store this data via it's own method.
89  *       An example would be datastores.
90  * \note The input frame should never be freed or corrupted during a manipulate callback.
91  *       If the callback has the potential to corrupt the frame's data during manipulation,
92  *       local data should be used for the manipulation and only copied to the frame on
93  *       success.
94  * \note A failure return value indicates that the frame was not manipulated and that
95  *       is being returned in its original state.
96  */
97 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
98
99 struct ast_audiohook_options {
100         int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
101         int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
102 };
103
104 struct ast_audiohook {
105         ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
106         ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
107         enum ast_audiohook_type type;                          /*!< Type of audiohook */
108         enum ast_audiohook_status status;                      /*!< Status of the audiohook */
109         enum ast_audiohook_init_flags init_flags;              /*!< Init flags */
110         const char *source;                                    /*!< Who this audiohook ultimately belongs to */
111         unsigned int flags;                                    /*!< Flags on the audiohook */
112         struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
113         struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
114         struct timeval read_time;                              /*!< Last time read factory was fed */
115         struct timeval write_time;                             /*!< Last time write factory was fed */
116         struct ast_format *format;                             /*!< Format translation path is setup as */
117         struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
118         ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
119         struct ast_audiohook_options options;                  /*!< Applicable options */
120         unsigned int hook_internal_samp_rate;                  /*!< internal read/write sample rate on the audiohook.*/
121         enum ast_audiohook_direction direction;                /*!< Intended audiohook direction, BOTH by default on init */
122         AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
123 };
124
125 struct ast_audiohook_list;
126
127 /*! \brief Initialize an audiohook structure
128  * \param audiohook
129  * \param type Type of audiohook to initialize this as
130  * \param source Who is initializing this audiohook
131  * \param flags
132  * \retval 0 on success
133  * \retval -1 on failure
134  */
135 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags);
136
137 /*! \brief Destroys an audiohook structure
138  * \param audiohook
139  * \retval 0 on success
140  * \retval -1 on failure
141  */
142 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
143
144 /*! \brief Sets direction on audiohook
145  * \param audiohook
146  * \param direction In which direction should the audiohook feed frames, ie if we are snooping 'in', set direction to READ so that only the 'in' frames are fed to the slin factory
147  * \retval 0 on success
148  * \retval -1 on failure due to audiohook already in use or in shutdown. Can only set direction on NEW audiohooks
149  */
150 int ast_audiohook_set_frame_feed_direction(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction);
151
152 /*! \brief Writes a frame into the audiohook structure
153  * \param audiohook
154  * \param direction Direction the audio frame came from
155  * \param frame Frame to write in
156  * \retval 0 on success
157  * \retval -1 on failure
158  */
159 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
160
161 /*! \brief Reads a frame in from the audiohook structure
162  * \param audiohook
163  * \param samples Number of samples wanted
164  * \param direction Direction the audio frame came from
165  * \param format Format of frame remote side wants back
166  * \return frame on success
167  * \retval NULL on failure
168  */
169 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, struct ast_format *format);
170
171 /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments.
172  * \param audiohook
173  * \param samples Number of samples wanted
174  * \param format Format of frame remote side wants back
175  * \param read_frame if available, we'll copy the read buffer to this.
176  * \param write_frame if available, we'll copy the write buffer to this.
177  * \return frame on success
178  * \retval NULL on failure
179  */
180 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);
181
182 /*! \brief Attach audiohook to channel
183  * \param chan
184  * \param audiohook
185  * \return 0 on success
186  * \retval -1 on failure
187  */
188 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
189
190 /*! \brief Detach audiohook from channel
191  * \param audiohook
192  * \return Returns 0 on success, -1 on failure
193  */
194 int ast_audiohook_detach(struct ast_audiohook *audiohook);
195
196 /*!
197  * \brief Detach audiohooks from list and destroy said list
198  * \param audiohook_list List of audiohooks (NULL tolerant)
199  */
200 void ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
201
202 /*! \brief Move an audiohook from one channel to a new one
203  *
204  * \todo Currently only the first audiohook of a specific source found will be moved.
205  * We should add the capability to move multiple audiohooks from a single source as well.
206  *
207  * \note It is required that both old_chan and new_chan are locked prior to calling
208  * this function. Besides needing to protect the data within the channels, not locking
209  * these channels can lead to a potential deadlock
210  *
211  * \param old_chan The source of the audiohook to move
212  * \param new_chan The destination to which we want the audiohook to move
213  * \param source The source of the audiohook we want to move
214  */
215 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
216
217 /*! \brief Move all audiohooks from one channel to another
218  *
219  * \note It is required that both old_chan and new_chan are locked prior to calling
220  * this function. Besides needing to protect the data within the channels, not locking
221  * these channels can lead to a potential deadlock.
222  *
223  * \param old_chan The source of the audiohooks being moved
224  * \param new_chan The destination channel for the audiohooks to be moved to
225  */
226 void ast_audiohook_move_all(struct ast_channel *old_chan, struct ast_channel *new_chan);
227
228 /*!
229  * \brief Detach specified source audiohook from channel
230  *
231  * \param chan Channel to detach from
232  * \param source Name of source to detach
233  *
234  * \retval 0 on success
235  * \retval -1 on failure
236  *
237  * \note The channel does not need to be locked before calling this function.
238  */
239 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
240
241 /*!
242  * \brief Remove an audiohook from a specified channel
243  *
244  * \param chan Channel to remove from
245  * \param audiohook Audiohook to remove
246  *
247  * \retval 0 on success
248  * \retval -1 on failure
249  *
250  * \note The channel does not need to be locked before calling this function
251  */
252 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
253
254 /*!
255  * \brief Determine if a audiohook_list is empty or not.
256  *
257  * \param audiohook_list Audiohook to check.  (NULL also means empty)
258  *
259  * \retval 0 false
260  * \retval 1 true
261  */
262 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
263
264 /*! \brief Pass a frame off to be handled by the audiohook core
265  * \param chan Channel that the list is coming off of
266  * \param audiohook_list List of audiohooks
267  * \param direction Direction frame is coming in from
268  * \param frame The frame itself
269  * \return frame on success
270  * \retval NULL on failure
271  */
272 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);
273
274 /*! \brief Update audiohook's status
275  * \param audiohook
276  * \param status
277  *
278  * \note once status is updated to DONE, this function can not be used to set the
279  * status back to any other setting.  Setting DONE effectively locks the status as such.
280  */
281 void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status);
282
283 /*! \brief Wait for audiohook trigger to be triggered
284  * \param audiohook Audiohook to wait on
285  */
286 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
287
288 /*!
289   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
290   \param chan The channel on which to find the spies
291   \param source The audiohook's source
292   \param type The type of audiohook
293   \return number of audiohooks which are from the source specified
294
295   Note: Function performs nlocking.
296 */
297 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
298
299 /*!
300   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
301   \param chan The channel on which to find the spies
302   \param source The source of the audiohook
303   \param type The type of spy to look for
304   \return number of running audiohooks which are from the source specified
305
306   Note: Function performs no locking.
307 */
308 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
309
310 /*! \brief Lock an audiohook
311  * \param ah Audiohook structure
312  */
313 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
314
315 /*! \brief Unlock an audiohook
316  * \param ah Audiohook structure
317  */
318 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
319
320 /*!
321  * \brief Adjust the volume on frames read from or written to a channel
322  * \param chan Channel to muck with
323  * \param direction Direction to set on
324  * \param volume Value to adjust the volume by
325  * \retval 0 on success
326  * \retval -1 on failure
327  * \since 1.6.1
328  */
329 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
330
331 /*!
332  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
333  * \param chan Channel to retrieve volume adjustment from
334  * \param direction Direction to retrieve
335  * \return adjustment value
336  * \since 1.6.1
337  */
338 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
339
340 /*!
341  * \brief Adjust the volume on frames read from or written to a channel
342  * \param chan Channel to muck with
343  * \param direction Direction to increase
344  * \param volume Value to adjust the adjustment by
345  * \retval 0 on success
346  * \retval -1 on failure
347  * \since 1.6.1
348  */
349 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
350
351 /*! \brief Mute frames read from or written to a channel
352  * \param chan Channel to muck with
353  * \param source Type of audiohook
354  * \param flag which direction to set / clear
355  * \param clear set or clear muted frames on direction based on flag parameter
356  * \retval 0 success
357  * \retval -1 failure
358  */
359 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear);
360
361 #if defined(__cplusplus) || defined(c_plusplus)
362 }
363 #endif
364
365 #endif /* _ASTERISK_AUDIOHOOK_H */