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. |
Channel Bridging API.
Definition in file bridging_features.h.
#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 int(* ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt) |
Features hook callback type.
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 |
0 | success |
-1 | failure |
Definition at line 64 of file bridging_features.h.
Built in features.
Definition at line 40 of file bridging_features.h.
{ /*! 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, };
Flags used for bridge features.
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.
{ /*! 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), };
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.
bridge | Bridge to play stream into |
dtmf | DTMF to play |
chan | Channel to optionally not play to |
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 1337 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::chan, ast_bridge::channels, ast_bridge_channel::dtmf_stream_q, and ast_bridge_channel::entry.
Referenced by bridge_channel_feature().
{ struct ast_bridge_channel *bridge_channel = NULL; ao2_lock(bridge); AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) { if (bridge_channel->chan == chan) { continue; } ast_copy_string(bridge_channel->dtmf_stream_q, dtmf, sizeof(bridge_channel->dtmf_stream_q)); ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_DTMF); } ao2_unlock(bridge); return 0; }
int ast_bridge_features_cleanup | ( | struct ast_bridge_features * | features | ) |
Clean up the contents of a bridge features structure.
features | Bridge features structure |
0 | on success |
-1 | on failure |
Example usage:
struct ast_bridge_features features; ast_bridge_features_init(&features); ast_bridge_features_cleanup(&features);
This cleans up the feature structure 'features'.
Definition at line 1325 of file bridging.c.
References ast_free, AST_LIST_REMOVE_HEAD, ast_bridge_features_hook::entry, and ast_bridge_features::hooks.
Referenced by confbridge_exec(), destroy_bridge(), and feature_attended_transfer().
{ struct ast_bridge_features_hook *hook = NULL; /* This is relatively simple, hooks are kept as a list on the features structure so we just pop them off and free them */ while ((hook = AST_LIST_REMOVE_HEAD(&features->hooks, entry))) { ast_free(hook); } return 0; }
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.
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 |
0 | on success |
-1 | on failure |
Example usage:
struct ast_bridge_features features; ast_bridge_features_init(&features); ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL);
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 1287 of file bridging.c.
References ast_bridge_features_hook(), ast_debug, and ast_strlen_zero().
Referenced by feature_attended_transfer().
{ /* If no alternate DTMF stream was provided use the default one */ if (ast_strlen_zero(dtmf)) { dtmf = builtin_features_dtmf[feature]; /* If no DTMF is still available (ie: it has been disabled) then error out now */ if (ast_strlen_zero(dtmf)) { ast_debug(1, "Failed to enable built in feature %d on %p, no DTMF string is available for it.\n", feature, features); return -1; } } if (!builtin_features_handlers[feature]) { return -1; } /* The rest is basically pretty easy. We create another hook using the built in feature's callback and DTMF, easy as pie. */ return ast_bridge_features_hook(features, dtmf, builtin_features_handlers[feature], config); }
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.
features | Bridge features structure |
dtmf | DTMF string to be activated upon |
callback | Function to execute upon activation |
hook_pvt | Unique data |
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.
Definition at line 1266 of file bridging.c.
References ast_calloc, ast_copy_string(), AST_LIST_INSERT_TAIL, ast_bridge_features_hook::callback, ast_bridge_features_hook::dtmf, ast_bridge_features_hook::entry, ast_bridge_features_hook::hook_pvt, ast_bridge_features::hooks, and ast_bridge_features::usable.
Referenced by ast_bridge_features_enable(), confbridge_exec(), and feature_attended_transfer().
{ struct ast_bridge_features_hook *hook = NULL; /* Allocate new memory and setup it's various variables */ if (!(hook = ast_calloc(1, sizeof(*hook)))) { return -1; } ast_copy_string(hook->dtmf, dtmf, sizeof(hook->dtmf)); hook->callback = callback; hook->hook_pvt = hook_pvt; /* Once done we add it onto the list. Now it will be picked up when DTMF is used */ AST_LIST_INSERT_TAIL(&features->hooks, hook, entry); features->usable = 1; return 0; }
int ast_bridge_features_init | ( | struct ast_bridge_features * | features | ) |
Initialize bridge features structure.
features | Bridge featues structure |
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.
Definition at line 1314 of file bridging.c.
References AST_LIST_HEAD_INIT_NOLOCK, and ast_bridge_features::hooks.
Referenced by confbridge_exec(), and feature_attended_transfer().
{ /* Zero out the structure */ memset(features, 0, sizeof(*features)); /* Initialize the hooks list, just in case */ AST_LIST_HEAD_INIT_NOLOCK(&features->hooks); return 0; }
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.
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 |
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 1240 of file bridging.c.
References ast_copy_string(), and ast_strlen_zero().
Referenced by load_module().
{ if (builtin_features_handlers[feature]) { return -1; } if (!ast_strlen_zero(dtmf)) { ast_copy_string(builtin_features_dtmf[feature], dtmf, sizeof(builtin_features_dtmf[feature])); } builtin_features_handlers[feature] = callback; return 0; }
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.
features | Bridge features structure |
flag | Flag to enable |
0 | on success |
-1 | on failure |
Example usage:
struct ast_bridge_features features; ast_bridge_features_init(&features); ast_bridge_features_set_flag(&features, AST_BRIDGE_FLAG_DISSOLVE);
This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure 'features'.
Definition at line 1307 of file bridging.c.
References ast_set_flag, ast_bridge_features::feature_flags, and ast_bridge_features::usable.
Referenced by feature_attended_transfer().
{ ast_set_flag(&features->feature_flags, flag); features->usable = 1; return 0; }
int ast_bridge_features_unregister | ( | enum ast_bridge_builtin_feature | feature | ) |
Unregister a handler for a built in feature.
feature | The feature to unregister |
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 1255 of file bridging.c.
{ if (!builtin_features_handlers[feature]) { return -1; } builtin_features_handlers[feature] = NULL; return 0; }