Wed Jan 8 2020 09:49:42

Asterisk developer's documentation


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/frame_defs.h"
34 #include "asterisk/slinfactory.h"
35 
37  AST_AUDIOHOOK_TYPE_SPY = 0, /*!< Audiohook wants to receive audio */
38  AST_AUDIOHOOK_TYPE_WHISPER, /*!< Audiohook wants to provide audio to be mixed with existing audio */
39  AST_AUDIOHOOK_TYPE_MANIPULATE, /*!< Audiohook wants to manipulate the audio */
40 };
41 
43  AST_AUDIOHOOK_STATUS_NEW = 0, /*!< Audiohook was just created, not in use yet */
44  AST_AUDIOHOOK_STATUS_RUNNING, /*!< Audiohook is running on a channel */
45  AST_AUDIOHOOK_STATUS_SHUTDOWN, /*!< Audiohook is being shutdown */
46  AST_AUDIOHOOK_STATUS_DONE, /*!< Audiohook has shutdown and is not running on a channel any longer */
47 };
48 
50  AST_AUDIOHOOK_DIRECTION_READ = 0, /*!< Reading audio in */
51  AST_AUDIOHOOK_DIRECTION_WRITE, /*!< Writing audio out */
52  AST_AUDIOHOOK_DIRECTION_BOTH, /*!< Both reading audio in and writing audio out */
53 };
54 
55 /*
56  * The flags here have been shifted around due to an unintended overlap between
57  * AST_AUDIOHOOK_TRIGGER_WRITE and AST_AUDIOHOOK_WANTS_DTMF. In future Asterisk
58  * releases (Asterisk 11+), these have been reorganized to make more sense.
59  */
61  AST_AUDIOHOOK_TRIGGER_MODE = ((1 << 6) | (1 << 0)), /*!< When audiohook should be triggered to do something */
62  AST_AUDIOHOOK_TRIGGER_READ = (1 << 0), /*!< Audiohook wants to be triggered when reading audio in */
63  AST_AUDIOHOOK_TRIGGER_WRITE = (1 << 6), /*!< Audiohook wants to be triggered when writing audio out */
64  AST_AUDIOHOOK_WANTS_DTMF = (1 << 1), /*!< Audiohook also wants to receive DTMF frames */
65  AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2), /*!< Audiohook wants to be triggered when both sides have combined audio available */
66  /*! Audiohooks with this flag set will not allow for a large amount of samples to build up on its
67  * slinfactories. We will flush the factories if they contain too many samples.
68  */
70  AST_AUDIOHOOK_MUTE_READ = (1 << 4), /*!< audiohook should be mute frames read */
71  AST_AUDIOHOOK_MUTE_WRITE = (1 << 5), /*!< audiohook should be mute frames written */
72 
73  /* IMPORTANT: When adding new flags, start with (1 << 7) */
74 };
75 
76 #define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */
77 
78 struct ast_audiohook;
79 
80 /*! \brief Callback function for manipulate audiohook type
81  * \param audiohook Audiohook structure
82  * \param chan Channel
83  * \param frame Frame of audio to manipulate
84  * \param direction Direction frame came from
85  * \return Returns 0 on success, -1 on failure.
86  * \note An audiohook does not have any reference to a private data structure for manipulate
87  * types. It is up to the manipulate callback to store this data via it's own method.
88  * An example would be datastores.
89  * \note The input frame should never be freed or corrupted during a manipulate callback.
90  * If the callback has the potential to corrupt the frame's data during manipulation,
91  * local data should be used for the manipulation and only copied to the frame on
92  * success.
93  * \note A failure return value indicates that the frame was not manipulated and that
94  * is being returned in its original state.
95  */
96 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
97 
99  int read_volume; /*!< Volume adjustment on frames read from the channel the hook is on */
100  int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
101 };
102 
104  ast_mutex_t lock; /*!< Lock that protects the audiohook structure */
105  ast_cond_t trigger; /*!< Trigger condition (if enabled) */
106  enum ast_audiohook_type type; /*!< Type of audiohook */
107  enum ast_audiohook_status status; /*!< Status of the audiohook */
108  const char *source; /*!< Who this audiohook ultimately belongs to */
109  unsigned int flags; /*!< Flags on the audiohook */
110  struct ast_slinfactory read_factory; /*!< Factory where frames read from the channel, or read from the whisper source will go through */
111  struct ast_slinfactory write_factory; /*!< Factory where frames written to the channel will go through */
112  struct timeval read_time; /*!< Last time read factory was fed */
113  struct timeval write_time; /*!< Last time write factory was fed */
114  int format; /*!< Format translation path is setup as */
115  struct ast_trans_pvt *trans_pvt; /*!< Translation path for reading frames */
117  struct ast_audiohook_options options; /*!< Applicable options */
118  AST_LIST_ENTRY(ast_audiohook) list; /*!< Linked list information */
119 };
120 
121 struct ast_audiohook_list;
122 
123 /*! \brief Initialize an audiohook structure
124  * \param audiohook Audiohook structure
125  * \param type Type of audiohook to initialize this as
126  * \param source Who is initializing this audiohook
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);
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, format_t format);
153 
154 /*! \brief Attach audiohook to channel
155  * \param chan Channel
156  * \param audiohook Audiohook structure
157  * \return Returns 0 on success, -1 on failure
158  */
159 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
160 
161 /*! \brief Detach audiohook from channel
162  * \param audiohook Audiohook structure
163  * \return Returns 0 on success, -1 on failure
164  */
165 int ast_audiohook_detach(struct ast_audiohook *audiohook);
166 
167 /*! \brief Detach audiohooks from list and destroy said list
168  * \param audiohook_list List of audiohooks
169  * \return Returns 0 on success, -1 on failure
170  */
171 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
172 
173 /*! \brief Move an audiohook from one channel to a new one
174  *
175  * \todo Currently only the first audiohook of a specific source found will be moved.
176  * We should add the capability to move multiple audiohooks from a single source as well.
177  *
178  * \note It is required that both old_chan and new_chan are locked prior to calling
179  * this function. Besides needing to protect the data within the channels, not locking
180  * these channels can lead to a potential deadlock
181  *
182  * \param old_chan The source of the audiohook to move
183  * \param new_chan The destination to which we want the audiohook to move
184  * \param source The source of the audiohook we want to move
185  */
186 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
187 
188 /*!
189  * \brief Detach specified source audiohook from channel
190  *
191  * \param chan Channel to detach from
192  * \param source Name of source to detach
193  *
194  * \return Returns 0 on success, -1 on failure
195  *
196  * \note The channel does not need to be locked before calling this function.
197  */
198 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
199 
200 /*!
201  * \brief Remove an audiohook from a specified channel
202  *
203  * \param chan Channel to remove from
204  * \param audiohook Audiohook to remove
205  *
206  * \return Returns 0 on success, -1 on failure
207  *
208  * \note The channel does not need to be locked before calling this function
209  */
210 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
211 
212 /*!
213  * \brief determines if a audiohook_list is empty or not.
214  *
215  * retval 0 false, 1 true
216  */
217 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
218 
219 /*! \brief Pass a frame off to be handled by the audiohook core
220  * \param chan Channel that the list is coming off of
221  * \param audiohook_list List of audiohooks
222  * \param direction Direction frame is coming in from
223  * \param frame The frame itself
224  * \return Return frame on success, NULL on failure
225  */
226 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);
227 
228 /*! \brief Update audiohook's status
229  * \param audiohook Audiohook structure
230  * \param audiohook status enum
231  *
232  * \note once status is updated to DONE, this function can not be used to set the
233  * status back to any other setting. Setting DONE effectively locks the status as such.
234  */
236 
237 /*! \brief Wait for audiohook trigger to be triggered
238  * \param audiohook Audiohook to wait on
239  */
240 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
241 
242 /*!
243  \brief Find out how many audiohooks from a certain source exist on a given channel, regardless of status.
244  \param chan The channel on which to find the spies
245  \param source The audiohook's source
246  \param type The type of audiohook
247  \return Return the number of audiohooks which are from the source specified
248 
249  Note: Function performs nlocking.
250 */
251 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
252 
253 /*!
254  \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
255  \param chan The channel on which to find the spies
256  \param source The source of the audiohook
257  \param type The type of spy to look for
258  \return Return the number of running audiohooks which are from the source specified
259 
260  Note: Function performs no locking.
261 */
262 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
263 
264 /*! \brief Lock an audiohook
265  * \param ah Audiohook structure
266  */
267 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
268 
269 /*! \brief Unlock an audiohook
270  * \param ah Audiohook structure
271  */
272 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
273 
274 /*!
275  * \brief Adjust the volume on frames read from or written to a channel
276  * \param chan Channel to muck with
277  * \param direction Direction to set on
278  * \param volume Value to adjust the volume by
279  * \return Returns 0 on success, -1 on failure
280  * \since 1.6.1
281  */
282 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
283 
284 /*!
285  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
286  * \param chan Channel to retrieve volume adjustment from
287  * \param direction Direction to retrieve
288  * \return Returns adjustment value
289  * \since 1.6.1
290  */
291 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
292 
293 /*!
294  * \brief Adjust the volume on frames read from or written to a channel
295  * \param chan Channel to muck with
296  * \param direction Direction to increase
297  * \param volume Value to adjust the adjustment by
298  * \return Returns 0 on success, -1 on failure
299  * \since 1.6.1
300  */
301 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
302 
303 /*! \brief Mute frames read from or written to a channel
304  * \param chan Channel to muck with
305  * \param source Type of audiohook
306  * \param flag which direction to set / clear
307  * \param clear set or clear muted frames on direction based on flag parameter
308  * \retval 0 success
309  * \retval -1 failure
310  */
311 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear);
312 
313 #if defined(__cplusplus) || defined(c_plusplus)
314 }
315 #endif
316 
317 #endif /* _ASTERISK_AUDIOHOOK_H */
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:979
Main Channel structure associated with a channel.
Definition: channel.h:742
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:480
struct ast_frame * ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, format_t format)
Reads a frame in from the audiohook structure.
Definition: audiohook.c:313
struct ast_slinfactory write_factory
Definition: audiohook.h:111
ast_audiohook_flags
Definition: audiohook.h:60
Asterisk locking-related definitions:
enum ast_audiohook_type type
Definition: audiohook.h:106
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:127
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:1004
int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list)
determines if a audiohook_list is empty or not.
Definition: audiohook.c:744
int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source)
Initialize an audiohook structure.
Definition: audiohook.c:64
int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook)
Remove an audiohook from a specified channel.
Definition: audiohook.c:541
void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status)
Update audiohook&#39;s status.
Definition: audiohook.c:387
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:1057
int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook)
Attach audiohook to channel.
Definition: audiohook.c:348
ast_mutex_t lock
Definition: audiohook.h:104
int ast_audiohook_destroy(struct ast_audiohook *audiohook)
Destroys an audiohook structure.
Definition: audiohook.c:96
pthread_cond_t ast_cond_t
Definition: lock.h:144
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:96
ast_audiohook_manipulate_callback manipulate_callback
Definition: audiohook.h:116
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:791
ast_audiohook_type
Definition: audiohook.h:36
A set of macros to manage forward-linked lists.
struct ast_trans_pvt * trans_pvt
Definition: audiohook.h:115
int ast_audiohook_detach_source(struct ast_channel *chan, const char *source)
Detach specified source audiohook from channel.
Definition: audiohook.c:509
int ast_audiohook_detach(struct ast_audiohook *audiohook)
Detach audiohook from channel.
Definition: audiohook.c:401
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:762
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:135
int64_t format_t
Definition: frame_defs.h:32
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
struct ast_audiohook::@143 list
const char * source
Definition: audiohook.h:108
A machine to gather up arbitrary frames and convert them to raw slinear on demand.
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:1030
ast_cond_t trigger
Definition: audiohook.h:105
ast_audiohook_direction
Definition: audiohook.h:49
struct ast_slinfactory read_factory
Definition: audiohook.h:110
struct ast_audiohook_options options
Definition: audiohook.h:117
unsigned int flags
Definition: audiohook.h:109
struct timeval write_time
Definition: audiohook.h:113
Data structure associated with a single frame of data.
Definition: frame.h:142
enum ast_audiohook_status status
Definition: audiohook.h:107
struct timeval read_time
Definition: audiohook.h:112
ast_audiohook_status
Definition: audiohook.h:42
Asterisk internal frame definitions.
int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list)
Detach audiohooks from list and destroy said list.
Definition: audiohook.c:418
void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook)
Wait for audiohook trigger to be triggered.
Definition: audiohook.c:776
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:830
Structure for mutex and tracking information.
Definition: lock.h:121