00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2007 - 2009, 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 Channel Bridging API 00021 * \author Joshua Colp <jcolp@digium.com> 00022 * \ref AstBridging 00023 */ 00024 00025 /*! 00026 * \page AstBridging Channel Bridging API 00027 * 00028 * The purpose of this API is to provide an easy and flexible way to bridge 00029 * channels of different technologies with different features. 00030 * 00031 * Bridging technologies provide the mechanism that do the actual handling 00032 * of frames between channels. They provide capability information, codec information, 00033 * and preference value to assist the bridging core in choosing a bridging technology when 00034 * creating a bridge. Different bridges may use different bridging technologies based on needs 00035 * but once chosen they all operate under the same premise; they receive frames and send frames. 00036 * 00037 * Bridges are a combination of bridging technology, channels, and features. A 00038 * developer creates a new bridge based on what they are currently expecting to do 00039 * with it or what they will do with it in the future. The bridging core determines what 00040 * available bridging technology will best fit the requirements and creates a new bridge. 00041 * Once created, channels can be added to the bridge in a blocking or non-blocking fashion. 00042 * 00043 * Features are such things as channel muting or DTMF based features such as attended transfer, 00044 * blind transfer, and hangup. Feature information must be set at the most granular level, on 00045 * the channel. While you can use features on a global scope the presence of a feature structure 00046 * on the channel will override the global scope. An example would be having the bridge muted 00047 * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted 00048 * it would be able to speak. 00049 * 00050 * Feature hooks allow a developer to tell the bridging core that when a DTMF string 00051 * is received from a channel a callback should be called in their application. For 00052 * example, a conference bridge application may want to provide an IVR to control various 00053 * settings on the conference bridge. This can be accomplished by attaching a feature hook 00054 * that calls an IVR function when a DTMF string is entered. 00055 * 00056 */ 00057 00058 #ifndef _ASTERISK_BRIDGING_H 00059 #define _ASTERISK_BRIDGING_H 00060 00061 #if defined(__cplusplus) || defined(c_plusplus) 00062 extern "C" { 00063 #endif 00064 00065 #include "asterisk/bridging_features.h" 00066 00067 /*! \brief Capabilities for a bridge technology */ 00068 enum ast_bridge_capability { 00069 /*! Bridge is only capable of mixing 2 channels */ 00070 AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1), 00071 /*! Bridge is capable of mixing 2 or more channels */ 00072 AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2), 00073 /*! Bridge should natively bridge two channels if possible */ 00074 AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3), 00075 /*! Bridge should run using the multithreaded model */ 00076 AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4), 00077 /*! Bridge should run a central bridge thread */ 00078 AST_BRIDGE_CAPABILITY_THREAD = (1 << 5), 00079 /*! Bridge technology can do video mixing (or something along those lines) */ 00080 AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6), 00081 /*! Bridge technology can optimize things based on who is talking */ 00082 AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7), 00083 }; 00084 00085 /*! \brief State information about a bridged channel */ 00086 enum ast_bridge_channel_state { 00087 /*! Waiting for a signal */ 00088 AST_BRIDGE_CHANNEL_STATE_WAIT = 0, 00089 /*! Bridged channel has ended itself (it has hung up) */ 00090 AST_BRIDGE_CHANNEL_STATE_END, 00091 /*! Bridged channel should be hung up */ 00092 AST_BRIDGE_CHANNEL_STATE_HANGUP, 00093 /*! Bridged channel should be removed from the bridge without being hung up */ 00094 AST_BRIDGE_CHANNEL_STATE_DEPART, 00095 /*! Bridged channel is executing a feature hook */ 00096 AST_BRIDGE_CHANNEL_STATE_FEATURE, 00097 /*! Bridged channel is sending a DTMF stream out */ 00098 AST_BRIDGE_CHANNEL_STATE_DTMF, 00099 }; 00100 00101 /*! \brief Return values for bridge technology write function */ 00102 enum ast_bridge_write_result { 00103 /*! Bridge technology wrote out frame fine */ 00104 AST_BRIDGE_WRITE_SUCCESS = 0, 00105 /*! Bridge technology attempted to write out the frame but failed */ 00106 AST_BRIDGE_WRITE_FAILED, 00107 /*! Bridge technology does not support writing out a frame of this type */ 00108 AST_BRIDGE_WRITE_UNSUPPORTED, 00109 }; 00110 00111 struct ast_bridge_technology; 00112 struct ast_bridge; 00113 00114 /*! 00115 * \brief Structure that contains information regarding a channel in a bridge 00116 */ 00117 struct ast_bridge_channel { 00118 /*! Lock to protect this data structure */ 00119 ast_mutex_t lock; 00120 /*! Condition, used if we want to wake up a thread waiting on the bridged channel */ 00121 ast_cond_t cond; 00122 /*! Current bridged channel state */ 00123 enum ast_bridge_channel_state state; 00124 /*! Asterisk channel participating in the bridge */ 00125 struct ast_channel *chan; 00126 /*! Asterisk channel we are swapping with (if swapping) */ 00127 struct ast_channel *swap; 00128 /*! Bridge this channel is participating in */ 00129 struct ast_bridge *bridge; 00130 /*! Private information unique to the bridge technology */ 00131 void *bridge_pvt; 00132 /*! Thread handling the bridged channel */ 00133 pthread_t thread; 00134 /*! Additional file descriptors to look at */ 00135 int fds[4]; 00136 /*! Bit to indicate whether the channel is suspended from the bridge or not */ 00137 unsigned int suspended:1; 00138 /*! Features structure for features that are specific to this channel */ 00139 struct ast_bridge_features *features; 00140 /*! Queue of DTMF digits used for DTMF streaming */ 00141 char dtmf_stream_q[8]; 00142 /*! Linked list information */ 00143 AST_LIST_ENTRY(ast_bridge_channel) entry; 00144 }; 00145 00146 /*! 00147 * \brief Structure that contains information about a bridge 00148 */ 00149 struct ast_bridge { 00150 /*! Number of channels participating in the bridge */ 00151 int num; 00152 /*! Bit to indicate that the bridge thread is waiting on channels in the bridge array */ 00153 unsigned int waiting:1; 00154 /*! Bit to indicate the bridge thread should stop */ 00155 unsigned int stop:1; 00156 /*! Bit to indicate the bridge thread should refresh itself */ 00157 unsigned int refresh:1; 00158 /*! Bridge flags to tweak behavior */ 00159 struct ast_flags feature_flags; 00160 /*! Bridge technology that is handling the bridge */ 00161 struct ast_bridge_technology *technology; 00162 /*! Private information unique to the bridge technology */ 00163 void *bridge_pvt; 00164 /*! Thread running the bridge */ 00165 pthread_t thread; 00166 /*! Enabled features information */ 00167 struct ast_bridge_features features; 00168 /*! Array of channels that the bridge thread is currently handling */ 00169 struct ast_channel **array; 00170 /*! Number of channels in the above array */ 00171 size_t array_num; 00172 /*! Number of channels the array can handle */ 00173 size_t array_size; 00174 /*! Linked list of channels participating in the bridge */ 00175 AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels; 00176 }; 00177 00178 /*! \brief Create a new bridge 00179 * 00180 * \param capabilities The capabilities that we require to be used on the bridge 00181 * \param flags Flags that will alter the behavior of the bridge 00182 * 00183 * \retval a pointer to a new bridge on success 00184 * \retval NULL on failure 00185 * 00186 * Example usage: 00187 * 00188 * \code 00189 * struct ast_bridge *bridge; 00190 * bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE); 00191 * \endcode 00192 * 00193 * This creates a simple two party bridge that will be destroyed once one of 00194 * the channels hangs up. 00195 */ 00196 struct ast_bridge *ast_bridge_new(enum ast_bridge_capability capabilities, int flags); 00197 00198 /*! \brief See if it is possible to create a bridge 00199 * 00200 * \param capabilities The capabilities that the bridge will use 00201 * 00202 * \retval 1 if possible 00203 * \retval 0 if not possible 00204 * 00205 * Example usage: 00206 * 00207 * \code 00208 * int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX); 00209 * \endcode 00210 * 00211 * This sees if it is possible to create a bridge capable of bridging two channels 00212 * together. 00213 */ 00214 int ast_bridge_check(enum ast_bridge_capability capabilities); 00215 00216 /*! \brief Destroy a bridge 00217 * 00218 * \param bridge Bridge to destroy 00219 * 00220 * \retval 0 on success 00221 * \retval -1 on failure 00222 * 00223 * Example usage: 00224 * 00225 * \code 00226 * ast_bridge_destroy(bridge); 00227 * \endcode 00228 * 00229 * This destroys a bridge that was previously created using ast_bridge_new. 00230 */ 00231 int ast_bridge_destroy(struct ast_bridge *bridge); 00232 00233 /*! \brief Join (blocking) a channel to a bridge 00234 * 00235 * \param bridge Bridge to join 00236 * \param chan Channel to join 00237 * \param swap Channel to swap out if swapping 00238 * \param features Bridge features structure 00239 * 00240 * \retval state that channel exited the bridge with 00241 * 00242 * Example usage: 00243 * 00244 * \code 00245 * ast_bridge_join(bridge, chan, NULL, NULL); 00246 * \endcode 00247 * 00248 * This adds a channel pointed to by the chan pointer to the bridge pointed to by 00249 * the bridge pointer. This function will not return until the channel has been 00250 * removed from the bridge, swapped out for another channel, or has hung up. 00251 * 00252 * If this channel will be replacing another channel the other channel can be specified 00253 * in the swap parameter. The other channel will be thrown out of the bridge in an 00254 * atomic fashion. 00255 * 00256 * If channel specific features are enabled a pointer to the features structure 00257 * can be specified in the features parameter. 00258 */ 00259 enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features); 00260 00261 /*! \brief Impart (non-blocking) a channel on a bridge 00262 * 00263 * \param bridge Bridge to impart on 00264 * \param chan Channel to impart 00265 * \param swap Channel to swap out if swapping 00266 * \param features Bridge features structure 00267 * 00268 * \retval 0 on success 00269 * \retval -1 on failure 00270 * 00271 * Example usage: 00272 * 00273 * \code 00274 * ast_bridge_impart(bridge, chan, NULL, NULL); 00275 * \endcode 00276 * 00277 * This adds a channel pointed to by the chan pointer to the bridge pointed to by 00278 * the bridge pointer. This function will return immediately and will not wait 00279 * until the channel is no longer part of the bridge. 00280 * 00281 * If this channel will be replacing another channel the other channel can be specified 00282 * in the swap parameter. The other channel will be thrown out of the bridge in an 00283 * atomic fashion. 00284 * 00285 * If channel specific features are enabled a pointer to the features structure 00286 * can be specified in the features parameter. 00287 */ 00288 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features); 00289 00290 /*! \brief Depart a channel from a bridge 00291 * 00292 * \param bridge Bridge to depart from 00293 * \param chan Channel to depart 00294 * 00295 * \retval 0 on success 00296 * \retval -1 on failure 00297 * 00298 * Example usage: 00299 * 00300 * \code 00301 * ast_bridge_depart(bridge, chan); 00302 * \endcode 00303 * 00304 * This removes the channel pointed to by the chan pointer from the bridge 00305 * pointed to by the bridge pointer and gives control to the calling thread. 00306 * This does not hang up the channel. 00307 * 00308 * \note This API call can only be used on channels that were added to the bridge 00309 * using the ast_bridge_impart API call. 00310 */ 00311 int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan); 00312 00313 /*! \brief Remove a channel from a bridge 00314 * 00315 * \param bridge Bridge that the channel is to be removed from 00316 * \param chan Channel to remove 00317 * 00318 * \retval 0 on success 00319 * \retval -1 on failure 00320 * 00321 * Example usage: 00322 * 00323 * \code 00324 * ast_bridge_remove(bridge, chan); 00325 * \endcode 00326 * 00327 * This removes the channel pointed to by the chan pointer from the bridge 00328 * pointed to by the bridge pointer and requests that it be hung up. Control 00329 * over the channel will NOT be given to the calling thread. 00330 * 00331 * \note This API call can be used on channels that were added to the bridge 00332 * using both ast_bridge_join and ast_bridge_impart. 00333 */ 00334 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan); 00335 00336 /*! \brief Merge two bridges together 00337 * 00338 * \param bridge0 First bridge 00339 * \param bridge1 Second bridge 00340 * 00341 * \retval 0 on success 00342 * \retval -1 on failure 00343 * 00344 * Example usage: 00345 * 00346 * \code 00347 * ast_bridge_merge(bridge0, bridge1); 00348 * \endcode 00349 * 00350 * This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0. 00351 * In reality all of the channels in bridge1 are simply moved to bridge0. 00352 * 00353 * \note The second bridge specified is not destroyed when this operation is 00354 * completed. 00355 */ 00356 int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1); 00357 00358 /*! \brief Suspend a channel temporarily from a bridge 00359 * 00360 * \param bridge Bridge to suspend the channel from 00361 * \param chan Channel to suspend 00362 * 00363 * \retval 0 on success 00364 * \retval -1 on failure 00365 * 00366 * Example usage: 00367 * 00368 * \code 00369 * ast_bridge_suspend(bridge, chan); 00370 * \endcode 00371 * 00372 * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily. 00373 * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as 00374 * the channel will not be removed from the bridge. 00375 * 00376 * \note This API call can be used on channels that were added to the bridge 00377 * using both ast_bridge_join and ast_bridge_impart. 00378 */ 00379 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan); 00380 00381 /*! \brief Unsuspend a channel from a bridge 00382 * 00383 * \param bridge Bridge to unsuspend the channel from 00384 * \param chan Channel to unsuspend 00385 * 00386 * \retval 0 on success 00387 * \retval -1 on failure 00388 * 00389 * Example usage: 00390 * 00391 * \code 00392 * ast_bridge_unsuspend(bridge, chan); 00393 * \endcode 00394 * 00395 * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge. 00396 * The bridge will go back to handling the channel once this function returns. 00397 * 00398 * \note You must not mess with the channel once this function returns. 00399 * Doing so may result in bad things happening. 00400 */ 00401 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan); 00402 00403 /*! \brief Change the state of a bridged channel 00404 * 00405 * \param bridge_channel Channel to change the state on 00406 * \param new_state The new state to place the channel into 00407 * 00408 * Example usage: 00409 * 00410 * \code 00411 * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT); 00412 * \endcode 00413 * 00414 * This places the channel pointed to by bridge_channel into the state 00415 * AST_BRIDGE_CHANNEL_STATE_WAIT. 00416 * 00417 * \note This API call is only meant to be used in feature hook callbacks to 00418 * make sure the channel either hangs up or returns to the bridge. 00419 */ 00420 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state); 00421 00422 #if defined(__cplusplus) || defined(c_plusplus) 00423 } 00424 #endif 00425 00426 #endif /* _ASTERISK_BRIDGING_H */