bridging.h File Reference

Channel Bridging API. More...

#include "asterisk/bridging_features.h"

Include dependency graph for bridging.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_bridge
	Structure that contains information about a bridge. More...
struct	ast_bridge_channel
	Structure that contains information regarding a channel in a bridge. More...
Enumerations
enum	ast_bridge_capability {   AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1), AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2), AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3), AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4),   AST_BRIDGE_CAPABILITY_THREAD = (1 << 5), AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6), AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7) }
	Capabilities for a bridge technology. More...
enum	ast_bridge_channel_state {   AST_BRIDGE_CHANNEL_STATE_WAIT = 0, AST_BRIDGE_CHANNEL_STATE_END, AST_BRIDGE_CHANNEL_STATE_HANGUP, AST_BRIDGE_CHANNEL_STATE_DEPART,   AST_BRIDGE_CHANNEL_STATE_FEATURE, AST_BRIDGE_CHANNEL_STATE_DTMF }
	State information about a bridged channel. More...
enum	ast_bridge_write_result { AST_BRIDGE_WRITE_SUCCESS = 0, AST_BRIDGE_WRITE_FAILED, AST_BRIDGE_WRITE_UNSUPPORTED }
	Return values for bridge technology write function. More...
Functions
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.
int	ast_bridge_check (int capabilities)
	See if it is possible to create a bridge.
int	ast_bridge_depart (struct ast_bridge *bridge, struct ast_channel *chan)
	Depart a channel from a bridge.
int	ast_bridge_destroy (struct ast_bridge *bridge)
	Destroy a bridge.
int	ast_bridge_impart (struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features)
	Impart (non-blocking) a channel on a bridge.
enum ast_bridge_channel_state	ast_bridge_join (struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features)
	Join (blocking) a channel to a bridge.
int	ast_bridge_merge (struct ast_bridge *bridge0, struct ast_bridge *bridge1)
	Merge two bridges together.
struct ast_bridge *	ast_bridge_new (int capabilities, int flags)
	Create a new bridge.
int	ast_bridge_remove (struct ast_bridge *bridge, struct ast_channel *chan)
	Remove a channel from a bridge.
int	ast_bridge_suspend (struct ast_bridge *bridge, struct ast_channel *chan)
	Suspend a channel temporarily from a bridge.
int	ast_bridge_unsuspend (struct ast_bridge *bridge, struct ast_channel *chan)
	Unsuspend a channel from a bridge.

---

Detailed Description

Channel Bridging API.

Author:

Joshua Colp <jcolp@digium.com> Channel Bridging API

Definition in file bridging.h.

---

Enumeration Type Documentation

enum ast_bridge_capability

Capabilities for a bridge technology.

Enumerator:

AST_BRIDGE_CAPABILITY_1TO1MIX	Bridge is only capable of mixing 2 channels
AST_BRIDGE_CAPABILITY_MULTIMIX	Bridge is capable of mixing 2 or more channels
AST_BRIDGE_CAPABILITY_NATIVE	Bridge should natively bridge two channels if possible
AST_BRIDGE_CAPABILITY_MULTITHREADED	Bridge should run using the multithreaded model
AST_BRIDGE_CAPABILITY_THREAD	Bridge should run a central bridge thread
AST_BRIDGE_CAPABILITY_VIDEO	Bridge technology can do video mixing (or something along those lines)
AST_BRIDGE_CAPABILITY_OPTIMIZE	Bridge technology can optimize things based on who is talking

Definition at line 68 of file bridging.h.

                           {
   /*! Bridge is only capable of mixing 2 channels */
   AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1),
   /*! Bridge is capable of mixing 2 or more channels */
   AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2),
   /*! Bridge should natively bridge two channels if possible */
   AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3),
   /*! Bridge should run using the multithreaded model */
   AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4),
   /*! Bridge should run a central bridge thread */
   AST_BRIDGE_CAPABILITY_THREAD = (1 << 5),
   /*! Bridge technology can do video mixing (or something along those lines) */
   AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6),
   /*! Bridge technology can optimize things based on who is talking */
   AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7),
};

enum ast_bridge_channel_state

State information about a bridged channel.

Enumerator:

AST_BRIDGE_CHANNEL_STATE_WAIT	Waiting for a signal
AST_BRIDGE_CHANNEL_STATE_END	Bridged channel has ended itself (it has hung up)
AST_BRIDGE_CHANNEL_STATE_HANGUP	Bridged channel should be hung up
AST_BRIDGE_CHANNEL_STATE_DEPART	Bridged channel should be removed from the bridge without being hung up
AST_BRIDGE_CHANNEL_STATE_FEATURE	Bridged channel is executing a feature hook
AST_BRIDGE_CHANNEL_STATE_DTMF	Bridged channel is sending a DTMF stream out

