Wed Jan 8 2020 09:49:58

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...
 

Macros

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

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. More...
 

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. More...
 
int ast_bridge_features_cleanup (struct ast_bridge_features *features)
 Clean up the contents of a bridge features structure. More...
 
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. More...
 
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. More...
 
int ast_bridge_features_init (struct ast_bridge_features *features)
 Initialize bridge features structure. More...
 
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. More...
 
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. More...
 
int ast_bridge_features_unregister (enum ast_bridge_builtin_feature feature)
 Unregister a handler for a built in feature. More...
 

Detailed Description

Channel Bridging API.

Author
Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file bridging_features.h.

Macro Definition 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
bridgeThe bridge that the channel is part of
bridge_channelChannel executing the feature
hook_pvtPrivate data passed in when the hook was created
Return values
0success
-1failure

Definition at line 64 of file bridging_features.h.

Enumeration Type Documentation

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.

40  {
41  /*! DTMF Based Blind Transfer */
43  /*! DTMF Based Attended Transfer */
45  /*! DTMF Based Hangup Feature */
47  /*! End terminator for list of built in features. Must remain last. */
49 };

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.

32  {
33  /*! Upon hangup the bridge should be discontinued */
34  AST_BRIDGE_FLAG_DISSOLVE = (1 << 0),
35  /*! Move between bridging technologies as needed. */
36  AST_BRIDGE_FLAG_SMART = (1 << 1),
37 };

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
bridgeBridge to play stream into
dtmfDTMF to play
chanChannel to optionally not play to
Return values
0on success
-1on 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 1345 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, and ast_bridge_channel::dtmf_stream_q.

Referenced by bridge_channel_feature().

1346 {
1347  struct ast_bridge_channel *bridge_channel = NULL;
1348 
1349  ao2_lock(bridge);
1350 
1351  AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
1352  if (bridge_channel->chan == chan) {
1353  continue;
1354  }
1355  ast_copy_string(bridge_channel->dtmf_stream_q, dtmf, sizeof(bridge_channel->dtmf_stream_q));
1357  }
1358 
1359  ao2_unlock(bridge);
1360 
1361  return 0;
1362 }
char dtmf_stream_q[8]
Definition: bridging.h:141
#define ao2_unlock(a)
Definition: astobj2.h:497
void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state)
Change the state of a bridged channel.
Definition: bridging.c:122
#define ao2_lock(a)
Definition: astobj2.h:488
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
struct ast_channel * chan
Definition: bridging.h:125
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:223
int ast_bridge_features_cleanup ( struct ast_bridge_features features)

Clean up the contents of a bridge features structure.

Parameters
featuresBridge features structure
Return values
0on success
-1on failure

Example usage:

* struct ast_bridge_features features;
*

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 1333 of file bridging.c.

References ast_free, and AST_LIST_REMOVE_HEAD.

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

1334 {
1335  struct ast_bridge_features_hook *hook = NULL;
1336 
1337  /* This is relatively simple, hooks are kept as a list on the features structure so we just pop them off and free them */
1338  while ((hook = AST_LIST_REMOVE_HEAD(&features->hooks, entry))) {
1339  ast_free(hook);
1340  }
1341 
1342  return 0;
1343 }
#define AST_LIST_REMOVE_HEAD(head, field)
Removes and returns the head entry from a list.
Definition: linkedlists.h:818
#define ast_free(a)
Definition: astmm.h:97
Structure that is the essence of a features hook.
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
featuresBridge features structure
featureFeature to enable
dtmfOptionally the DTMF stream to trigger the feature, if not specified it will be the default
configConfiguration structure unique to the built in type
Return values
0on success
-1on 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 1295 of file bridging.c.

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

Referenced by feature_attended_transfer().

1296 {
1297  /* If no alternate DTMF stream was provided use the default one */
1298  if (ast_strlen_zero(dtmf)) {
1299  dtmf = builtin_features_dtmf[feature];
1300  /* If no DTMF is still available (ie: it has been disabled) then error out now */
1301  if (ast_strlen_zero(dtmf)) {
1302  ast_debug(1, "Failed to enable built in feature %u on %p, no DTMF string is available for it.\n", feature, features);
1303  return -1;
1304  }
1305  }
1306 
1307  if (!builtin_features_handlers[feature]) {
1308  return -1;
1309  }
1310 
1311  /* The rest is basically pretty easy. We create another hook using the built in feature's callback and DTMF, easy as pie. */
1312  return ast_bridge_features_hook(features, dtmf, builtin_features_handlers[feature], config);
1313 }
static const char config[]
Definition: cdr_csv.c:57
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.
Definition: bridging.c:1274
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
static void * builtin_features_handlers[AST_BRIDGE_BUILTIN_END]
Definition: bridging.c:61
static char builtin_features_dtmf[AST_BRIDGE_BUILTIN_END][MAXIMUM_DTMF_FEATURE_STRING]
Definition: bridging.c:58
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
featuresBridge features structure
dtmfDTMF string to be activated upon
callbackFunction to execute upon activation
hook_pvtUnique data
Return values
0on success
-1on failure

