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_FEATURES_H 00025 #define _ASTERISK_BRIDGING_FEATURES_H 00026 00027 #if defined(__cplusplus) || defined(c_plusplus) 00028 extern "C" { 00029 #endif 00030 00031 /*! \brief Flags used for bridge features */ 00032 enum ast_bridge_feature_flags { 00033 /*! Upon hangup the bridge should be discontinued */ 00034 AST_BRIDGE_FLAG_DISSOLVE = (1 << 0), 00035 /*! Move between bridging technologies as needed. */ 00036 AST_BRIDGE_FLAG_SMART = (1 << 1), 00037 }; 00038 00039 /*! \brief Built in features */ 00040 enum ast_bridge_builtin_feature { 00041 /*! DTMF Based Blind Transfer */ 00042 AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0, 00043 /*! DTMF Based Attended Transfer */ 00044 AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, 00045 /*! DTMF Based Hangup Feature */ 00046 AST_BRIDGE_BUILTIN_HANGUP, 00047 /*! End terminator for list of built in features. Must remain last. */ 00048 AST_BRIDGE_BUILTIN_END, 00049 }; 00050 00051 struct ast_bridge; 00052 struct ast_bridge_channel; 00053 00054 /*! 00055 * \brief Features hook callback type 00056 * 00057 * \param bridge The bridge that the channel is part of 00058 * \param bridge_channel Channel executing the feature 00059 * \param hook_pvt Private data passed in when the hook was created 00060 * 00061 * \retval 0 success 00062 * \retval -1 failure 00063 */ 00064 typedef int (*ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt); 00065 00066 /*! 00067 * \brief Maximum length of a DTMF feature string 00068 */ 00069 #define MAXIMUM_DTMF_FEATURE_STRING 8 00070 00071 /*! 00072 * \brief Structure that is the essence of a features hook 00073 */ 00074 struct ast_bridge_features_hook { 00075 /*! DTMF String that is examined during a feature hook lookup */ 00076 char dtmf[MAXIMUM_DTMF_FEATURE_STRING]; 00077 /*! Callback that is called when DTMF string is matched */ 00078 ast_bridge_features_hook_callback callback; 00079 /*! Unique data that was passed into us */ 00080 void *hook_pvt; 00081 /*! Linked list information */ 00082 AST_LIST_ENTRY(ast_bridge_features_hook) entry; 00083 }; 00084 00085 /*! 00086 * \brief Structure that contains features information 00087 */ 00088 struct ast_bridge_features { 00089 /*! Attached DTMF based feature hooks */ 00090 AST_LIST_HEAD_NOLOCK(, ast_bridge_features_hook) hooks; 00091 /*! Feature flags that are enabled */ 00092 struct ast_flags feature_flags; 00093 /*! Bit to indicate that this structure is useful and should be considered when looking for features */ 00094 unsigned int usable:1; 00095 /*! Bit to indicate whether the channel/bridge is muted or not */ 00096 unsigned int mute:1; 00097 }; 00098 00099 /*! 00100 * \brief Structure that contains configuration information for the blind transfer built in feature 00101 */ 00102 struct ast_bridge_features_blind_transfer { 00103 /*! Context to use for transfers */ 00104 char context[AST_MAX_CONTEXT]; 00105 }; 00106 00107 /*! 00108 * \brief Structure that contains configuration information for the attended transfer built in feature 00109 */ 00110 struct ast_bridge_features_attended_transfer { 00111 /*! DTMF string used to abort the transfer */ 00112 char abort[MAXIMUM_DTMF_FEATURE_STRING]; 00113 /*! DTMF string used to turn the transfer into a three way conference */ 00114 char threeway[MAXIMUM_DTMF_FEATURE_STRING]; 00115 /*! DTMF string used to complete the transfer */ 00116 char complete[MAXIMUM_DTMF_FEATURE_STRING]; 00117 /*! Context to use for transfers */ 00118 char context[AST_MAX_CONTEXT]; 00119 }; 00120 00121 /*! \brief Register a handler for a built in feature 00122 * 00123 * \param feature The feature that the handler will be responsible for 00124 * \param callback The callback function that will handle it 00125 * \param dtmf Default DTMF string used to activate the feature 00126 * 00127 * \retval 0 on success 00128 * \retval -1 on failure 00129 * 00130 * Example usage: 00131 * 00132 * \code 00133 * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1"); 00134 * \endcode 00135 * 00136 * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in 00137 * attended transfer feature. 00138 */ 00139 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf); 00140 00141 /*! \brief Unregister a handler for a built in feature 00142 * 00143 * \param feature The feature to unregister 00144 * 00145 * \retval 0 on success 00146 * \retval -1 on failure 00147 * 00148 * Example usage: 00149 * 00150 * \code 00151 * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER); 00152 * \endcode 00153 * 00154 * This unregisters the function that is handling the built in attended transfer feature. 00155 */ 00156 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature); 00157 00158 /*! \brief Attach a custom hook to a bridge features structure 00159 * 00160 * \param features Bridge features structure 00161 * \param dtmf DTMF string to be activated upon 00162 * \param callback Function to execute upon activation 00163 * \param hook_pvt Unique data 00164 * 00165 * \retval 0 on success 00166 * \retval -1 on failure 00167 * 00168 * Example usage: 00169 * 00170 * \code 00171 * struct ast_bridge_features features; 00172 * ast_bridge_features_init(&features); 00173 * ast_bridge_features_hook(&features, "#", pound_callback, NULL); 00174 * \endcode 00175 * 00176 * This makes the bridging core call pound_callback if a channel that has this 00177 * feature structure inputs the DTMF string '#'. A pointer to useful data may be 00178 * provided to the hook_pvt parameter. 00179 * 00180 * \note It is important that the callback set the bridge channel state back to 00181 * AST_BRIDGE_CHANNEL_STATE_WAIT or the bridge thread will not service the channel. 00182 */ 00183 int ast_bridge_features_hook(struct ast_bridge_features *features, const char *dtmf, ast_bridge_features_hook_callback callback, void *hook_pvt); 00184 00185 /*! \brief Enable a built in feature on a bridge features structure 00186 * 00187 * \param features Bridge features structure 00188 * \param feature Feature to enable 00189 * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default 00190 * \param config Configuration structure unique to the built in type 00191 * 00192 * \retval 0 on success 00193 * \retval -1 on failure 00194 * 00195 * Example usage: 00196 * 00197 * \code 00198 * struct ast_bridge_features features; 00199 * ast_bridge_features_init(&features); 00200 * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL); 00201 * \endcode 00202 * 00203 * This enables the attended transfer DTMF option using the default DTMF string. An alternate 00204 * string may be provided using the dtmf parameter. Internally this is simply setting up a hook 00205 * to a built in feature callback function. 00206 */ 00207 int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config); 00208 00209 /*! \brief Set a flag on a bridge features structure 00210 * 00211 * \param features Bridge features structure 00212 * \param flag Flag to enable 00213 * 00214 * \retval 0 on success 00215 * \retval -1 on failure 00216 * 00217 * Example usage: 00218 * 00219 * \code 00220 * struct ast_bridge_features features; 00221 * ast_bridge_features_init(&features); 00222 * ast_bridge_features_set_flag(&features, AST_BRIDGE_FLAG_DISSOLVE); 00223 * \endcode 00224 * 00225 * This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure 00226 * 'features'. 00227 */ 00228 int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag); 00229 00230 /*! \brief Initialize bridge features structure 00231 * 00232 * \param features Bridge featues structure 00233 * 00234 * \retval 0 on success 00235 * \retval -1 on failure 00236 * 00237 * Example usage: 00238 * 00239 * \code 00240 * struct ast_bridge_features features; 00241 * ast_bridge_features_init(&features); 00242 * \endcode 00243 * 00244 * This initializes the feature structure 'features' to have nothing enabled. 00245 * 00246 * \note This MUST be called before enabling features or flags. Failure to do so 00247 * may result in a crash. 00248 */ 00249 int ast_bridge_features_init(struct ast_bridge_features *features); 00250 00251 /*! \brief Clean up the contents of a bridge features structure 00252 * 00253 * \param features Bridge features structure 00254 * 00255 * \retval 0 on success 00256 * \retval -1 on failure 00257 * 00258 * Example usage: 00259 * 00260 * \code 00261 * struct ast_bridge_features features; 00262 * ast_bridge_features_init(&features); 00263 * ast_bridge_features_cleanup(&features); 00264 * \endcode 00265 * 00266 * This cleans up the feature structure 'features'. 00267 * 00268 * \note This MUST be called after the features structure is done being used 00269 * or a memory leak may occur. 00270 */ 00271 int ast_bridge_features_cleanup(struct ast_bridge_features *features); 00272 00273 /*! \brief Play a DTMF stream into a bridge, optionally not to a given channel 00274 * 00275 * \param bridge Bridge to play stream into 00276 * \param dtmf DTMF to play 00277 * \param chan Channel to optionally not play to 00278 * 00279 * \retval 0 on success 00280 * \retval -1 on failure 00281 * 00282 * Example usage: 00283 * 00284 * \code 00285 * ast_bridge_dtmf_stream(bridge, "0123456789", NULL); 00286 * \endcode 00287 * 00288 * This sends the DTMF digits '0123456789' to all channels in the bridge pointed to 00289 * by the bridge pointer. Optionally a channel may be excluded by passing it's channel pointer 00290 * using the chan parameter. 00291 */ 00292 int ast_bridge_dtmf_stream(struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan); 00293 00294 #if defined(__cplusplus) || defined(c_plusplus) 00295 } 00296 #endif 00297 00298 #endif /* _ASTERISK_BRIDGING_FEATURES_H */