audiohook signal trigger on every status change
[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/frame_defs.h"
34 #include "asterisk/slinfactory.h"
35
36 enum ast_audiohook_type {
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
42 enum ast_audiohook_status {
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
49 enum ast_audiohook_direction {
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 enum ast_audiohook_flags {
56         AST_AUDIOHOOK_TRIGGER_MODE = (3 << 0),  /*!< When audiohook should be triggered to do something */
57         AST_AUDIOHOOK_TRIGGER_READ = (1 << 0),  /*!< Audiohook wants to be triggered when reading audio in */
58         AST_AUDIOHOOK_TRIGGER_WRITE = (2 << 0), /*!< Audiohook wants to be triggered when writing audio out */
59         AST_AUDIOHOOK_WANTS_DTMF = (1 << 1),    /*!< Audiohook also wants to receive DTMF frames */
60         AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2),  /*!< Audiohook wants to be triggered when both sides have combined audio available */
61         /*! Audiohooks with this flag set will not allow for a large amount of samples to build up on its
62          * slinfactories. We will flush the factories if they contain too many samples.
63          */
64         AST_AUDIOHOOK_SMALL_QUEUE = (1 << 3),
65 };
66
67 #define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */
68
69 struct ast_audiohook;
70
71 /*! \brief Callback function for manipulate audiohook type
72  * \param audiohook Audiohook structure
73  * \param chan Channel
74  * \param frame Frame of audio to manipulate
75  * \param direction Direction frame came from
76  * \return Returns 0 on success, -1 on failure
77  * \note An audiohook does not have any reference to a private data structure for manipulate types. It is up to the manipulate callback to store this data
78  *       via it's own method. An example would be datastores.
79  */
80 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
81
82 struct ast_audiohook_options {
83         int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
84         int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
85 };
86
87 struct ast_audiohook {
88         ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
89         ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
90         enum ast_audiohook_type type;                          /*!< Type of audiohook */
91         enum ast_audiohook_status status;                      /*!< Status of the audiohook */
92         const char *source;                                    /*!< Who this audiohook ultimately belongs to */
93         unsigned int flags;                                    /*!< Flags on the audiohook */
94         struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
95         struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
96         struct timeval read_time;                              /*!< Last time read factory was fed */
97         struct timeval write_time;                             /*!< Last time write factory was fed */
98         int format;                                            /*!< Format translation path is setup as */
99         struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
100         ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
101         struct ast_audiohook_options options;                  /*!< Applicable options */
102         AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
103 };
104
105 struct ast_audiohook_list;
106
107 /*! \brief Initialize an audiohook structure
108  * \param audiohook Audiohook structure
109  * \param type Type of audiohook to initialize this as
110  * \param source Who is initializing this audiohook
111  * \return Returns 0 on success, -1 on failure
112  */
113 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source);
114
115 /*! \brief Destroys an audiohook structure
116  * \param audiohook Audiohook structure
117  * \return Returns 0 on success, -1 on failure
118  */
119 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
120
121 /*! \brief Writes a frame into the audiohook structure
122  * \param audiohook Audiohook structure
123  * \param direction Direction the audio frame came from
124  * \param frame Frame to write in
125  * \return Returns 0 on success, -1 on failure
126  */
127 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
128
129 /*! \brief Reads a frame in from the audiohook structure
130  * \param audiohook Audiohook structure
131  * \param samples Number of samples wanted
132  * \param direction Direction the audio frame came from
133  * \param format Format of frame remote side wants back
134  * \return Returns frame on success, NULL on failure
135  */
136 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, format_t format);
137
138 /*! \brief Attach audiohook to channel
139  * \param chan Channel
140  * \param audiohook Audiohook structure
141  * \return Returns 0 on success, -1 on failure
142  */
143 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
144
145 /*! \brief Detach audiohook from channel
146  * \param audiohook Audiohook structure
147  * \return Returns 0 on success, -1 on failure
148  */
149 int ast_audiohook_detach(struct ast_audiohook *audiohook);
150
151 /*! \brief Detach audiohooks from list and destroy said list
152  * \param audiohook_list List of audiohooks
153  * \return Returns 0 on success, -1 on failure
154  */
155 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
156
157 /*! \brief Move an audiohook from one channel to a new one
158  *
159  * \todo Currently only the first audiohook of a specific source found will be moved.
160  * We should add the capability to move multiple audiohooks from a single source as well.
161  *
162  * \note It is required that both old_chan and new_chan are locked prior to calling
163  * this function. Besides needing to protect the data within the channels, not locking
164  * these channels can lead to a potential deadlock
165  *
166  * \param old_chan The source of the audiohook to move
167  * \param new_chan The destination to which we want the audiohook to move
168  * \param source The source of the audiohook we want to move
169  */
170 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
171
172 /*!
173  * \brief Detach specified source audiohook from channel
174  *
175  * \param chan Channel to detach from
176  * \param source Name of source to detach
177  *
178  * \return Returns 0 on success, -1 on failure
179  *
180  * \note The channel does not need to be locked before calling this function.
181  */
182 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
183
184 /*!
185  * \brief Remove an audiohook from a specified channel
186  *
187  * \param chan Channel to remove from
188  * \param audiohook Audiohook to remove
189  *
190  * \return Returns 0 on success, -1 on failure
191  *
192  * \note The channel does not need to be locked before calling this function
193  */
194 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
195
196 /*! \brief Pass a frame off to be handled by the audiohook core
197  * \param chan Channel that the list is coming off of
198  * \param audiohook_list List of audiohooks
199  * \param direction Direction frame is coming in from
200  * \param frame The frame itself
201  * \return Return frame on success, NULL on failure
202  */
203 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);
204
205 /*! \brief Update audiohook's status
206  * \param audiohook Audiohook structure
207  * \param audiohook status enum
208  */
209 void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status);
210
211 /*! \brief Wait for audiohook trigger to be triggered
212  * \param audiohook Audiohook to wait on
213  */
214 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
215
216 /*!
217   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
218   \param chan The channel on which to find the spies
219   \param source The audiohook's source
220   \param type The type of audiohook
221   \return Return the number of audiohooks which are from the source specified
222
223   Note: Function performs nlocking.
224 */
225 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
226
227 /*!
228   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
229   \param chan The channel on which to find the spies
230   \param source The source of the audiohook
231   \param type The type of spy to look for
232   \return Return the number of running audiohooks which are from the source specified
233
234   Note: Function performs no locking.
235 */
236 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
237
238 /*! \brief Lock an audiohook
239  * \param ah Audiohook structure
240  */
241 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
242
243 /*! \brief Unlock an audiohook
244  * \param ah Audiohook structure
245  */
246 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
247
248 /*!
249  * \brief Adjust the volume on frames read from or written to a channel
250  * \param chan Channel to muck with
251  * \param direction Direction to set on
252  * \param volume Value to adjust the volume by
253  * \return Returns 0 on success, -1 on failure
254  * \since 1.6.1
255  */
256 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
257
258 /*!
259  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
260  * \param chan Channel to retrieve volume adjustment from
261  * \param direction Direction to retrieve
262  * \return Returns adjustment value
263  * \since 1.6.1
264  */
265 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
266
267 /*!
268  * \brief Adjust the volume on frames read from or written to a channel
269  * \param chan Channel to muck with
270  * \param direction Direction to increase
271  * \param volume Value to adjust the adjustment by
272  * \return Returns 0 on success, -1 on failure
273  * \since 1.6.1
274  */
275 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
276
277 #if defined(__cplusplus) || defined(c_plusplus)
278 }
279 #endif
280
281 #endif /* _ASTERISK_AUDIOHOOK_H */