Wed Apr 6 11:29:53 2011

Asterisk developer's documentation


bridging_features.h File Reference

Channel Bridging API. More...

Go to the source code of this file.

Data Structures

struct  ast_bridge_features
 Structure that contains features information. More...
struct  ast_bridge_features_attended_transfer
 Structure that contains configuration information for the attended transfer built in feature. More...
struct  ast_bridge_features_blind_transfer
 Structure that contains configuration information for the blind transfer built in feature. More...
struct  ast_bridge_features_hook
 Structure that is the essence of a features hook. More...

Defines

#define MAXIMUM_DTMF_FEATURE_STRING   8
 Maximum length of a DTMF feature string.

Typedefs

typedef int(*) ast_bridge_features_hook_callback (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt)
 Features hook callback type.

Enumerations

enum  ast_bridge_builtin_feature { AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, AST_BRIDGE_BUILTIN_HANGUP, AST_BRIDGE_BUILTIN_END }
 Built in features. More...
enum  ast_bridge_feature_flags { AST_BRIDGE_FLAG_DISSOLVE = (1 << 0), AST_BRIDGE_FLAG_SMART = (1 << 1) }
 Flags used for bridge features. More...

Functions

int ast_bridge_dtmf_stream (struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan)
 Play a DTMF stream into a bridge, optionally not to a given channel.
int ast_bridge_features_cleanup (struct ast_bridge_features *features)
 Clean up the contents of a bridge features structure.
int ast_bridge_features_enable (struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config)
 Enable a built in feature on a bridge features structure.
int ast_bridge_features_hook (struct ast_bridge_features *features, const char *dtmf, ast_bridge_features_hook_callback callback, void *hook_pvt)
 Attach a custom hook to a bridge features structure.
int ast_bridge_features_init (struct ast_bridge_features *features)
 Initialize bridge features structure.
int ast_bridge_features_register (enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf)
 Register a handler for a built in feature.
int ast_bridge_features_set_flag (struct ast_bridge_features *features, enum ast_bridge_feature_flags flag)
 Set a flag on a bridge features structure.
int ast_bridge_features_unregister (enum ast_bridge_builtin_feature feature)
 Unregister a handler for a built in feature.


Detailed Description

Channel Bridging API.

Author:
Joshua Colp <jcolp@digium.com>

Definition in file bridging_features.h.


Define Documentation

#define MAXIMUM_DTMF_FEATURE_STRING   8

Maximum length of a DTMF feature string.

Definition at line 69 of file bridging_features.h.

Referenced by bridge_channel_feature().


Typedef Documentation

typedef int(*) ast_bridge_features_hook_callback(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt)

Features hook callback type.

Parameters:
bridge The bridge that the channel is part of
bridge_channel Channel executing the feature
hook_pvt Private data passed in when the hook was created
Return values:
0 success
-1 failure

Definition at line 64 of file bridging_features.h.


Enumeration Type Documentation

enum ast_bridge_builtin_feature

Built in features.

Enumerator:
AST_BRIDGE_BUILTIN_BLINDTRANSFER  DTMF Based Blind Transfer
AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER  DTMF Based Attended Transfer
AST_BRIDGE_BUILTIN_HANGUP  DTMF Based Hangup Feature
AST_BRIDGE_BUILTIN_END  End terminator for list of built in features. Must remain last.

Definition at line 40 of file bridging_features.h.

00040                                 {
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 };

enum ast_bridge_feature_flags

Flags used for bridge features.

Enumerator:
AST_BRIDGE_FLAG_DISSOLVE  Upon hangup the bridge should be discontinued
AST_BRIDGE_FLAG_SMART  Move between bridging technologies as needed.

Definition at line 32 of file bridging_features.h.

00032                               {
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 };


Function Documentation

int ast_bridge_dtmf_stream ( struct ast_bridge bridge,
const char *  dtmf,
struct ast_channel chan 
)

Play a DTMF stream into a bridge, optionally not to a given channel.

