00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 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 */ 00023 00024 #ifndef _ASTERISK_BRIDGING_TECHNOLOGY_H 00025 #define _ASTERISK_BRIDGING_TECHNOLOGY_H 00026 00027 #if defined(__cplusplus) || defined(c_plusplus) 00028 extern "C" { 00029 #endif 00030 00031 /*! \brief Preference for choosing the bridge technology */ 00032 enum ast_bridge_preference { 00033 /*! Bridge technology should have high precedence over other bridge technologies */ 00034 AST_BRIDGE_PREFERENCE_HIGH = 0, 00035 /*! Bridge technology is decent, not the best but should still be considered over low */ 00036 AST_BRIDGE_PREFERENCE_MEDIUM, 00037 /*! Bridge technology is low, it should not be considered unless it is absolutely needed */ 00038 AST_BRIDGE_PREFERENCE_LOW, 00039 }; 00040 00041 /*! 00042 * \brief Structure that is the essence of a bridge technology 00043 */ 00044 struct ast_bridge_technology { 00045 /*! Unique name to this bridge technology */ 00046 const char *name; 00047 /*! The capabilities that this bridge technology is capable of */ 00048 int capabilities; 00049 /*! Preference level that should be used when determining whether to use this bridge technology or not */ 00050 enum ast_bridge_preference preference; 00051 /*! Callback for when a bridge is being created */ 00052 int (*create)(struct ast_bridge *bridge); 00053 /*! Callback for when a bridge is being destroyed */ 00054 int (*destroy)(struct ast_bridge *bridge); 00055 /*! Callback for when a channel is being added to a bridge */ 00056 int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); 00057 /*! Callback for when a channel is leaving a bridge */ 00058 int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); 00059 /*! Callback for when a channel is suspended from the bridge */ 00060 void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); 00061 /*! Callback for when a channel is unsuspended from the bridge */ 00062 void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); 00063 /*! Callback to see if a channel is compatible with the bridging technology */ 00064 int (*compatible)(struct ast_bridge_channel *bridge_channel); 00065 /*! Callback for writing a frame into the bridging technology */ 00066 enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame); 00067 /*! Callback for when a file descriptor trips */ 00068 int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd); 00069 /*! Callback for replacement thread function */ 00070 int (*thread)(struct ast_bridge *bridge); 00071 /*! Callback for poking a bridge thread */ 00072 int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); 00073 /*! Formats that the bridge technology supports */ 00074 format_t formats; 00075 /*! Bit to indicate whether the bridge technology is currently suspended or not */ 00076 unsigned int suspended:1; 00077 /*! Module this bridge technology belongs to. Is used for reference counting when creating/destroying a bridge. */ 00078 struct ast_module *mod; 00079 /*! Linked list information */ 00080 AST_RWLIST_ENTRY(ast_bridge_technology) entry; 00081 }; 00082 00083 /*! \brief Register a bridge technology for use 00084 * 00085 * \param technology The bridge technology to register 00086 * \param mod The module that is registering the bridge technology 00087 * 00088 * \retval 0 on success 00089 * \retval -1 on failure 00090 * 00091 * Example usage: 00092 * 00093 * \code 00094 * ast_bridge_technology_register(&simple_bridge_tech); 00095 * \endcode 00096 * 00097 * This registers a bridge technology declared as the structure 00098 * simple_bridge_tech with the bridging core and makes it available for 00099 * use when creating bridges. 00100 */ 00101 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod); 00102 00103 /*! \brief See \ref __ast_bridge_technology_register() */ 00104 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self) 00105 00106 /*! \brief Unregister a bridge technology from use 00107 * 00108 * \param technology The bridge technology to unregister 00109 * 00110 * \retval 0 on success 00111 * \retval -1 on failure 00112 * 00113 * Example usage: 00114 * 00115 * \code 00116 * ast_bridge_technology_unregister(&simple_bridge_tech); 00117 * \endcode 00118 * 00119 * This unregisters a bridge technlogy declared as the structure 00120 * simple_bridge_tech with the bridging core. It will no longer be 00121 * considered when creating a new bridge. 00122 */ 00123 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology); 00124 00125 /*! \brief Feed notification that a frame is waiting on a channel into the bridging core 00126 * 00127 * \param bridge The bridge that the notification should influence 00128 * \param bridge_channel Bridge channel the notification was received on (if known) 00129 * \param chan Channel the notification was received on (if known) 00130 * \param outfd File descriptor that the notification was received on (if known) 00131 * 00132 * Example usage: 00133 * 00134 * \code 00135 * ast_bridge_handle_trip(bridge, NULL, chan, -1); 00136 * \endcode 00137 * 00138 * This tells the bridging core that a frame has been received on 00139 * the channel pointed to by chan and that it should be read and handled. 00140 * 00141 * \note This should only be used by bridging technologies. 00142 */ 00143 void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd); 00144 00145 /*! \brief Suspend a bridge technology from consideration 00146 * 00147 * \param technology The bridge technology to suspend 00148 * 00149 * Example usage: 00150 * 00151 * \code 00152 * ast_bridge_technology_suspend(&simple_bridge_tech); 00153 * \endcode 00154 * 00155 * This suspends the bridge technology simple_bridge_tech from being considered 00156 * when creating a new bridge. Existing bridges using the bridge technology 00157 * are not affected. 00158 */ 00159 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology); 00160 00161 /*! \brief Unsuspend a bridge technology 00162 * 00163 * \param technology The bridge technology to unsuspend 00164 * 00165 * Example usage: 00166 * 00167 * \code 00168 * ast_bridge_technology_unsuspend(&simple_bridge_tech); 00169 * \endcode 00170 * 00171 * This makes the bridge technology simple_bridge_tech considered when 00172 * creating a new bridge again. 00173 */ 00174 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology); 00175 00176 #if defined(__cplusplus) || defined(c_plusplus) 00177 } 00178 #endif 00179 00180 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */