5ef0ac29432a4ea03fd339f4f4d9bd15ae10cb38
[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
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 };
61
62 struct ast_audiohook;
63
64 /*! \brief Callback function for manipulate audiohook type
65  * \param audiohook Audiohook structure
66  * \param chan Channel
67  * \param frame Frame of audio to manipulate
68  * \param direction Direction frame came from
69  * \return Returns 0 on success, -1 on failure
70  * \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
71  *       via it's own method. An example would be datastores.
72  */
73 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
74
75 struct ast_audiohook_options {
76         int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
77         int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
78 };
79
80 struct ast_audiohook {
81         ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
82         ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
83         enum ast_audiohook_type type;                          /*!< Type of audiohook */
84         enum ast_audiohook_status status;                      /*!< Status of the audiohook */
85         const char *source;                                    /*!< Who this audiohook ultimately belongs to */
86         unsigned int flags;                                    /*!< Flags on the audiohook */
87         struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
88         struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
89         int format;                                            /*!< Format translation path is setup as */
90         struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
91         ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
92         struct ast_audiohook_options options;                  /*!< Applicable options */
93         AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
94 };
95
96 struct ast_audiohook_list;
97
98 /*! \brief Initialize an audiohook structure
99  * \param audiohook Audiohook structure
100  * \param type Type of audiohook to initialize this as
101  * \param source Who is initializing this audiohook
102  * \return Returns 0 on success, -1 on failure
103  */
104 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source);
105
106 /*! \brief Destroys an audiohook structure
107  * \param audiohook Audiohook structure
108  * \return Returns 0 on success, -1 on failure
109  */
110 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
111
112 /*! \brief Writes a frame into the audiohook structure
113  * \param audiohook Audiohook structure
114  * \param direction Direction the audio frame came from
115  * \param frame Frame to write in
116  * \return Returns 0 on success, -1 on failure
117  */
118 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
119
120 /*! \brief Reads a frame in from the audiohook structure
121  * \param audiohook Audiohook structure
122  * \param samples Number of samples wanted
123  * \param direction Direction the audio frame came from
124  * \param format Format of frame remote side wants back
125  * \return Returns frame on success, NULL on failure
126  */
127 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, int format);
128
129 /*! \brief Attach audiohook to channel
130  * \param chan Channel
131  * \param audiohook Audiohook structure
132  * \return Returns 0 on success, -1 on failure
133  */
134 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
135
136 /*! \brief Detach audiohook from channel
137  * \param audiohook Audiohook structure
138  * \return Returns 0 on success, -1 on failure
139  */
140 int ast_audiohook_detach(struct ast_audiohook *audiohook);
141
142 /*! \brief Detach audiohooks from list and destroy said list
143  * \param audiohook_list List of audiohooks
144  * \return Returns 0 on success, -1 on failure
145  */
146 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
147
148 /*! 
149  * \brief Detach specified source audiohook from channel
150  *
151  * \param chan Channel to detach from
152  * \param source Name of source to detach
153  *
154  * \return Returns 0 on success, -1 on failure
155  *
156  * \note The channel does not need to be locked before calling this function.
157  */
158 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
159
160 /*! \brief Pass a frame off to be handled by the audiohook core
161  * \param chan Channel that the list is coming off of
162  * \param audiohook_list List of audiohooks
163  * \param direction Direction frame is coming in from
164  * \param frame The frame itself
165  * \return Return frame on success, NULL on failure
166  */
167 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);
168
169 /*! \brief Wait for audiohook trigger to be triggered
170  * \param audiohook Audiohook to wait on
171  */
172 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
173
174 /*!
175   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
176   \param chan The channel on which to find the spies 
177   \param source The audiohook's source
178   \param type The type of audiohook 
179   \return Return the number of audiohooks which are from the source specified
180
181   Note: Function performs nlocking.
182 */
183 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
184
185 /*!
186   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
187   \param chan The channel on which to find the spies
188   \param source The source of the audiohook
189   \param type The type of spy to look for
190   \return Return the number of running audiohooks which are from the source specified
191
192   Note: Function performs no locking.
193 */
194 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
195
196 /*! \brief Lock an audiohook
197  * \param ah Audiohook structure
198  */
199 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
200
201 /*! \brief Unlock an audiohook
202  * \param ah Audiohook structure
203  */
204 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
205
206 #if defined(__cplusplus) || defined(c_plusplus)
207 }
208 #endif
209
210 #endif /* _ASTERISK_AUDIOHOOK_H */