Definition at line 86 of file bridging.h.

                              {
   /*! Waiting for a signal */
   AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
   /*! Bridged channel has ended itself (it has hung up) */
   AST_BRIDGE_CHANNEL_STATE_END,
   /*! Bridged channel should be hung up */
   AST_BRIDGE_CHANNEL_STATE_HANGUP,
   /*! Bridged channel should be removed from the bridge without being hung up */
   AST_BRIDGE_CHANNEL_STATE_DEPART,
   /*! Bridged channel is executing a feature hook */
   AST_BRIDGE_CHANNEL_STATE_FEATURE,
   /*! Bridged channel is sending a DTMF stream out */
   AST_BRIDGE_CHANNEL_STATE_DTMF,
};

enum ast_bridge_write_result

Return values for bridge technology write function.

Enumerator:

AST_BRIDGE_WRITE_SUCCESS	Bridge technology wrote out frame fine
AST_BRIDGE_WRITE_FAILED	Bridge technology attempted to write out the frame but failed
AST_BRIDGE_WRITE_UNSUPPORTED	Bridge technology does not support writing out a frame of this type

Definition at line 102 of file bridging.h.

                             {
   /*! Bridge technology wrote out frame fine */
   AST_BRIDGE_WRITE_SUCCESS = 0,
   /*! Bridge technology attempted to write out the frame but failed */
   AST_BRIDGE_WRITE_FAILED,
   /*! Bridge technology does not support writing out a frame of this type */
   AST_BRIDGE_WRITE_UNSUPPORTED,
};

---

Function Documentation

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.

Parameters:

	bridge_channel	Channel to change the state on
	new_state	The new state to place the channel into

Example usage:

 ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT);

This places the channel pointed to by bridge_channel into the state AST_BRIDGE_CHANNEL_STATE_WAIT.

Note:

This API call is only meant to be used in feature hook callbacks to make sure the channel either hangs up or returns to the bridge.

Definition at line 118 of file bridging.c.

References ast_cond_signal(), ast_mutex_lock(), ast_mutex_unlock(), ast_bridge_channel::cond, ast_bridge_channel::lock, ast_bridge_channel::state, and ast_bridge_channel::thread.

Referenced by ast_bridge_depart(), ast_bridge_destroy(), ast_bridge_dtmf_stream(), ast_bridge_handle_trip(), ast_bridge_remove(), attended_abort_transfer(), attended_threeway_transfer(), bridge_channel_dtmf_stream(), bridge_channel_feature(), bridge_channel_join(), bridge_check_dissolve(), bridge_handle_dtmf(), feature_attended_transfer(), feature_blind_transfer(), and feature_hangup().

{
   /* Change the state on the bridge channel */
   bridge_channel->state = new_state;

   /* Only poke the channel's thread if it is not us */
   if (!pthread_equal(pthread_self(), bridge_channel->thread)) {
      pthread_kill(bridge_channel->thread, SIGURG);
      ast_mutex_lock(&bridge_channel->lock);
      ast_cond_signal(&bridge_channel->cond);
      ast_mutex_unlock(&bridge_channel->lock);
   }

   return;
}

int ast_bridge_check

(

int

capabilities

)

See if it is possible to create a bridge.

Parameters:

capabilities

The capabilities that the bridge will use

Return values:

	1	if possible
	0	if not possible

Example usage:

 int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX);

This sees if it is possible to create a bridge capable of bridging two channels together.

Definition at line 501 of file bridging.c.

References ast_module_unref(), find_best_technology(), and ast_bridge_technology::mod.

{
   struct ast_bridge_technology *bridge_technology = NULL;

   if (!(bridge_technology = find_best_technology(capabilities))) {
      return 0;
   }

   ast_module_unref(bridge_technology->mod);

   return 1;
}

int ast_bridge_depart	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan
	)

Depart a channel from a bridge.

Parameters:

	bridge	Bridge to depart from
	chan	Channel to depart

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_depart(bridge, chan);

This removes the channel pointed to by the chan pointer from the bridge pointed to by the bridge pointer and gives control to the calling thread. This does not hang up the channel.

Note:

This API call can only be used on channels that were added to the bridge using the ast_bridge_impart API call.

