Asterisk - The Open Source Telephony Project  GIT-master-a24979a
audiohook.h
Go to the documentation of this file.
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 
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 
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 
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 
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  */
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 
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. */
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 
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 
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 */
119  struct ast_audiohook_options options; /*!< Applicable options */
120  unsigned int hook_internal_samp_rate; /*!< internal read/write sample rate on the audiohook.*/
121  AST_LIST_ENTRY(ast_audiohook) list; /*!< Linked list information */
122 };
123 
124 struct ast_audiohook_list;
125 
126 /*! \brief Initialize an audiohook structure
127  * \param audiohook
128  * \param type Type of audiohook to initialize this as
129  * \param source Who is initializing this audiohook
130  * \param flags
131  * \retval 0 on success
132  * \retval -1 on failure
133  */
134 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags);
135 
136 /*! \brief Destroys an audiohook structure
137  * \param audiohook
138  * \retval 0 on success
139  * \retval -1 on failure
140  */
141 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
142 
143 /*! \brief Writes a frame into the audiohook structure
144  * \param audiohook
145  * \param direction Direction the audio frame came from
146  * \param frame Frame to write in
147  * \retval 0 on success
148  * \retval -1 on failure
149  */
150 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
151 
152 /*! \brief Reads a frame in from the audiohook structure
153  * \param audiohook
154  * \param samples Number of samples wanted
155  * \param direction Direction the audio frame came from
156  * \param format Format of frame remote side wants back
157  * \return frame on success
158  * \retval NULL on failure
159  */
161 
162 /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments.
163  * \param audiohook
164  * \param samples Number of samples wanted
165  * \param format Format of frame remote side wants back
166  * \param read_frame if available, we'll copy the read buffer to this.
167  * \param write_frame if available, we'll copy the write buffer to this.
168  * \return frame on success
169  * \retval NULL on failure
170  */
171 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);
172 
173 /*! \brief Attach audiohook to channel
174  * \param chan
175  * \param audiohook
176  * \return 0 on success
177  * \retval -1 on failure
178  */
179 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
180 
181 /*! \brief Detach audiohook from channel
182  * \param audiohook
183  * \return Returns 0 on success, -1 on failure
184  */
185 int ast_audiohook_detach(struct ast_audiohook *audiohook);
186 
187 /*!
188  * \brief Detach audiohooks from list and destroy said list
189  * \param audiohook_list List of audiohooks (NULL tolerant)
190  */
191 void ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
192 
193 /*! \brief Move an audiohook from one channel to a new one
194  *
195  * \todo Currently only the first audiohook of a specific source found will be moved.
196  * We should add the capability to move multiple audiohooks from a single source as well.
197  *
198  * \note It is required that both old_chan and new_chan are locked prior to calling
199  * this function. Besides needing to protect the data within the channels, not locking
200  * these channels can lead to a potential deadlock
201  *
202  * \param old_chan The source of the audiohook to move
203  * \param new_chan The destination to which we want the audiohook to move
204  * \param source The source of the audiohook we want to move
205  */
206 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
207 
208 /*! \brief Move all audiohooks from one channel to another
209  *
210  * \note It is required that both old_chan and new_chan are locked prior to calling
211  * this function. Besides needing to protect the data within the channels, not locking
212  * these channels can lead to a potential deadlock.
213  *
214  * \param old_chan The source of the audiohooks being moved
215  * \param new_chan The destination channel for the audiohooks to be moved to
216  */
217 void ast_audiohook_move_all(struct ast_channel *old_chan, struct ast_channel *new_chan);
218 
219 /*!
220  * \brief Detach specified source audiohook from channel
221  *
222  * \param chan Channel to detach from
223  * \param source Name of source to detach
224  *
225  * \retval 0 on success
226  * \retval -1 on failure
227  *
228  * \note The channel does not need to be locked before calling this function.
229  */
230 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
231 
232 /*!
233  * \brief Remove an audiohook from a specified channel
234  *
235  * \param chan Channel to remove from
236  * \param audiohook Audiohook to remove
237  *
238  * \retval 0 on success
239  * \retval -1 on failure
240  *
241  * \note The channel does not need to be locked before calling this function
242  */
243 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
244 
245 /*!
246  * \brief Determine if a audiohook_list is empty or not.
247  *
248  * \param audiohook_list Audiohook to check. (NULL also means empty)
249  *
250  * \retval 0 false
251  * \retval 1 true
252  */
253 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
254 
255 /*! \brief Pass a frame off to be handled by the audiohook core
256  * \param chan Channel that the list is coming off of
257  * \param audiohook_list List of audiohooks
258  * \param direction Direction frame is coming in from
259  * \param frame The frame itself
260  * \return frame on success
261  * \retval NULL on failure
262  */
263 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);
264 
265 /*! \brief Update audiohook's status
266  * \param audiohook
267  * \param status
268  *
269  * \note once status is updated to DONE, this function can not be used to set the
270  * status back to any other setting. Setting DONE effectively locks the status as such.
271  */
273 
274 /*! \brief Wait for audiohook trigger to be triggered
275  * \param audiohook Audiohook to wait on
276  */
277 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
278 
279 /*!
280  \brief Find out how many audiohooks from a certain source exist on a given channel, regardless of status.
281  \param chan The channel on which to find the spies
282  \param source The audiohook's source
283  \param type The type of audiohook
284  \return number of audiohooks which are from the source specified
285 
286  Note: Function performs nlocking.
287 */
288 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
289 
290 /*!
291  \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
292  \param chan The channel on which to find the spies
293  \param source The source of the audiohook
294  \param type The type of spy to look for
295  \return number of running audiohooks which are from the source specified
296 
297  Note: Function performs no locking.
298 */
299 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
300 
301 /*! \brief Lock an audiohook
302  * \param ah Audiohook structure
303  */
304 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
305 
306 /*! \brief Unlock an audiohook
307  * \param ah Audiohook structure
308  */
309 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
310 
311 /*!
312  * \brief Adjust the volume on frames read from or written to a channel
313  * \param chan Channel to muck with
314  * \param direction Direction to set on
315  * \param volume Value to adjust the volume by
316  * \retval 0 on success
317  * \retval -1 on failure
318  * \since 1.6.1
319  */
321 
322 /*!
323  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
324  * \param chan Channel to retrieve volume adjustment from
325  * \param direction Direction to retrieve
326  * \return adjustment value
327  * \since 1.6.1
328  */
330 
331 /*!
332  * \brief Adjust the volume on frames read from or written to a channel
333  * \param chan Channel to muck with
334  * \param direction Direction to increase
335  * \param volume Value to adjust the adjustment by
336  * \retval 0 on success
337  * \retval -1 on failure
338  * \since 1.6.1
339  */
341 
342 /*! \brief Mute frames read from or written to a channel
343  * \param chan Channel to muck with
344  * \param source Type of audiohook
345  * \param flag which direction to set / clear
346  * \param clear set or clear muted frames on direction based on flag parameter
347  * \retval 0 success
348  * \retval -1 failure
349  */
350 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear);
351 
352 #if defined(__cplusplus) || defined(c_plusplus)
353 }
354 #endif
355 
356 #endif /* _ASTERISK_AUDIOHOOK_H */
jack_status_t status
Definition: app_jack.c:146
ast_audiohook_init_flags
Definition: audiohook.h:71
@ AST_AUDIOHOOK_MANIPULATE_ALL_RATES
Definition: audiohook.h:75
struct ast_frame * ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, struct ast_format *format)
Reads a frame in from the audiohook structure.
Definition: audiohook.c:424
int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags)
Initialize an audiohook structure.
Definition: audiohook.c:100
int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear)
Mute frames read from or written to a channel.
Definition: audiohook.c:1331
int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame)
Writes a frame into the audiohook structure.
Definition: audiohook.c:152
int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook)
Remove an audiohook from a specified channel.
Definition: audiohook.c:699
ast_audiohook_direction
Definition: audiohook.h:48
@ AST_AUDIOHOOK_DIRECTION_READ
Definition: audiohook.h:49
@ AST_AUDIOHOOK_DIRECTION_WRITE
Definition: audiohook.h:50
@ AST_AUDIOHOOK_DIRECTION_BOTH
Definition: audiohook.h:51
int ast_audiohook_detach_source(struct ast_channel *chan, const char *source)
Detach specified source audiohook from channel.
Definition: audiohook.c:676
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)
Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame dat...
Definition: audiohook.c:429
int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction)
Retrieve the volume adjustment value on frames read from or written to a channel.
Definition: audiohook.c:1291
int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list)
Determine if a audiohook_list is empty or not.
Definition: audiohook.c:1049
void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook)
Wait for audiohook trigger to be triggered.
Definition: audiohook.c:1072
int(* ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction)
Callback function for manipulate audiohook type.
Definition: audiohook.h:97
void ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list)
Detach audiohooks from list and destroy said list.
Definition: audiohook.c:543
void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status)
Update audiohook's status.
Definition: audiohook.c:518
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)
Pass a frame off to be handled by the audiohook core.
Definition: audiohook.c:1057
ast_audiohook_flags
Definition: audiohook.h:54
@ AST_AUDIOHOOK_COMPATIBLE
Definition: audiohook.h:66
@ AST_AUDIOHOOK_WANTS_DTMF
Definition: audiohook.h:58
@ AST_AUDIOHOOK_TRIGGER_MODE
Definition: audiohook.h:55
@ AST_AUDIOHOOK_MUTE_READ
Definition: audiohook.h:64
@ AST_AUDIOHOOK_MUTE_WRITE
Definition: audiohook.h:65
@ AST_AUDIOHOOK_SUBSTITUTE_SILENCE
Definition: audiohook.h:68
@ AST_AUDIOHOOK_SMALL_QUEUE
Definition: audiohook.h:63
@ AST_AUDIOHOOK_TRIGGER_READ
Definition: audiohook.h:56
@ AST_AUDIOHOOK_TRIGGER_WRITE
Definition: audiohook.h:57
@ AST_AUDIOHOOK_TRIGGER_SYNC
Definition: audiohook.h:59
int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type)
Find out how many audiohooks from a certain source exist on a given channel, regardless of status.
Definition: audiohook.c:1087
int ast_audiohook_detach(struct ast_audiohook *audiohook)
Detach audiohook from channel.
Definition: audiohook.c:528
int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook)
Attach audiohook to channel.
Definition: audiohook.c:462
int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type)
Find out how many spies of a certain type exist on a given channel, and are in state running.
Definition: audiohook.c:1127
int ast_audiohook_destroy(struct ast_audiohook *audiohook)
Destroys an audiohook structure.
Definition: audiohook.c:121
ast_audiohook_type
Definition: audiohook.h:35
@ AST_AUDIOHOOK_TYPE_MANIPULATE
Definition: audiohook.h:38
@ AST_AUDIOHOOK_TYPE_SPY
Definition: audiohook.h:36
@ AST_AUDIOHOOK_TYPE_WHISPER
Definition: audiohook.h:37
ast_audiohook_status
Definition: audiohook.h:41
@ AST_AUDIOHOOK_STATUS_DONE
Definition: audiohook.h:45
@ AST_AUDIOHOOK_STATUS_NEW
Definition: audiohook.h:42
@ AST_AUDIOHOOK_STATUS_RUNNING
Definition: audiohook.h:43
@ AST_AUDIOHOOK_STATUS_SHUTDOWN
Definition: audiohook.h:44
int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume)
Adjust the volume on frames read from or written to a channel.
Definition: audiohook.c:1311
int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume)
Adjust the volume on frames read from or written to a channel.
Definition: audiohook.c:1271
void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source)
Move an audiohook from one channel to a new one.
Definition: audiohook.c:634
void ast_audiohook_move_all(struct ast_channel *old_chan, struct ast_channel *new_chan)
Move all audiohooks from one channel to another.
Definition: audiohook.c:650
static snd_pcm_format_t format
Definition: chan_alsa.c:106
static const char type[]
Definition: chan_ooh323.c:109
long int flag
Definition: f2c.h:83
static struct ast_frame * read_frame(struct ast_filestream *s, int *whennext)
Definition: file.c:909
direction
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
Asterisk locking-related definitions:
pthread_cond_t ast_cond_t
Definition: lock.h:176
A machine to gather up arbitrary frames and convert them to raw slinear on demand.
ast_cond_t trigger
Definition: audiohook.h:106
struct timeval write_time
Definition: audiohook.h:115
enum ast_audiohook_type type
Definition: audiohook.h:107
struct timeval read_time
Definition: audiohook.h:114
ast_audiohook_manipulate_callback manipulate_callback
Definition: audiohook.h:118
unsigned int hook_internal_samp_rate
Definition: audiohook.h:120
struct ast_slinfactory read_factory
Definition: audiohook.h:112
struct ast_trans_pvt * trans_pvt
Definition: audiohook.h:117
struct ast_audiohook_options options
Definition: audiohook.h:119
enum ast_audiohook_init_flags init_flags
Definition: audiohook.h:109
enum ast_audiohook_status status
Definition: audiohook.h:108
struct ast_audiohook::@215 list
struct ast_format * format
Definition: audiohook.h:116
unsigned int flags
Definition: audiohook.h:111
ast_mutex_t lock
Definition: audiohook.h:105
struct ast_slinfactory write_factory
Definition: audiohook.h:113
const char * source
Definition: audiohook.h:110
Main Channel structure associated with a channel.
Definition of a media format.
Definition: format.c:43
Data structure associated with a single frame of data.
Structure for mutex and tracking information.
Definition: lock.h:135
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:213