Parameters:
bridge Bridge to play stream into
dtmf DTMF to play
chan Channel to optionally not play to
Return values:
0 on success
-1 on failure
Example usage:

 ast_bridge_dtmf_stream(bridge, "0123456789", NULL);

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.

Definition at line 1346 of file bridging.c.

References ao2_lock, ao2_unlock, ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_DTMF, ast_copy_string(), AST_LIST_TRAVERSE, ast_bridge_channel::bridge, ast_bridge_channel::chan, and ast_bridge_channel::dtmf_stream_q.

Referenced by bridge_channel_feature().

01347 {
01348    struct ast_bridge_channel *bridge_channel = NULL;
01349 
01350    ao2_lock(bridge);
01351 
01352    AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
01353       if (bridge_channel->chan == chan) {
01354          continue;
01355       }
01356       ast_copy_string(bridge_channel->dtmf_stream_q, dtmf, sizeof(bridge_channel->dtmf_stream_q));
01357       ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_DTMF);
01358    }
01359 
01360    ao2_unlock(bridge);
01361 
01362    return 0;
01363 }

int ast_bridge_features_cleanup ( struct ast_bridge_features features  ) 

Clean up the contents of a bridge features structure.

Parameters:
features Bridge features structure
Return values:
0 on success
-1 on failure
Example usage:

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.

Definition at line 1334 of file bridging.c.

References ast_free, and AST_LIST_REMOVE_HEAD.

Referenced by confbridge_exec(), destroy_bridge(), and feature_attended_transfer().

01335 {
01336    struct ast_bridge_features_hook *hook = NULL;
01337 
01338    /* This is relatively simple, hooks are kept as a list on the features structure so we just pop them off and free them */
01339    while ((hook = AST_LIST_REMOVE_HEAD(&features->hooks, entry))) {
01340       ast_free(hook);
01341    }
01342 
01343    return 0;
01344 }

int ast_bridge_features_enable ( struct ast_bridge_features features,
enum ast_bridge_builtin_feature  feature,
const char *  dtmf,
void *  config 
)

Enable a built in feature on a bridge features structure.

Parameters:
features Bridge features structure
feature Feature to enable
dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
config Configuration structure unique to the built in type
Return values:
0 on success
-1 on failure
Example usage:

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.

Definition at line 1296 of file bridging.c.

References ast_bridge_features_hook(), ast_debug, ast_strlen_zero(), builtin_features_dtmf, and builtin_features_handlers.

Referenced by feature_attended_transfer().

01297 {
01298    /* If no alternate DTMF stream was provided use the default one */
01299    if (ast_strlen_zero(dtmf)) {
01300       dtmf = builtin_features_dtmf[feature];
01301       /* If no DTMF is still available (ie: it has been disabled) then error out now */
01302       if (ast_strlen_zero(dtmf)) {
01303          ast_debug(1, "Failed to enable built in feature %d on %p, no DTMF string is available for it.\n", feature, features);
01304          return -1;
01305       }
01306    }
01307 
01308    if (!builtin_features_handlers[feature]) {
01309       return -1;
01310    }
01311 
01312    /* The rest is basically pretty easy. We create another hook using the built in feature's callback and DTMF, easy as pie. */
01313    return ast_bridge_features_hook(features, dtmf, builtin_features_handlers[feature], config);
01314 }

int ast_bridge_features_hook ( struct ast_bridge_features features,
const char *  dtmf,
ast_bridge_features_hook_callback  callback,
void *  hook_pvt 
)

Attach a custom hook to a bridge features structure.

Parameters:
features Bridge features structure
dtmf DTMF string to be activated upon
callback Function to execute upon activation
hook_pvt Unique data
Return values:
0 on success
-1 on failure
Example usage:

 struct ast_bridge_features features;
 ast_bridge_features_init(&features);
 ast_bridge_features_hook(&features, "#", pound_callback, NULL);

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.

Definition at line 1275 of file bridging.c.

