00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@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 Asterisk PBX channel spy definitions 00021 */ 00022 00023 #ifndef _ASTERISK_CHANSPY_H 00024 #define _ASTERISK_CHANSPY_H 00025 00026 #if defined(__cplusplus) || defined(c_plusplus) 00027 extern "C" { 00028 #endif 00029 00030 #include "asterisk/linkedlists.h" 00031 00032 enum chanspy_states { 00033 CHANSPY_NEW = 0, /*!< spy not yet operating */ 00034 CHANSPY_RUNNING = 1, /*!< normal operation, spy is still operating */ 00035 CHANSPY_DONE = 2, /*!< spy is stopped and already removed from channel */ 00036 CHANSPY_STOP = 3, /*!< spy requested to stop, still attached to channel */ 00037 }; 00038 00039 enum chanspy_flags { 00040 CHANSPY_MIXAUDIO = (1 << 0), 00041 CHANSPY_READ_VOLADJUST = (1 << 1), 00042 CHANSPY_WRITE_VOLADJUST = (1 << 2), 00043 CHANSPY_FORMAT_AUDIO = (1 << 3), 00044 CHANSPY_TRIGGER_MODE = (3 << 4), 00045 CHANSPY_TRIGGER_READ = (1 << 4), 00046 CHANSPY_TRIGGER_WRITE = (2 << 4), 00047 CHANSPY_TRIGGER_NONE = (3 << 4), 00048 CHANSPY_TRIGGER_FLUSH = (1 << 6), 00049 }; 00050 00051 struct ast_channel_spy_queue { 00052 struct ast_frame *head; 00053 unsigned int samples; 00054 unsigned int format; 00055 }; 00056 00057 struct ast_channel_spy { 00058 AST_LIST_ENTRY(ast_channel_spy) list; 00059 ast_mutex_t lock; 00060 ast_cond_t trigger; 00061 struct ast_channel *chan; 00062 struct ast_channel_spy_queue read_queue; 00063 struct ast_channel_spy_queue write_queue; 00064 unsigned int flags; 00065 enum chanspy_states status; 00066 const char *type; 00067 /* The volume adjustment values are very straightforward: 00068 positive values cause the samples to be multiplied by that amount 00069 negative values cause the samples to be divided by the absolute value of that amount 00070 */ 00071 int read_vol_adjustment; 00072 int write_vol_adjustment; 00073 }; 00074 00075 /*! 00076 \brief Adds a spy to a channel, to begin receiving copies of the channel's audio frames. 00077 \param chan The channel to add the spy to. 00078 \param spy A pointer to ast_channel_spy structure describing how the spy is to be used. 00079 \return 0 for success, non-zero for failure 00080 00081 Note: This function performs no locking; you must hold the channel's lock before 00082 calling this function. 00083 */ 00084 int ast_channel_spy_add(struct ast_channel *chan, struct ast_channel_spy *spy); 00085 00086 /*! 00087 \brief Remove a spy from a channel. 00088 \param chan The channel to remove the spy from 00089 \param spy The spy to be removed 00090 \return nothing 00091 00092 Note: This function performs no locking; you must hold the channel's lock before 00093 calling this function. 00094 */ 00095 void ast_channel_spy_remove(struct ast_channel *chan, struct ast_channel_spy *spy); 00096 00097 /*! 00098 \brief Free a spy. 00099 \param spy The spy to free 00100 \return nothing 00101 00102 Note: This function MUST NOT be called with the spy locked. 00103 */ 00104 void ast_channel_spy_free(struct ast_channel_spy *spy); 00105 00106 /*! 00107 \brief Find all spies of a particular type on a channel and stop them. 00108 \param chan The channel to operate on 00109 \param type A character string identifying the type of spies to be stopped 00110 \return nothing 00111 00112 Note: This function performs no locking; you must hold the channel's lock before 00113 calling this function. 00114 */ 00115 void ast_channel_spy_stop_by_type(struct ast_channel *chan, const char *type); 00116 00117 /*! 00118 \brief Read one (or more) frames of audio from a channel being spied upon. 00119 \param spy The spy to operate on 00120 \param samples The number of audio samples to read 00121 \return NULL for failure, one ast_frame pointer, or a chain of ast_frame pointers 00122 00123 This function can return multiple frames if the spy structure needs to be 'flushed' 00124 due to mismatched queue lengths, or if the spy structure is configured to return 00125 unmixed audio (in which case each call to this function will return a frame of audio 00126 from each side of channel). 00127 00128 Note: This function performs no locking; you must hold the spy's lock before calling 00129 this function. You must <b>not</b> hold the channel's lock at the same time. 00130 */ 00131 struct ast_frame *ast_channel_spy_read_frame(struct ast_channel_spy *spy, unsigned int samples); 00132 00133 /*! 00134 \brief Efficiently wait until audio is available for a spy, or an exception occurs. 00135 \param spy The spy to wait on 00136 \return nothing 00137 00138 Note: The locking rules for this function are non-obvious... first, you must <b>not</b> 00139 hold the channel's lock when calling this function. Second, you must hold the spy's lock 00140 before making the function call; while the function runs the lock will be released, and 00141 when the trigger event occurs, the lock will be re-obtained. This means that when control 00142 returns to your code, you will again hold the spy's lock. 00143 */ 00144 void ast_channel_spy_trigger_wait(struct ast_channel_spy *spy); 00145 00146 #if defined(__cplusplus) || defined(c_plusplus) 00147 } 00148 #endif 00149 00150 #endif /* _ASTERISK_CHANSPY_H */