/usr/include/asterisk/bridging_features.h is in asterisk-dev 1:11.7.0~dfsg-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 | /*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2009, Digium, Inc.
*
* Joshua Colp <jcolp@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*! \file
* \brief Channel Bridging API
* \author Joshua Colp <jcolp@digium.com>
*/
#ifndef _ASTERISK_BRIDGING_FEATURES_H
#define _ASTERISK_BRIDGING_FEATURES_H
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
/*! \brief Flags used for bridge features */
enum ast_bridge_feature_flags {
/*! Upon hangup the bridge should be discontinued */
AST_BRIDGE_FLAG_DISSOLVE = (1 << 0),
/*! Move between bridging technologies as needed. */
AST_BRIDGE_FLAG_SMART = (1 << 1),
};
/*! \brief Built in features */
enum ast_bridge_builtin_feature {
/*! DTMF Based Blind Transfer */
AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0,
/*! DTMF Based Attended Transfer */
AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
/*! DTMF Based Hangup Feature */
AST_BRIDGE_BUILTIN_HANGUP,
/*! End terminator for list of built in features. Must remain last. */
AST_BRIDGE_BUILTIN_END,
};
struct ast_bridge;
struct ast_bridge_channel;
/*!
* \brief Features hook callback type
*
* \param bridge The bridge that the channel is part of
* \param bridge_channel Channel executing the feature
* \param hook_pvt Private data passed in when the hook was created
*
* \retval 0 success
* \retval -1 failure
*/
typedef int (*ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt);
/*!
* \brief Features hook pvt destructor callback
*
* \param hook_pvt Private data passed in when the hook was create to destroy
*/
typedef void (*ast_bridge_features_hook_pvt_destructor)(void *hook_pvt);
/*!
* \brief Talking indicator callback
*
* \details This callback can be registered with the bridge in order
* to receive updates on when a bridge_channel has started and stopped
* talking
*
* \param bridge The bridge that the channel is part of
* \param bridge_channel Channel executing the feature
*
* \retval 0 success
* \retval -1 failure
*/
typedef void (*ast_bridge_talking_indicate_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *pvt_data);
typedef void (*ast_bridge_talking_indicate_destructor)(void *pvt_data);
/*!
* \brief Maximum length of a DTMF feature string
*/
#define MAXIMUM_DTMF_FEATURE_STRING 8
/*!
* \brief Structure that is the essence of a features hook
*/
struct ast_bridge_features_hook {
/*! DTMF String that is examined during a feature hook lookup */
char dtmf[MAXIMUM_DTMF_FEATURE_STRING];
/*! Callback that is called when DTMF string is matched */
ast_bridge_features_hook_callback callback;
/*! Callback to destroy hook_pvt data right before destruction. */
ast_bridge_features_hook_pvt_destructor destructor;
/*! Unique data that was passed into us */
void *hook_pvt;
/*! Linked list information */
AST_LIST_ENTRY(ast_bridge_features_hook) entry;
};
/*!
* \brief Structure that contains features information
*/
struct ast_bridge_features {
/*! Attached DTMF based feature hooks */
AST_LIST_HEAD_NOLOCK(, ast_bridge_features_hook) hooks;
/*! Callback to indicate when a bridge channel has started and stopped talking */
ast_bridge_talking_indicate_callback talker_cb;
/*! Callback to destroy any pvt data stored for the talker. */
ast_bridge_talking_indicate_destructor talker_destructor_cb;
/*! Talker callback pvt data */
void *talker_pvt_data;
/*! Feature flags that are enabled */
struct ast_flags feature_flags;
/*! Bit to indicate that the hook list is useful and should be considered when looking for DTMF features */
unsigned int usable:1;
/*! Bit to indicate whether the channel/bridge is muted or not */
unsigned int mute:1;
/*! Bit to indicate whether DTMF should be passed into the bridge tech or not. */
unsigned int dtmf_passthrough:1;
};
/*!
* \brief Structure that contains configuration information for the blind transfer built in feature
*/
struct ast_bridge_features_blind_transfer {
/*! Context to use for transfers */
char context[AST_MAX_CONTEXT];
};
/*!
* \brief Structure that contains configuration information for the attended transfer built in feature
*/
struct ast_bridge_features_attended_transfer {
/*! DTMF string used to abort the transfer */
char abort[MAXIMUM_DTMF_FEATURE_STRING];
/*! DTMF string used to turn the transfer into a three way conference */
char threeway[MAXIMUM_DTMF_FEATURE_STRING];
/*! DTMF string used to complete the transfer */
char complete[MAXIMUM_DTMF_FEATURE_STRING];
/*! Context to use for transfers */
char context[AST_MAX_CONTEXT];
};
/*! \brief Register a handler for a built in feature
*
* \param feature The feature that the handler will be responsible for
* \param callback The callback function that will handle it
* \param dtmf Default DTMF string used to activate the feature
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
* \endcode
*
* This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
* attended transfer feature.
*/
int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf);
/*! \brief Unregister a handler for a built in feature
*
* \param feature The feature to unregister
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
* \endcode
*
* This unregisters the function that is handling the built in attended transfer feature.
*/
int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
/*! \brief Attach a custom hook to a bridge features structure
*
* \param features Bridge features structure
* \param dtmf DTMF string to be activated upon
* \param callback Function to execute upon activation
* \param hook_pvt Unique data
* \param Optional destructor callback for hook_pvt data
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* struct ast_bridge_features features;
* ast_bridge_features_init(&features);
* ast_bridge_features_hook(&features, "#", pound_callback, NULL, NULL);
* \endcode
*
* This makes the bridging core call pound_callback if a channel that has this
* feature structure inputs the DTMF string '#'. A pointer to useful data may be
* provided to the hook_pvt parameter.
*
* \note It is important that the callback set the bridge channel state back to
* AST_BRIDGE_CHANNEL_STATE_WAIT or the bridge thread will not service the channel.
*/
int ast_bridge_features_hook(struct ast_bridge_features *features,
const char *dtmf,
ast_bridge_features_hook_callback callback,
void *hook_pvt,
ast_bridge_features_hook_pvt_destructor destructor);
/*! \brief Set a callback on the features structure to receive talking notifications on.
*
* \param features Bridge features structure
* \param talker_cb, Callback function to execute when talking events occur in the bridge core.
* \param pvt_data Optional unique data that will be passed with the talking events.
* \param Optional destructor callback for pvt data.
*
* \retval 0, success
* \retval -1, failure
*/
int ast_bridge_features_set_talk_detector(struct ast_bridge_features *features,
ast_bridge_talking_indicate_callback talker_cb,
ast_bridge_talking_indicate_destructor talker_destructor,
void *pvt_data);
/*! \brief Enable a built in feature on a bridge features structure
*
* \param features Bridge features structure
* \param feature Feature to enable
* \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
* \param config Configuration structure unique to the built in type
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* struct ast_bridge_features features;
* ast_bridge_features_init(&features);
* ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL);
* \endcode
*
* This enables the attended transfer DTMF option using the default DTMF string. An alternate
* string may be provided using the dtmf parameter. Internally this is simply setting up a hook
* to a built in feature callback function.
*/
int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config);
/*! \brief Set a flag on a bridge features structure
*
* \param features Bridge features structure
* \param flag Flag to enable
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* struct ast_bridge_features features;
* ast_bridge_features_init(&features);
* ast_bridge_features_set_flag(&features, AST_BRIDGE_FLAG_DISSOLVE);
* \endcode
*
* This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure
* 'features'.
*/
int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag);
/*! \brief Initialize bridge features structure
*
* \param features Bridge featues structure
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* struct ast_bridge_features features;
* ast_bridge_features_init(&features);
* \endcode
*
* This initializes the feature structure 'features' to have nothing enabled.
*
* \note This MUST be called before enabling features or flags. Failure to do so
* may result in a crash.
*/
int ast_bridge_features_init(struct ast_bridge_features *features);
/*! \brief Clean up the contents of a bridge features structure
*
* \param features Bridge features structure
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* struct ast_bridge_features features;
* ast_bridge_features_init(&features);
* ast_bridge_features_cleanup(&features);
* \endcode
*
* This cleans up the feature structure 'features'.
*
* \note This MUST be called after the features structure is done being used
* or a memory leak may occur.
*/
int ast_bridge_features_cleanup(struct ast_bridge_features *features);
/*! \brief Play a DTMF stream into a bridge, optionally not to a given channel
*
* \param bridge Bridge to play stream into
* \param dtmf DTMF to play
* \param chan Channel to optionally not play to
*
* \retval 0 on success
* \retval -1 on failure
*
* Example usage:
*
* \code
* ast_bridge_dtmf_stream(bridge, "0123456789", NULL);
* \endcode
*
* This sends the DTMF digits '0123456789' to all channels in the bridge pointed to
* by the bridge pointer. Optionally a channel may be excluded by passing it's channel pointer
* using the chan parameter.
*/
int ast_bridge_dtmf_stream(struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan);
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
#endif /* _ASTERISK_BRIDGING_FEATURES_H */
|