References ast_calloc, ast_copy_string(), AST_LIST_INSERT_TAIL, and ast_bridge_features::usable.

Referenced by ast_bridge_features_enable(), confbridge_exec(), and feature_attended_transfer().

01276 {
01277    struct ast_bridge_features_hook *hook = NULL;
01278 
01279    /* Allocate new memory and setup it's various variables */
01280    if (!(hook = ast_calloc(1, sizeof(*hook)))) {
01281       return -1;
01282    }
01283 
01284    ast_copy_string(hook->dtmf, dtmf, sizeof(hook->dtmf));
01285    hook->callback = callback;
01286    hook->hook_pvt = hook_pvt;
01287 
01288    /* Once done we add it onto the list. Now it will be picked up when DTMF is used */
01289    AST_LIST_INSERT_TAIL(&features->hooks, hook, entry);
01290 
01291    features->usable = 1;
01292 
01293    return 0;
01294 }

int ast_bridge_features_init ( struct ast_bridge_features features  ) 

Initialize bridge features structure.

Parameters:
features Bridge featues structure
Return values:
0 on success
-1 on failure
Example usage:

 struct ast_bridge_features features;
 ast_bridge_features_init(&features);

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.

Definition at line 1323 of file bridging.c.

References AST_LIST_HEAD_INIT_NOLOCK.

Referenced by confbridge_exec(), and feature_attended_transfer().

01324 {
01325    /* Zero out the structure */
01326    memset(features, 0, sizeof(*features));
01327 
01328    /* Initialize the hooks list, just in case */
01329    AST_LIST_HEAD_INIT_NOLOCK(&features->hooks);
01330 
01331    return 0;
01332 }

int ast_bridge_features_register ( enum ast_bridge_builtin_feature  feature,
ast_bridge_features_hook_callback  callback,
const char *  dtmf 
)

Register a handler for a built in feature.

Parameters:
feature The feature that the handler will be responsible for
callback The callback function that will handle it
dtmf Default DTMF string used to activate the feature
Return values:
0 on success
-1 on failure
Example usage:

 ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");

This registers the function bridge_builtin_attended_transfer as the function responsible for the built in attended transfer feature.

Definition at line 1249 of file bridging.c.

References ast_copy_string(), ast_strlen_zero(), builtin_features_dtmf, and builtin_features_handlers.

Referenced by load_module().

01250 {
01251    if (builtin_features_handlers[feature]) {
01252       return -1;
01253    }
01254 
01255    if (!ast_strlen_zero(dtmf)) {
01256       ast_copy_string(builtin_features_dtmf[feature], dtmf, sizeof(builtin_features_dtmf[feature]));
01257    }
01258 
01259    builtin_features_handlers[feature] = callback;
01260 
01261    return 0;
01262 }

int ast_bridge_features_set_flag ( struct ast_bridge_features features,
enum ast_bridge_feature_flags  flag 
)

Set a flag on a bridge features structure.

Parameters:
features Bridge features structure
flag Flag to enable
Return values:
0 on success
-1 on failure
Example usage:

This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure 'features'.

Definition at line 1316 of file bridging.c.

References ast_set_flag, ast_bridge_features::feature_flags, and ast_bridge_features::usable.

Referenced by feature_attended_transfer().

01317 {
01318    ast_set_flag(&features->feature_flags, flag);
01319    features->usable = 1;
01320    return 0;
01321 }

int ast_bridge_features_unregister ( enum ast_bridge_builtin_feature  feature  ) 

Unregister a handler for a built in feature.

Parameters:
feature The feature to unregister
Return values:
0 on success
-1 on failure
Example usage:

 ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);

This unregisters the function that is handling the built in attended transfer feature.

Definition at line 1264 of file bridging.c.

References builtin_features_handlers.

01265 {
01266    if (!builtin_features_handlers[feature]) {
01267       return -1;
01268    }
01269 
01270    builtin_features_handlers[feature] = NULL;
01271 
01272    return 0;
01273 }


Generated on Wed Apr 6 11:29:53 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7