Mon Oct 8 12:38:58 2012

Asterisk developer's documentation


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/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 /*
00056  * The flags here have been shifted around due to an unintended overlap between
00057  * AST_AUDIOHOOK_TRIGGER_WRITE and AST_AUDIOHOOK_WANTS_DTMF.  In future Asterisk
00058  * releases (Asterisk 11+), these have been reorganized to make more sense.
00059  */
00060 enum ast_audiohook_flags {
00061    AST_AUDIOHOOK_TRIGGER_MODE = ((1 << 6) | (1 << 0)),  /*!< When audiohook should be triggered to do something */
00062    AST_AUDIOHOOK_TRIGGER_READ = (1 << 0),  /*!< Audiohook wants to be triggered when reading audio in */
00063    AST_AUDIOHOOK_TRIGGER_WRITE = (1 << 6), /*!< Audiohook wants to be triggered when writing audio out */
00064    AST_AUDIOHOOK_WANTS_DTMF = (1 << 1),    /*!< Audiohook also wants to receive DTMF frames */
00065    AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2),  /*!< Audiohook wants to be triggered when both sides have combined audio available */
00066    /*! Audiohooks with this flag set will not allow for a large amount of samples to build up on its
00067     * slinfactories. We will flush the factories if they contain too many samples.
00068     */
00069    AST_AUDIOHOOK_SMALL_QUEUE = (1 << 3),
00070    AST_AUDIOHOOK_MUTE_READ = (1 << 4),     /*!< audiohook should be mute frames read */
00071    AST_AUDIOHOOK_MUTE_WRITE = (1 << 5),    /*!< audiohook should be mute frames written */
00072 
00073    /* IMPORTANT: When adding new flags, start with (1 << 7) */
00074 };
00075 
00076 #define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */
00077 
00078 struct ast_audiohook;
00079 
00080 /*! \brief Callback function for manipulate audiohook type
00081  * \param audiohook Audiohook structure
00082  * \param chan Channel
00083  * \param frame Frame of audio to manipulate
00084  * \param direction Direction frame came from
00085  * \return Returns 0 on success, -1 on failure.
00086  * \note An audiohook does not have any reference to a private data structure for manipulate
00087  *       types. It is up to the manipulate callback to store this data via it's own method.
00088  *       An example would be datastores.
00089  * \note The input frame should never be freed or corrupted during a manipulate callback.
00090  *       If the callback has the potential to corrupt the frame's data during manipulation,
00091  *       local data should be used for the manipulation and only copied to the frame on
00092  *       success.
00093  * \note A failure return value indicates that the frame was not manipulated and that
00094  *       is being returned in its original state.
00095  */
00096 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
00097 
00098 struct ast_audiohook_options {
00099    int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
00100    int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
00101 };
00102 
00103 struct ast_audiohook {
00104    ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
00105    ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
00106    enum ast_audiohook_type type;                          /*!< Type of audiohook */
00107    enum ast_audiohook_status status;                      /*!< Status of the audiohook */
00108    const char *source;                                    /*!< Who this audiohook ultimately belongs to */
00109    unsigned int flags;                                    /*!< Flags on the audiohook */
00110    struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
00111    struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
00112    struct timeval read_time;                              /*!< Last time read factory was fed */
00113    struct timeval write_time;                             /*!< Last time write factory was fed */
00114    int format;                                            /*!< Format translation path is setup as */
00115    struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
00116    ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
00117    struct ast_audiohook_options options;                  /*!< Applicable options */
00118    AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
00119 };
00120 
00121 struct ast_audiohook_list;
00122 
00123 /*! \brief Initialize an audiohook structure
00124  * \param audiohook Audiohook structure
00125  * \param type Type of audiohook to initialize this as
00126  * \param source Who is initializing this audiohook
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);
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, format_t format);
00153 
00154 /*! \brief Attach audiohook to channel
00155  * \param chan Channel
00156  * \param audiohook Audiohook structure
00157  * \return Returns 0 on success, -1 on failure
00158  */
00159 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
00160 
00161 /*! \brief Detach audiohook from channel
00162  * \param audiohook Audiohook structure
00163  * \return Returns 0 on success, -1 on failure
00164  */
00165 int ast_audiohook_detach(struct ast_audiohook *audiohook);
00166 
00167 /*! \brief Detach audiohooks from list and destroy said list
00168  * \param audiohook_list List of audiohooks
00169  * \return Returns 0 on success, -1 on failure
00170  */
00171 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
00172 
00173 /*! \brief Move an audiohook from one channel to a new one
00174  *
00175  * \todo Currently only the first audiohook of a specific source found will be moved.
00176  * We should add the capability to move multiple audiohooks from a single source as well.
00177  *
00178  * \note It is required that both old_chan and new_chan are locked prior to calling
00179  * this function. Besides needing to protect the data within the channels, not locking
00180  * these channels can lead to a potential deadlock
00181  *
00182  * \param old_chan The source of the audiohook to move
00183  * \param new_chan The destination to which we want the audiohook to move
00184  * \param source The source of the audiohook we want to move
00185  */
00186 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
00187 
00188 /*!
00189  * \brief Detach specified source audiohook from channel
00190  *
00191  * \param chan Channel to detach from
00192  * \param source Name of source to detach
00193  *
00194  * \return Returns 0 on success, -1 on failure
00195  *
00196  * \note The channel does not need to be locked before calling this function.
00197  */
00198 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
00199 
00200 /*!
00201  * \brief Remove an audiohook from a specified channel
00202  *
00203  * \param chan Channel to remove from
00204  * \param audiohook Audiohook to remove
00205  *
00206  * \return Returns 0 on success, -1 on failure
00207  *
00208  * \note The channel does not need to be locked before calling this function
00209  */
00210 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
00211 
00212 /*!
00213  * \brief determines if a audiohook_list is empty or not.
00214  *
00215  * retval 0 false, 1 true
00216  */
00217 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
00218 
00219 /*! \brief Pass a frame off to be handled by the audiohook core
00220  * \param chan Channel that the list is coming off of
00221  * \param audiohook_list List of audiohooks
00222  * \param direction Direction frame is coming in from
00223  * \param frame The frame itself
00224  * \return Return frame on success, NULL on failure
00225  */
00226 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);
00227 
00228 /*! \brief Update audiohook's status
00229  * \param audiohook Audiohook structure
00230  * \param audiohook status enum
00231  *
00232  * \note once status is updated to DONE, this function can not be used to set the
00233  * status back to any other setting.  Setting DONE effectively locks the status as such.
00234  */
00235 void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status);
00236 
00237 /*! \brief Wait for audiohook trigger to be triggered
00238  * \param audiohook Audiohook to wait on
00239  */
00240 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
00241 
00242 /*!
00243   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
00244   \param chan The channel on which to find the spies
00245   \param source The audiohook's source
00246   \param type The type of audiohook
00247   \return Return the number of audiohooks which are from the source specified
00248 
00249   Note: Function performs nlocking.
00250 */
00251 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
00252 
00253 /*!
00254   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
00255   \param chan The channel on which to find the spies
00256   \param source The source of the audiohook
00257   \param type The type of spy to look for
00258   \return Return the number of running audiohooks which are from the source specified
00259 
00260   Note: Function performs no locking.
00261 */
00262 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
00263 
00264 /*! \brief Lock an audiohook
00265  * \param ah Audiohook structure
00266  */
00267 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
00268 
00269 /*! \brief Unlock an audiohook
00270  * \param ah Audiohook structure
00271  */
00272 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
00273 
00274 /*!
00275  * \brief Adjust the volume on frames read from or written to a channel
00276  * \param chan Channel to muck with
00277  * \param direction Direction to set on
00278  * \param volume Value to adjust the volume by
00279  * \return Returns 0 on success, -1 on failure
00280  * \since 1.6.1
00281  */
00282 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
00283 
00284 /*!
00285  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
00286  * \param chan Channel to retrieve volume adjustment from
00287  * \param direction Direction to retrieve
00288  * \return Returns adjustment value
00289  * \since 1.6.1
00290  */
00291 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
00292 
00293 /*!
00294  * \brief Adjust the volume on frames read from or written to a channel
00295  * \param chan Channel to muck with
00296  * \param direction Direction to increase
00297  * \param volume Value to adjust the adjustment by
00298  * \return Returns 0 on success, -1 on failure
00299  * \since 1.6.1
00300  */
00301 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
00302 
00303 /*! \brief Mute frames read from or written to a channel
00304  * \param chan Channel to muck with
00305  * \param source Type of audiohook
00306  * \param flag which direction to set / clear
00307  * \param clear set or clear muted frames on direction based on flag parameter
00308  * \retval 0 success
00309  * \retval -1 failure
00310  */
00311 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear);
00312 
00313 #if defined(__cplusplus) || defined(c_plusplus)
00314 }
00315 #endif
00316 
00317 #endif /* _ASTERISK_AUDIOHOOK_H */

Generated on Mon Oct 8 12:38:58 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7