audiohook.h

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

Generated on Thu Apr 16 06:27:15 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6