Example usage:

* struct ast_bridge_features 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 1274 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::hook_pvt, and ast_bridge_features::usable.

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

1275 {
1276  struct ast_bridge_features_hook *hook = NULL;
1277 
1278  /* Allocate new memory and setup it's various variables */
1279  if (!(hook = ast_calloc(1, sizeof(*hook)))) {
1280  return -1;
1281  }
1282 
1283  ast_copy_string(hook->dtmf, dtmf, sizeof(hook->dtmf));
1284  hook->callback = callback;
1285  hook->hook_pvt = hook_pvt;
1286 
1287  /* Once done we add it onto the list. Now it will be picked up when DTMF is used */
1288  AST_LIST_INSERT_TAIL(&features->hooks, hook, entry);
1289 
1290  features->usable = 1;
1291 
1292  return 0;
1293 }
char dtmf[MAXIMUM_DTMF_FEATURE_STRING]
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
#define ast_calloc(a, b)
Definition: astmm.h:82
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:223
ast_bridge_features_hook_callback callback
Structure that is the essence of a features hook.
int ast_bridge_features_init ( struct ast_bridge_features features)

Initialize bridge features structure.

Parameters
featuresBridge featues structure
Return values
0on success
-1on failure

Example usage:

* struct ast_bridge_features 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 1322 of file bridging.c.

References AST_LIST_HEAD_INIT_NOLOCK.

Referenced by confbridge_exec(), and feature_attended_transfer().

1323 {
1324  /* Zero out the structure */
1325  memset(features, 0, sizeof(*features));
1326 
1327  /* Initialize the hooks list, just in case */
1328  AST_LIST_HEAD_INIT_NOLOCK(&features->hooks);
1329 
1330  return 0;
1331 }
#define AST_LIST_HEAD_INIT_NOLOCK(head)
Initializes a list head structure.
Definition: linkedlists.h:666
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
featureThe feature that the handler will be responsible for
callbackThe callback function that will handle it
dtmfDefault DTMF string used to activate the feature
Return values
0on success
-1on 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 1248 of file bridging.c.

References ast_copy_string(), and ast_strlen_zero().

Referenced by load_module().

1249 {
1250  if (builtin_features_handlers[feature]) {
1251  return -1;
1252  }
1253 
1254  if (!ast_strlen_zero(dtmf)) {
1255  ast_copy_string(builtin_features_dtmf[feature], dtmf, sizeof(builtin_features_dtmf[feature]));
1256  }
1257 
1258  builtin_features_handlers[feature] = callback;
1259 
1260  return 0;
1261 }
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
static void * builtin_features_handlers[AST_BRIDGE_BUILTIN_END]
Definition: bridging.c:61
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:223
static char builtin_features_dtmf[AST_BRIDGE_BUILTIN_END][MAXIMUM_DTMF_FEATURE_STRING]
Definition: bridging.c:58
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
featuresBridge features structure
flagFlag to enable
Return values
0on success
-1on failure

Example usage:

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

Definition at line 1315 of file bridging.c.

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

Referenced by feature_attended_transfer().

1316 {
1317  ast_set_flag(&features->feature_flags, flag);
1318  features->usable = 1;
1319  return 0;
1320 }
#define ast_set_flag(p, flag)
Definition: utils.h:70
struct ast_flags feature_flags
int ast_bridge_features_unregister ( enum ast_bridge_builtin_feature  feature)

Unregister a handler for a built in feature.

Parameters
featureThe feature to unregister
Return values
0on success
-1on 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 1263 of file bridging.c.

1264 {
1265  if (!builtin_features_handlers[feature]) {
1266  return -1;
1267  }
1268 
1269  builtin_features_handlers[feature] = NULL;
1270 
1271  return 0;
1272 }
static void * builtin_features_handlers[AST_BRIDGE_BUILTIN_END]
Definition: bridging.c:61