Definition at line 1064 of file bridging.c.

References ao2_lock(), ao2_unlock(), ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_DEPART, find_bridge_channel(), ast_bridge_channel::thread, and thread.

Referenced by feature_attended_transfer(), and play_sound_file().

{
   struct ast_bridge_channel *bridge_channel = NULL;
   pthread_t thread;

   ao2_lock(bridge);

   /* Try to find the channel that we want to depart */
   if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
      ao2_unlock(bridge);
      return -1;
   }

   ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_DEPART);
   thread = bridge_channel->thread;

   ao2_unlock(bridge);

   pthread_join(thread, NULL);

   return 0;
}

int ast_bridge_destroy

(

struct ast_bridge *

bridge

)

Destroy a bridge.

Parameters:

bridge

Bridge to destroy

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_destroy(bridge);

This destroys a bridge that was previously created using ast_bridge_new.

Definition at line 514 of file bridging.c.

References ao2_lock(), ao2_ref, ao2_unlock(), ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_END, ast_debug, AST_LIST_TRAVERSE, bridge_poke(), ast_bridge::channels, ast_bridge_channel::entry, and ast_bridge::stop.

Referenced by ast_bridge_new(), destroy_conference_bridge(), and feature_attended_transfer().

{
   struct ast_bridge_channel *bridge_channel = NULL;

   ao2_lock(bridge);

   bridge->stop = 1;

   bridge_poke(bridge);

   ast_debug(1, "Telling all channels in bridge %p to end and leave the party\n", bridge);

   /* Drop every bridged channel, the last one will cause the bridge thread (if it exists) to exit */
   AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
      ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
   }

   ao2_unlock(bridge);

   ao2_ref(bridge, -1);

   return 0;
}

int ast_bridge_impart	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan,
		struct ast_channel *	swap,
		struct ast_bridge_features *	features
	)

Impart (non-blocking) a channel on a bridge.

Parameters:

	bridge	Bridge to impart on
	chan	Channel to impart
	swap	Channel to swap out if swapping
	features	Bridge features structure

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_impart(bridge, chan, NULL, NULL);

This adds a channel pointed to by the chan pointer to the bridge pointed to by the bridge pointer. This function will return immediately and will not wait until the channel is no longer part of the bridge.

If this channel will be replacing another channel the other channel can be specified in the swap parameter. The other channel will be thrown out of the bridge in an atomic fashion.

If channel specific features are enabled a pointer to the features structure can be specified in the features parameter.

Definition at line 1030 of file bridging.c.

References ao2_ref, ast_calloc, ast_cond_destroy(), ast_cond_init(), ast_free, ast_mutex_destroy(), ast_mutex_init(), ast_pthread_create, ast_bridge_channel::bridge, bridge_channel_thread(), ast_bridge_channel::chan, ast_bridge_channel::cond, ast_bridge_channel::features, ast_bridge_channel::lock, ast_bridge_channel::swap, and ast_bridge_channel::thread.

Referenced by bridge_call(), feature_attended_transfer(), feature_blind_transfer(), and play_sound_file().

{
   struct ast_bridge_channel *bridge_channel = NULL;

   /* Try to allocate a structure for the bridge channel */
   if (!(bridge_channel = ast_calloc(1, sizeof(*bridge_channel)))) {
      return -1;
   }

   /* Setup various parameters */
   bridge_channel->chan = chan;
   bridge_channel->swap = swap;
   bridge_channel->bridge = bridge;
   bridge_channel->features = features;

   /* Initialize our mutex lock and condition */
   ast_mutex_init(&bridge_channel->lock);
   ast_cond_init(&bridge_channel->cond, NULL);

   /* Bump up the reference count on the bridge, it'll get decremented later */
   ao2_ref(bridge, +1);

   /* Actually create the thread that will handle the channel */
   if (ast_pthread_create(&bridge_channel->thread, NULL, bridge_channel_thread, bridge_channel)) {
      ao2_ref(bridge, -1);
      ast_cond_destroy(&bridge_channel->cond);
      ast_mutex_destroy(&bridge_channel->lock);
      ast_free(bridge_channel);
      return -1;
   }

   return 0;
}

enum ast_bridge_channel_state ast_bridge_join	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan,
		struct ast_channel *	swap,
		struct ast_bridge_features *	features
	)

Join (blocking) a channel to a bridge.

Parameters:

	bridge	Bridge to join
	chan	Channel to join
	swap	Channel to swap out if swapping
	features	Bridge features structure

Return values:

state

that channel exited the bridge with

