Channel Bridging API. More...

This graph shows which files directly or indirectly include 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.

                                {
   /*! 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,
};

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.

                              {
   /*! 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),
};

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

Parameters:

features Bridge features structure

Return values:

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

Note:: This MUST be called after the features structure is done being used or a memory leak may occur.

Definition at line 1327 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.

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:

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

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

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

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

Parameters:

features	Bridge features structure
flag	Flag to enable

Return values:

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

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

{
   if (!builtin_features_handlers[feature]) {
      return -1;
   }

   builtin_features_handlers[feature] = NULL;

   return 0;
}

Asterisk developer's documentation

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation