Fri Jul 24 00:40:44 2009

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 
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 };
00062 
00063 #define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */
00064 
00065 struct ast_audiohook;
00066 
00067 /*! \brief Callback function for manipulate audiohook type
00068  * \param audiohook Audiohook structure
00069  * \param chan Channel
00070  * \param frame Frame of audio to manipulate
00071  * \param direction Direction frame came from
00072  * \return Returns 0 on success, -1 on failure
00073  * \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
00074  *       via it's own method. An example would be datastores.
00075  */
00076 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
00077 
00078 struct ast_audiohook_options {
00079    int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
00080    int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
00081 };
00082 
00083 struct ast_audiohook {
00084    ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
00085    ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
00086    enum ast_audiohook_type type;                          /*!< Type of audiohook */
00087    enum ast_audiohook_status status;                      /*!< Status of the audiohook */
00088    const char *source;                                    /*!< Who this audiohook ultimately belongs to */
00089    unsigned int flags;                                    /*!< Flags on the audiohook */
00090    struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
00091    struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
00092    struct timeval read_time;                              /*!< Last time read factory was fed */
00093    struct timeval write_time;                             /*!< Last time write factory was fed */
00094    int format;                                            /*!< Format translation path is setup as */
00095    struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
00096    ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
00097    struct ast_audiohook_options options;                  /*!< Applicable options */
00098    AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
00099 };
00100 
00101 struct ast_audiohook_list;
00102 
00103 /*! \brief Initialize an audiohook structure
00104  * \param audiohook Audiohook structure
00105  * \param type Type of audiohook to initialize this as
00106  * \param source Who is initializing this audiohook
00107  * \return Returns 0 on success, -1 on failure
00108  */
00109 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source);
00110 
00111 /*! \brief Destroys an audiohook structure
00112  * \param audiohook Audiohook structure
00113  * \return Returns 0 on success, -1 on failure
00114  */
00115 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
00116 
00117 /*! \brief Writes a frame into the audiohook structure
00118  * \param audiohook Audiohook structure
00119  * \param direction Direction the audio frame came from
00120  * \param frame Frame to write in
00121  * \return Returns 0 on success, -1 on failure
00122  */
00123 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
00124 
00125 /*! \brief Reads a frame in from the audiohook structure
00126  * \param audiohook Audiohook structure
00127  * \param samples Number of samples wanted
00128  * \param direction Direction the audio frame came from
00129  * \param format Format of frame remote side wants back
00130  * \return Returns frame on success, NULL on failure
00131  */
00132 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, int format);
00133 
00134 /*! \brief Attach audiohook to channel
00135  * \param chan Channel
00136  * \param audiohook Audiohook structure
00137  * \return Returns 0 on success, -1 on failure
00138  */
00139 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
00140 
00141 /*! \brief Detach audiohook from channel
00142  * \param audiohook Audiohook structure
00143  * \return Returns 0 on success, -1 on failure
00144  */
00145 int ast_audiohook_detach(struct ast_audiohook *audiohook);
00146 
00147 /*! \brief Detach audiohooks from list and destroy said list
00148  * \param audiohook_list List of audiohooks
00149  * \return Returns 0 on success, -1 on failure
00150  */
00151 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
00152 
00153 /*! \brief Move an audiohook from one channel to a new one
00154  *
00155  * \todo Currently only the first audiohook of a specific source found will be moved.
00156  * We should add the capability to move multiple audiohooks from a single source as well.
00157  *
00158  * \note It is required that both old_chan and new_chan are locked prior to calling
00159  * this function. Besides needing to protect the data within the channels, not locking
00160  * these channels can lead to a potential deadlock
00161  *
00162  * \param old_chan The source of the audiohook to move
00163  * \param new_chan The destination to which we want the audiohook to move
00164  * \param source The source of the audiohook we want to move
00165  */
00166 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
00167 
00168 /*!
00169  * \brief Detach specified source audiohook from channel
00170  *
00171  * \param chan Channel to detach from
00172  * \param source Name of source to detach
00173  *
00174  * \return Returns 0 on success, -1 on failure
00175  *
00176  * \note The channel does not need to be locked before calling this function.
00177  */
00178 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
00179 
00180 /*!
00181  * \brief Remove an audiohook from a specified channel
00182  *
00183  * \param chan Channel to remove from
00184  * \param audiohook Audiohook to remove
00185  *
00186  * \return Returns 0 on success, -1 on failure
00187  *
00188  * \note The channel does not need to be locked before calling this function
00189  */
00190 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
00191 
00192 /*! \brief Pass a frame off to be handled by the audiohook core
00193  * \param chan Channel that the list is coming off of
00194  * \param audiohook_list List of audiohooks
00195  * \param direction Direction frame is coming in from
00196  * \param frame The frame itself
00197  * \return Return frame on success, NULL on failure
00198  */
00199 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);
00200 
00201 /*! \brief Wait for audiohook trigger to be triggered
00202  * \param audiohook Audiohook to wait on
00203  */
00204 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
00205 
00206 /*!
00207   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
00208   \param chan The channel on which to find the spies
00209   \param source The audiohook's source
00210   \param type The type of audiohook
00211   \return Return the number of audiohooks which are from the source specified
00212 
00213   Note: Function performs nlocking.
00214 */
00215 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
00216 
00217 /*!
00218   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
00219   \param chan The channel on which to find the spies
00220   \param source The source of the audiohook
00221   \param type The type of spy to look for
00222   \return Return the number of running audiohooks which are from the source specified
00223 
00224   Note: Function performs no locking.
00225 */
00226 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
00227 
00228 /*! \brief Lock an audiohook
00229  * \param ah Audiohook structure
00230  */
00231 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
00232 
00233 /*! \brief Unlock an audiohook
00234  * \param ah Audiohook structure
00235  */
00236 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
00237 
00238 /*!
00239  * \brief Adjust the volume on frames read from or written to a channel
00240  * \param chan Channel to muck with
00241  * \param direction Direction to set on
00242  * \param volume Value to adjust the volume by
00243  * \return Returns 0 on success, -1 on failure
00244  * \since 1.6.1
00245  */
00246 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
00247 
00248 /*!
00249  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
00250  * \param chan Channel to retrieve volume adjustment from
00251  * \param direction Direction to retrieve
00252  * \return Returns adjustment value
00253  * \since 1.6.1
00254  */
00255 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
00256 
00257 /*!
00258  * \brief Adjust the volume on frames read from or written to a channel
00259  * \param chan Channel to muck with
00260  * \param direction Direction to increase
00261  * \param volume Value to adjust the adjustment by
00262  * \return Returns 0 on success, -1 on failure
00263  * \since 1.6.1
00264  */
00265 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
00266 
00267 #if defined(__cplusplus) || defined(c_plusplus)
00268 }
00269 #endif
00270 
00271 #endif /* _ASTERISK_AUDIOHOOK_H */

Generated on Fri Jul 24 00:40:44 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7