Example usage:

 ast_bridge_join(bridge, chan, NULL, NULL);

This adds a channel pointed to by the chan pointer to the bridge pointed to by the bridge pointer. This function will not return until the channel has been removed from the bridge, swapped out for another channel, or has hung up.

If this channel will be replacing another channel the other channel can be specified in the swap parameter. The other channel will be thrown out of the bridge in an atomic fashion.

If channel specific features are enabled a pointer to the features structure can be specified in the features parameter.

Definition at line 980 of file bridging.c.

References ao2_ref, ast_cond_destroy(), ast_cond_init(), ast_mutex_destroy(), ast_mutex_init(), ast_bridge_channel::bridge, ast_channel::bridge, bridge_channel_join(), ast_bridge_channel::chan, ast_bridge_channel::cond, ast_bridge::features, and ast_bridge_channel::lock.

Referenced by confbridge_exec(), and feature_attended_transfer().

{
   struct ast_bridge_channel bridge_channel = {
      .chan = chan,
      .swap = swap,
      .bridge = bridge,
      .features = features,
   };
   enum ast_bridge_channel_state state;

   /* Initialize various other elements of the bridge channel structure that we can't do above */
   ast_mutex_init(&bridge_channel.lock);
   ast_cond_init(&bridge_channel.cond, NULL);

   ao2_ref(bridge_channel.bridge, +1);

   state = bridge_channel_join(&bridge_channel);

   ao2_ref(bridge_channel.bridge, -1);

   /* Destroy some elements of the bridge channel structure above */
   ast_mutex_destroy(&bridge_channel.lock);
   ast_cond_destroy(&bridge_channel.cond);

   return state;
}

int ast_bridge_merge	(	struct ast_bridge *	bridge0,
		struct ast_bridge *	bridge1
	)

Merge two bridges together.

Parameters:

	bridge0	First bridge
	bridge1	Second bridge

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_merge(bridge0, bridge1);

This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0. In reality all of the channels in bridge1 are simply moved to bridge0.

Note:

The second bridge specified is not destroyed when this operation is completed.

Definition at line 1106 of file bridging.c.

References ao2_lock(), ao2_ref, ao2_unlock(), AST_BRIDGE_CAPABILITY_MULTIMIX, AST_BRIDGE_FLAG_SMART, ast_cond_signal(), ast_debug, AST_LIST_INSERT_TAIL, AST_LIST_REMOVE_HEAD, ast_mutex_lock(), ast_mutex_unlock(), AST_PTHREADT_STOP, ast_test_flag, ast_bridge_channel::bridge, bridge_array_add(), bridge_array_remove(), bridge_make_compatible(), ast_bridge_technology::capabilities, ast_bridge_channel::chan, ast_bridge::channels, ast_bridge_channel::cond, ast_bridge_channel::entry, ast_bridge::feature_flags, ast_bridge_technology::join, ast_bridge_technology::leave, ast_bridge_channel::lock, ast_bridge_technology::name, ast_bridge::num, smart_bridge_operation(), ast_bridge::technology, ast_bridge_channel::thread, and ast_bridge::thread.

