00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2007, Digium, Inc. 00005 * 00006 * Joshua Colp <jcolp@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Audiohooks Architecture 00021 */ 00022 00023 #ifndef _ASTERISK_AUDIOHOOK_H 00024 #define _ASTERISK_AUDIOHOOK_H 00025 00026 #if defined(__cplusplus) || defined(c_plusplus) 00027 extern "C" { 00028 #endif 00029 00030 /* these two are used in struct ast_audiohook */ 00031 #include "asterisk/lock.h" 00032 #include "asterisk/linkedlists.h" 00033 #include "asterisk/frame_defs.h" 00034 #include "asterisk/slinfactory.h" 00035 00036 enum ast_audiohook_type { 00037 AST_AUDIOHOOK_TYPE_SPY = 0, /*!< Audiohook wants to receive audio */ 00038 AST_AUDIOHOOK_TYPE_WHISPER, /*!< Audiohook wants to provide audio to be mixed with existing audio */ 00039 AST_AUDIOHOOK_TYPE_MANIPULATE, /*!< Audiohook wants to manipulate the audio */ 00040 }; 00041 00042 enum ast_audiohook_status { 00043 AST_AUDIOHOOK_STATUS_NEW = 0, /*!< Audiohook was just created, not in use yet */ 00044 AST_AUDIOHOOK_STATUS_RUNNING, /*!< Audiohook is running on a channel */ 00045 AST_AUDIOHOOK_STATUS_SHUTDOWN, /*!< Audiohook is being shutdown */ 00046 AST_AUDIOHOOK_STATUS_DONE, /*!< Audiohook has shutdown and is not running on a channel any longer */ 00047 }; 00048 00049 enum ast_audiohook_direction { 00050 AST_AUDIOHOOK_DIRECTION_READ = 0, /*!< Reading audio in */ 00051 AST_AUDIOHOOK_DIRECTION_WRITE, /*!< Writing audio out */ 00052 AST_AUDIOHOOK_DIRECTION_BOTH, /*!< Both reading audio in and writing audio out */ 00053 }; 00054 00055 enum ast_audiohook_flags { 00056 AST_AUDIOHOOK_TRIGGER_MODE = (3 << 0), /*!< When audiohook should be triggered to do something */ 00057 AST_AUDIOHOOK_TRIGGER_READ = (1 << 0), /*!< Audiohook wants to be triggered when reading audio in */ 00058 AST_AUDIOHOOK_TRIGGER_WRITE = (2 << 0), /*!< Audiohook wants to be triggered when writing audio out */ 00059 AST_AUDIOHOOK_WANTS_DTMF = (1 << 1), /*!< Audiohook also wants to receive DTMF frames */ 00060 AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2), /*!< Audiohook wants to be triggered when both sides have combined audio available */ 00061 /*! Audiohooks with this flag set will not allow for a large amount of samples to build up on its 00062 * slinfactories. We will flush the factories if they contain too many samples. 00063 */ 00064 AST_AUDIOHOOK_SMALL_QUEUE = (1 << 3), 00065 AST_AUDIOHOOK_MUTE_READ = (1 << 4), /*!< audiohook should be mute frames read */ 00066 AST_AUDIOHOOK_MUTE_WRITE = (1 << 5), /*!< audiohook should be mute frames written */ 00067 }; 00068 00069 #define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */ 00070 00071 struct ast_audiohook; 00072 00073 /*! \brief Callback function for manipulate audiohook type 00074 * \param audiohook Audiohook structure 00075 * \param chan Channel 00076 * \param frame Frame of audio to manipulate 00077 * \param direction Direction frame came from 00078 * \return Returns 0 on success, -1 on failure. 00079 * \note An audiohook does not have any reference to a private data structure for manipulate 00080 * types. It is up to the manipulate callback to store this data via it's own method. 00081 * An example would be datastores. 00082 * \note The input frame should never be freed or corrupted during a manipulate callback. 00083 * If the callback has the potential to corrupt the frame's data during manipulation, 00084 * local data should be used for the manipulation and only copied to the frame on 00085 * success. 00086 * \note A failure return value indicates that the frame was not manipulated and that 00087 * is being returned in its original state. 00088 */ 00089 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction); 00090 00091 struct ast_audiohook_options { 00092 int read_volume; /*!< Volume adjustment on frames read from the channel the hook is on */ 00093 int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */ 00094 }; 00095 00096 struct ast_audiohook { 00097 ast_mutex_t lock; /*!< Lock that protects the audiohook structure */ 00098 ast_cond_t trigger; /*!< Trigger condition (if enabled) */ 00099 enum ast_audiohook_type type; /*!< Type of audiohook */ 00100 enum ast_audiohook_status status; /*!< Status of the audiohook */ 00101 const char *source; /*!< Who this audiohook ultimately belongs to */ 00102 unsigned int flags; /*!< Flags on the audiohook */ 00103 struct ast_slinfactory read_factory; /*!< Factory where frames read from the channel, or read from the whisper source will go through */ 00104 struct ast_slinfactory write_factory; /*!< Factory where frames written to the channel will go through */ 00105 struct timeval read_time; /*!< Last time read factory was fed */ 00106 struct timeval write_time; /*!< Last time write factory was fed */ 00107 int format; /*!< Format translation path is setup as */ 00108 struct ast_trans_pvt *trans_pvt; /*!< Translation path for reading frames */ 00109 ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */ 00110 struct ast_audiohook_options options; /*!< Applicable options */ 00111 AST_LIST_ENTRY(ast_audiohook) list; /*!< Linked list information */ 00112 }; 00113 00114 struct ast_audiohook_list; 00115 00116 /*! \brief Initialize an audiohook structure 00117 * \param audiohook Audiohook structure 00118 * \param type Type of audiohook to initialize this as 00119 * \param source Who is initializing this audiohook 00120 * \return Returns 0 on success, -1 on failure 00121 */ 00122 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source); 00123 00124 /*! \brief Destroys an audiohook structure 00125 * \param audiohook Audiohook structure 00126 * \return Returns 0 on success, -1 on failure 00127 */ 00128 int ast_audiohook_destroy(struct ast_audiohook *audiohook); 00129 00130 /*! \brief Writes a frame into the audiohook structure 00131 * \param audiohook Audiohook structure 00132 * \param direction Direction the audio frame came from 00133 * \param frame Frame to write in 00134 * \return Returns 0 on success, -1 on failure 00135 */ 00136 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame); 00137 00138 /*! \brief Reads a frame in from the audiohook structure 00139 * \param audiohook Audiohook structure 00140 * \param samples Number of samples wanted 00141 * \param direction Direction the audio frame came from 00142 * \param format Format of frame remote side wants back 00143 * \return Returns frame on success, NULL on failure 00144 */ 00145 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, format_t format); 00146 00147 /*! \brief Attach audiohook to channel 00148 * \param chan Channel 00149 * \param audiohook Audiohook structure 00150 * \return Returns 0 on success, -1 on failure 00151 */ 00152 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook); 00153 00154 /*! \brief Detach audiohook from channel 00155 * \param audiohook Audiohook structure 00156 * \return Returns 0 on success, -1 on failure 00157 */ 00158 int ast_audiohook_detach(struct ast_audiohook *audiohook); 00159 00160 /*! \brief Detach audiohooks from list and destroy said list 00161 * \param audiohook_list List of audiohooks 00162 * \return Returns 0 on success, -1 on failure 00163 */ 00164 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list); 00165 00166 /*! \brief Move an audiohook from one channel to a new one 00167 * 00168 * \todo Currently only the first audiohook of a specific source found will be moved. 00169 * We should add the capability to move multiple audiohooks from a single source as well. 00170 * 00171 * \note It is required that both old_chan and new_chan are locked prior to calling 00172 * this function. Besides needing to protect the data within the channels, not locking 00173 * these channels can lead to a potential deadlock 00174 * 00175 * \param old_chan The source of the audiohook to move 00176 * \param new_chan The destination to which we want the audiohook to move 00177 * \param source The source of the audiohook we want to move 00178 */ 00179 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source); 00180 00181 /*! 00182 * \brief Detach specified source audiohook from channel 00183 * 00184 * \param chan Channel to detach from 00185 * \param source Name of source to detach 00186 * 00187 * \return Returns 0 on success, -1 on failure 00188 * 00189 * \note The channel does not need to be locked before calling this function. 00190 */ 00191 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source); 00192 00193 /*! 00194 * \brief Remove an audiohook from a specified channel 00195 * 00196 * \param chan Channel to remove from 00197 * \param audiohook Audiohook to remove 00198 * 00199 * \return Returns 0 on success, -1 on failure 00200 * 00201 * \note The channel does not need to be locked before calling this function 00202 */ 00203 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook); 00204 00205 /*! 00206 * \brief determines if a audiohook_list is empty or not. 00207 * 00208 * retval 0 false, 1 true 00209 */ 00210 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list); 00211 00212 /*! \brief Pass a frame off to be handled by the audiohook core 00213 * \param chan Channel that the list is coming off of 00214 * \param audiohook_list List of audiohooks 00215 * \param direction Direction frame is coming in from 00216 * \param frame The frame itself 00217 * \return Return frame on success, NULL on failure 00218 */ 00219 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); 00220 00221 /*! \brief Update audiohook's status 00222 * \param audiohook Audiohook structure 00223 * \param audiohook status enum 00224 * 00225 * \note once status is updated to DONE, this function can not be used to set the 00226 * status back to any other setting. Setting DONE effectively locks the status as such. 00227 */ 00228 void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status); 00229 00230 /*! \brief Wait for audiohook trigger to be triggered 00231 * \param audiohook Audiohook to wait on 00232 */ 00233 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook); 00234 00235 /*! 00236 \brief Find out how many audiohooks from a certain source exist on a given channel, regardless of status. 00237 \param chan The channel on which to find the spies 00238 \param source The audiohook's source 00239 \param type The type of audiohook 00240 \return Return the number of audiohooks which are from the source specified 00241 00242 Note: Function performs nlocking. 00243 */ 00244 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type); 00245 00246 /*! 00247 \brief Find out how many spies of a certain type exist on a given channel, and are in state running. 00248 \param chan The channel on which to find the spies 00249 \param source The source of the audiohook 00250 \param type The type of spy to look for 00251 \return Return the number of running audiohooks which are from the source specified 00252 00253 Note: Function performs no locking. 00254 */ 00255 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type); 00256 00257 /*! \brief Lock an audiohook 00258 * \param ah Audiohook structure 00259 */ 00260 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock) 00261 00262 /*! \brief Unlock an audiohook 00263 * \param ah Audiohook structure 00264 */ 00265 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock) 00266 00267 /*! 00268 * \brief Adjust the volume on frames read from or written to a channel 00269 * \param chan Channel to muck with 00270 * \param direction Direction to set on 00271 * \param volume Value to adjust the volume by 00272 * \return Returns 0 on success, -1 on failure 00273 * \since 1.6.1 00274 */ 00275 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume); 00276 00277 /*! 00278 * \brief Retrieve the volume adjustment value on frames read from or written to a channel 00279 * \param chan Channel to retrieve volume adjustment from 00280 * \param direction Direction to retrieve 00281 * \return Returns adjustment value 00282 * \since 1.6.1 00283 */ 00284 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction); 00285 00286 /*! 00287 * \brief Adjust the volume on frames read from or written to a channel 00288 * \param chan Channel to muck with 00289 * \param direction Direction to increase 00290 * \param volume Value to adjust the adjustment by 00291 * \return Returns 0 on success, -1 on failure 00292 * \since 1.6.1 00293 */ 00294 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume); 00295 00296 /*! \brief Mute frames read from or written to a channel 00297 * \param chan Channel to muck with 00298 * \param source Type of audiohook 00299 * \param flag which direction to set / clear 00300 * \param clear set or clear muted frames on direction based on flag parameter 00301 * \retval 0 success 00302 * \retval -1 failure 00303 */ 00304 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear); 00305 00306 #if defined(__cplusplus) || defined(c_plusplus) 00307 } 00308 #endif 00309 00310 #endif /* _ASTERISK_AUDIOHOOK_H */