{
   struct ast_bridge_channel *bridge_channel = NULL;

   ao2_lock(bridge0);
   ao2_lock(bridge1);

   /* If the first bridge currently has 2 channels and is not capable of becoming a multimixing bridge we can not merge */
   if ((bridge0->num + bridge1->num) > 2 && (!(bridge0->technology->capabilities & AST_BRIDGE_CAPABILITY_MULTIMIX) && !ast_test_flag(&bridge0->feature_flags, AST_BRIDGE_FLAG_SMART))) {
      ao2_unlock(bridge1);
      ao2_unlock(bridge0);
      ast_debug(1, "Can't merge bridge %p into bridge %p, multimix is needed and it could not be acquired.\n", bridge1, bridge0);
      return -1;
   }

   ast_debug(1, "Merging channels from bridge %p into bridge %p\n", bridge1, bridge0);

   /* Perform smart bridge operation on bridge we are merging into so it can change bridge technology if needed */
   if (smart_bridge_operation(bridge0, NULL, bridge0->num + bridge1->num)) {
      ao2_unlock(bridge1);
      ao2_unlock(bridge0);
      ast_debug(1, "Can't merge bridge %p into bridge %p, tried to perform smart bridge operation and failed.\n", bridge1, bridge0);
      return -1;
   }

   /* If a thread is currently executing on bridge1 tell it to stop */
   if (bridge1->thread) {
      ast_debug(1, "Telling bridge thread on bridge %p to stop as it is being merged into %p\n", bridge1, bridge0);
      bridge1->thread = AST_PTHREADT_STOP;
   }

   /* Move channels from bridge1 over to bridge0 */
   while ((bridge_channel = AST_LIST_REMOVE_HEAD(&bridge1->channels, entry))) {
      /* Tell the technology handling bridge1 that the bridge channel is leaving */
      if (bridge1->technology->leave) {
         ast_debug(1, "Giving bridge technology %s notification that %p is leaving bridge %p\n", bridge1->technology->name, bridge_channel, bridge1);
         if (bridge1->technology->leave(bridge1, bridge_channel)) {
            ast_debug(1, "Bridge technology %s failed to allow %p to leave bridge %p\n", bridge1->technology->name, bridge_channel, bridge1);
         }
      }

      /* Drop channel count and reference count on the bridge they are leaving */
      bridge1->num--;
      ao2_ref(bridge1, -1);

      bridge_array_remove(bridge1, bridge_channel->chan);

      /* Now add them into the bridge they are joining, increase channel count, and bump up reference count */
      bridge_channel->bridge = bridge0;
      AST_LIST_INSERT_TAIL(&bridge0->channels, bridge_channel, entry);
      bridge0->num++;
      ao2_ref(bridge0, +1);

      bridge_array_add(bridge0, bridge_channel->chan);

      /* Make the channel compatible with the new bridge it is joining or else formats would go amuck */
      bridge_make_compatible(bridge0, bridge_channel);

      /* Tell the technology handling bridge0 that the bridge channel is joining */
      if (bridge0->technology->join) {
         ast_debug(1, "Giving bridge technology %s notification that %p is joining bridge %p\n", bridge0->technology->name, bridge_channel, bridge0);
         if (bridge0->technology->join(bridge0, bridge_channel)) {
            ast_debug(1, "Bridge technology %s failed to join %p to bridge %p\n", bridge0->technology->name, bridge_channel, bridge0);
         }
      }

      /* Poke the bridge channel, this will cause it to wake up and execute the proper threading model for the new bridge it is in */
      pthread_kill(bridge_channel->thread, SIGURG);
      ast_mutex_lock(&bridge_channel->lock);
      ast_cond_signal(&bridge_channel->cond);
      ast_mutex_unlock(&bridge_channel->lock);
   }

   ast_debug(1, "Merged channels from bridge %p into bridge %p\n", bridge1, bridge0);

   ao2_unlock(bridge1);
   ao2_unlock(bridge0);

   return 0;
}

struct ast_bridge* ast_bridge_new	(	int	capabilities,
		int	flags
	)			[read]

Create a new bridge.

Parameters:

	capabilities	The capabilities that we require to be used on the bridge
	flags	Flags that will alter the behavior of the bridge

Return values:

	a	pointer to a new bridge on success
	NULL	on failure

Example usage:

 struct ast_bridge *bridge;
 bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE);

This creates a simple two party bridge that will be destroyed once one of the channels hangs up.

Definition at line 448 of file bridging.c.

References ao2_alloc, ao2_ref, ast_bridge::array, ast_bridge::array_size, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_CAPABILITY_MULTIMIX, ast_bridge_destroy(), AST_BRIDGE_FLAG_SMART, ast_bridge_new(), ast_calloc, ast_debug, AST_PTHREADT_NULL, ast_set_flag, BRIDGE_ARRAY_START, ast_bridge_technology::create, destroy_bridge(), ast_bridge::feature_flags, find_best_technology(), ast_bridge_technology::name, ast_bridge::technology, and ast_bridge::thread.

Referenced by ast_bridge_new(), feature_attended_transfer(), and join_conference_bridge().

{
   struct ast_bridge *bridge = NULL;
   struct ast_bridge_technology *bridge_technology = NULL;

   /* If we need to be a smart bridge see if we can move between 1to1 and multimix bridges */
   if (flags & AST_BRIDGE_FLAG_SMART) {
      struct ast_bridge *other_bridge;

      if (!(other_bridge = ast_bridge_new((capabilities & AST_BRIDGE_CAPABILITY_1TO1MIX) ? AST_BRIDGE_CAPABILITY_MULTIMIX : AST_BRIDGE_CAPABILITY_1TO1MIX, 0))) {
         return NULL;
      }

      ast_bridge_destroy(other_bridge);
   }

   /* If capabilities were provided use our helper function to find the "best" bridge technology, otherwise we can
    * just look for the most basic capability needed, single 1to1 mixing. */
   bridge_technology = (capabilities ? find_best_technology(capabilities) : find_best_technology(AST_BRIDGE_CAPABILITY_1TO1MIX));

   /* If no bridge technology was found we can't possibly do bridging so fail creation of the bridge */
   if (!bridge_technology) {
      ast_debug(1, "Failed to find a bridge technology to satisfy capabilities %d\n", capabilities);
      return NULL;
   }

   /* We have everything we need to create this bridge... so allocate the memory, link things together, and fire her up! */
   if (!(bridge = ao2_alloc(sizeof(*bridge), destroy_bridge))) {
      return NULL;
   }

   bridge->technology = bridge_technology;
   bridge->thread = AST_PTHREADT_NULL;

   /* Create an array of pointers for the channels that will be joining us */
   bridge->array = ast_calloc(BRIDGE_ARRAY_START, sizeof(struct ast_channel*));
   bridge->array_size = BRIDGE_ARRAY_START;

   ast_set_flag(&bridge->feature_flags, flags);

   /* Pass off the bridge to the technology to manipulate if needed */
   if (bridge->technology->create) {
      ast_debug(1, "Giving bridge technology %s the bridge structure %p to setup\n", bridge->technology->name, bridge);
      if (bridge->technology->create(bridge)) {
         ast_debug(1, "Bridge technology %s failed to setup bridge structure %p\n", bridge->technology->name, bridge);
         ao2_ref(bridge, -1);
         bridge = NULL;
      }
   }

   return bridge;
}

int ast_bridge_remove	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan
	)

Remove a channel from a bridge.

Parameters:

	bridge	Bridge that the channel is to be removed from
	chan	Channel to remove

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_remove(bridge, chan);

This removes the channel pointed to by the chan pointer from the bridge pointed to by the bridge pointer and requests that it be hung up. Control over the channel will NOT be given to the calling thread.

Note:

This API call can be used on channels that were added to the bridge using both ast_bridge_join and ast_bridge_impart.

Definition at line 1087 of file bridging.c.

References ao2_lock(), ao2_unlock(), ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_HANGUP, and find_bridge_channel().

Referenced by menu_callback().

{
   struct ast_bridge_channel *bridge_channel = NULL;

   ao2_lock(bridge);

   /* Try to find the channel that we want to remove */
   if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
      ao2_unlock(bridge);
      return -1;
   }

   ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_HANGUP);

   ao2_unlock(bridge);

   return 0;
}

int ast_bridge_suspend	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan
	)

Suspend a channel temporarily from a bridge.

Parameters:

	bridge	Bridge to suspend the channel from
	chan	Channel to suspend

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_suspend(bridge, chan);

This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily. Control of the channel is given to the calling thread. This differs from ast_bridge_depart as the channel will not be removed from the bridge.

Note:

This API call can be used on channels that were added to the bridge using both ast_bridge_join and ast_bridge_impart.

Definition at line 1187 of file bridging.c.

References ao2_lock(), ao2_unlock(), bridge_channel_suspend(), and find_bridge_channel().

Referenced by leave_conference_bridge(), post_join_marked(), and post_join_unmarked().

{
   struct ast_bridge_channel *bridge_channel;

   ao2_lock(bridge);

   if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
      ao2_unlock(bridge);
      return -1;
   }

   bridge_channel_suspend(bridge, bridge_channel);

   ao2_unlock(bridge);

   return 0;
}

int ast_bridge_unsuspend	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan
	)

Unsuspend a channel from a bridge.

Parameters:

	bridge	Bridge to unsuspend the channel from
	chan	Channel to unsuspend

Return values:

	0	on success
	-1	on failure

Example usage:

 ast_bridge_unsuspend(bridge, chan);

This unsuspends the channel pointed to by chan from the bridge pointed to by bridge. The bridge will go back to handling the channel once this function returns.

Note:

You must not mess with the channel once this function returns. Doing so may result in bad things happening.

Definition at line 1205 of file bridging.c.

References ao2_lock(), ao2_unlock(), bridge_channel_unsuspend(), and find_bridge_channel().

Referenced by leave_conference_bridge(), post_join_marked(), and post_join_unmarked().

{
   struct ast_bridge_channel *bridge_channel;

   ao2_lock(bridge);

   if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
      ao2_unlock(bridge);
      return -1;
   }

   bridge_channel_unsuspend(bridge, bridge_channel);

   ao2_unlock(bridge);

   return 0;
}