Mon Mar 19 11:30:36 2012

Asterisk developer's documentation


bridging.h File Reference

Channel Bridging API. More...

#include "asterisk/bridging_features.h"

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 (enum ast_bridge_capability 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.
ast_bridgeast_bridge_new (enum ast_bridge_capability 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.

00068                            {
00069    /*! Bridge is only capable of mixing 2 channels */
00070    AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1),
00071    /*! Bridge is capable of mixing 2 or more channels */
00072    AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2),
00073    /*! Bridge should natively bridge two channels if possible */
00074    AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3),
00075    /*! Bridge should run using the multithreaded model */
00076    AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4),
00077    /*! Bridge should run a central bridge thread */
00078    AST_BRIDGE_CAPABILITY_THREAD = (1 << 5),
00079    /*! Bridge technology can do video mixing (or something along those lines) */
00080    AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6),
00081    /*! Bridge technology can optimize things based on who is talking */
00082    AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7),
00083 };

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.

00086                               {
00087    /*! Waiting for a signal */
00088    AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
00089    /*! Bridged channel has ended itself (it has hung up) */
00090    AST_BRIDGE_CHANNEL_STATE_END,
00091    /*! Bridged channel should be hung up */
00092    AST_BRIDGE_CHANNEL_STATE_HANGUP,
00093    /*! Bridged channel should be removed from the bridge without being hung up */
00094    AST_BRIDGE_CHANNEL_STATE_DEPART,
00095    /*! Bridged channel is executing a feature hook */
00096    AST_BRIDGE_CHANNEL_STATE_FEATURE,
00097    /*! Bridged channel is sending a DTMF stream out */
00098    AST_BRIDGE_CHANNEL_STATE_DTMF,
00099 };

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.

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


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:

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

00119 {
00120    /* Change the state on the bridge channel */
00121    bridge_channel->state = new_state;
00122 
00123    /* Only poke the channel's thread if it is not us */
00124    if (!pthread_equal(pthread_self(), bridge_channel->thread)) {
00125       pthread_kill(bridge_channel->thread, SIGURG);
00126       ast_mutex_lock(&bridge_channel->lock);
00127       ast_cond_signal(&bridge_channel->cond);
00128       ast_mutex_unlock(&bridge_channel->lock);
00129    }
00130 
00131    return;
00132 }

int ast_bridge_check ( enum ast_bridge_capability  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:

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.

00502 {
00503    struct ast_bridge_technology *bridge_technology = NULL;
00504 
00505    if (!(bridge_technology = find_best_technology(capabilities))) {
00506       return 0;
00507    }
00508 
00509    ast_module_unref(bridge_technology->mod);
00510 
00511    return 1;
00512 }

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

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

Referenced by feature_attended_transfer(), and play_sound_file().

01072 {
01073    struct ast_bridge_channel *bridge_channel = NULL;
01074    pthread_t thread;
01075 
01076    ao2_lock(bridge);
01077 
01078    /* Try to find the channel that we want to depart */
01079    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01080       ao2_unlock(bridge);
01081       return -1;
01082    }
01083 
01084    ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_DEPART);
01085    thread = bridge_channel->thread;
01086 
01087    ao2_unlock(bridge);
01088 
01089    pthread_join(thread, NULL);
01090 
01091    return 0;
01092 }

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:

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, ast_bridge_channel::bridge, bridge_poke(), and ast_bridge::stop.

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

00515 {
00516    struct ast_bridge_channel *bridge_channel = NULL;
00517 
00518    ao2_lock(bridge);
00519 
00520    bridge->stop = 1;
00521 
00522    bridge_poke(bridge);
00523 
00524    ast_debug(1, "Telling all channels in bridge %p to end and leave the party\n", bridge);
00525 
00526    /* Drop every bridged channel, the last one will cause the bridge thread (if it exists) to exit */
00527    AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
00528       ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
00529    }
00530 
00531    ao2_unlock(bridge);
00532 
00533    ao2_ref(bridge, -1);
00534 
00535    return 0;
00536 }

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 1037 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_channel::bridge, ast_bridge_channel::bridge, bridge_channel_thread(), ast_bridge_channel::chan, ast_bridge::features, ast_bridge_channel::features, and ast_bridge_channel::swap.

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

01038 {
01039    struct ast_bridge_channel *bridge_channel = NULL;
01040 
01041    /* Try to allocate a structure for the bridge channel */
01042    if (!(bridge_channel = ast_calloc(1, sizeof(*bridge_channel)))) {
01043       return -1;
01044    }
01045 
01046    /* Setup various parameters */
01047    bridge_channel->chan = chan;
01048    bridge_channel->swap = swap;
01049    bridge_channel->bridge = bridge;
01050    bridge_channel->features = features;
01051 
01052    /* Initialize our mutex lock and condition */
01053    ast_mutex_init(&bridge_channel->lock);
01054    ast_cond_init(&bridge_channel->cond, NULL);
01055 
01056    /* Bump up the reference count on the bridge, it'll get decremented later */
01057    ao2_ref(bridge, +1);
01058 
01059    /* Actually create the thread that will handle the channel */
01060    if (ast_pthread_create(&bridge_channel->thread, NULL, bridge_channel_thread, bridge_channel)) {
01061       ao2_ref(bridge, -1);
01062       ast_cond_destroy(&bridge_channel->cond);
01063       ast_mutex_destroy(&bridge_channel->lock);
01064       ast_free(bridge_channel);
01065       return -1;
01066    }
01067 
01068    return 0;
01069 }

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

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

Referenced by confbridge_exec(), and feature_attended_transfer().

00988 {
00989    struct ast_bridge_channel bridge_channel = {
00990       .chan = chan,
00991       .swap = swap,
00992       .bridge = bridge,
00993       .features = features,
00994    };
00995    enum ast_bridge_channel_state state;
00996 
00997    /* Initialize various other elements of the bridge channel structure that we can't do above */
00998    ast_mutex_init(&bridge_channel.lock);
00999    ast_cond_init(&bridge_channel.cond, NULL);
01000 
01001    ao2_ref(bridge_channel.bridge, +1);
01002 
01003    state = bridge_channel_join(&bridge_channel);
01004 
01005    ao2_ref(bridge_channel.bridge, -1);
01006 
01007    /* Destroy some elements of the bridge channel structure above */
01008    ast_mutex_destroy(&bridge_channel.lock);
01009    ast_cond_destroy(&bridge_channel.cond);
01010 
01011    return state;
01012 }

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 1113 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_channel::cond, 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::thread, and ast_bridge_channel::thread.

01114 {
01115    struct ast_bridge_channel *bridge_channel = NULL;
01116 
01117    ao2_lock(bridge0);
01118    ao2_lock(bridge1);
01119 
01120    /* If the first bridge currently has 2 channels and is not capable of becoming a multimixing bridge we can not merge */
01121    if ((bridge0->num + bridge1->num) > 2 && (!(bridge0->technology->capabilities & AST_BRIDGE_CAPABILITY_MULTIMIX) && !ast_test_flag(&bridge0->feature_flags, AST_BRIDGE_FLAG_SMART))) {
01122       ao2_unlock(bridge1);
01123       ao2_unlock(bridge0);
01124       ast_debug(1, "Can't merge bridge %p into bridge %p, multimix is needed and it could not be acquired.\n", bridge1, bridge0);
01125       return -1;
01126    }
01127 
01128    ast_debug(1, "Merging channels from bridge %p into bridge %p\n", bridge1, bridge0);
01129 
01130    /* Perform smart bridge operation on bridge we are merging into so it can change bridge technology if needed */
01131    if (smart_bridge_operation(bridge0, NULL, bridge0->num + bridge1->num)) {
01132       ao2_unlock(bridge1);
01133       ao2_unlock(bridge0);
01134       ast_debug(1, "Can't merge bridge %p into bridge %p, tried to perform smart bridge operation and failed.\n", bridge1, bridge0);
01135       return -1;
01136    }
01137 
01138    /* If a thread is currently executing on bridge1 tell it to stop */
01139    if (bridge1->thread) {
01140       ast_debug(1, "Telling bridge thread on bridge %p to stop as it is being merged into %p\n", bridge1, bridge0);
01141       bridge1->thread = AST_PTHREADT_STOP;
01142    }
01143 
01144    /* Move channels from bridge1 over to bridge0 */
01145    while ((bridge_channel = AST_LIST_REMOVE_HEAD(&bridge1->channels, entry))) {
01146       /* Tell the technology handling bridge1 that the bridge channel is leaving */
01147       if (bridge1->technology->leave) {
01148          ast_debug(1, "Giving bridge technology %s notification that %p is leaving bridge %p\n", bridge1->technology->name, bridge_channel, bridge1);
01149          if (bridge1->technology->leave(bridge1, bridge_channel)) {
01150             ast_debug(1, "Bridge technology %s failed to allow %p to leave bridge %p\n", bridge1->technology->name, bridge_channel, bridge1);
01151          }
01152       }
01153 
01154       /* Drop channel count and reference count on the bridge they are leaving */
01155       bridge1->num--;
01156       ao2_ref(bridge1, -1);
01157 
01158       bridge_array_remove(bridge1, bridge_channel->chan);
01159 
01160       /* Now add them into the bridge they are joining, increase channel count, and bump up reference count */
01161       bridge_channel->bridge = bridge0;
01162       AST_LIST_INSERT_TAIL(&bridge0->channels, bridge_channel, entry);
01163       bridge0->num++;
01164       ao2_ref(bridge0, +1);
01165 
01166       bridge_array_add(bridge0, bridge_channel->chan);
01167 
01168       /* Make the channel compatible with the new bridge it is joining or else formats would go amuck */
01169       bridge_make_compatible(bridge0, bridge_channel);
01170 
01171       /* Tell the technology handling bridge0 that the bridge channel is joining */
01172       if (bridge0->technology->join) {
01173          ast_debug(1, "Giving bridge technology %s notification that %p is joining bridge %p\n", bridge0->technology->name, bridge_channel, bridge0);
01174          if (bridge0->technology->join(bridge0, bridge_channel)) {
01175             ast_debug(1, "Bridge technology %s failed to join %p to bridge %p\n", bridge0->technology->name, bridge_channel, bridge0);
01176          }
01177       }
01178 
01179       /* Poke the bridge channel, this will cause it to wake up and execute the proper threading model for the new bridge it is in */
01180       pthread_kill(bridge_channel->thread, SIGURG);
01181       ast_mutex_lock(&bridge_channel->lock);
01182       ast_cond_signal(&bridge_channel->cond);
01183       ast_mutex_unlock(&bridge_channel->lock);
01184    }
01185 
01186    ast_debug(1, "Merged channels from bridge %p into bridge %p\n", bridge1, bridge0);
01187 
01188    ao2_unlock(bridge1);
01189    ao2_unlock(bridge0);
01190 
01191    return 0;
01192 }

struct ast_bridge* ast_bridge_new ( enum ast_bridge_capability  capabilities,
int  flags 
)

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:

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_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, destroy_bridge(), find_best_technology(), and ast_bridge_technology::thread.

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

00449 {
00450    struct ast_bridge *bridge = NULL;
00451    struct ast_bridge_technology *bridge_technology = NULL;
00452 
00453    /* If we need to be a smart bridge see if we can move between 1to1 and multimix bridges */
00454    if (flags & AST_BRIDGE_FLAG_SMART) {
00455       struct ast_bridge *other_bridge;
00456 
00457       if (!(other_bridge = ast_bridge_new((capabilities & AST_BRIDGE_CAPABILITY_1TO1MIX) ? AST_BRIDGE_CAPABILITY_MULTIMIX : AST_BRIDGE_CAPABILITY_1TO1MIX, 0))) {
00458          return NULL;
00459       }
00460 
00461       ast_bridge_destroy(other_bridge);
00462    }
00463 
00464    /* If capabilities were provided use our helper function to find the "best" bridge technology, otherwise we can
00465     * just look for the most basic capability needed, single 1to1 mixing. */
00466    bridge_technology = (capabilities ? find_best_technology(capabilities) : find_best_technology(AST_BRIDGE_CAPABILITY_1TO1MIX));
00467 
00468    /* If no bridge technology was found we can't possibly do bridging so fail creation of the bridge */
00469    if (!bridge_technology) {
00470       ast_debug(1, "Failed to find a bridge technology to satisfy capabilities %d\n", capabilities);
00471       return NULL;
00472    }
00473 
00474    /* We have everything we need to create this bridge... so allocate the memory, link things together, and fire her up! */
00475    if (!(bridge = ao2_alloc(sizeof(*bridge), destroy_bridge))) {
00476       return NULL;
00477    }
00478 
00479    bridge->technology = bridge_technology;
00480    bridge->thread = AST_PTHREADT_NULL;
00481 
00482    /* Create an array of pointers for the channels that will be joining us */
00483    bridge->array = ast_calloc(BRIDGE_ARRAY_START, sizeof(struct ast_channel*));
00484    bridge->array_size = BRIDGE_ARRAY_START;
00485 
00486    ast_set_flag(&bridge->feature_flags, flags);
00487 
00488    /* Pass off the bridge to the technology to manipulate if needed */
00489    if (bridge->technology->create) {
00490       ast_debug(1, "Giving bridge technology %s the bridge structure %p to setup\n", bridge->technology->name, bridge);
00491       if (bridge->technology->create(bridge)) {
00492          ast_debug(1, "Bridge technology %s failed to setup bridge structure %p\n", bridge->technology->name, bridge);
00493          ao2_ref(bridge, -1);
00494          bridge = NULL;
00495       }
00496    }
00497 
00498    return bridge;
00499 }

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

References ao2_lock, ao2_unlock, ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_HANGUP, ast_bridge_channel::bridge, ast_bridge_channel::chan, and find_bridge_channel().

Referenced by menu_callback().

01095 {
01096    struct ast_bridge_channel *bridge_channel = NULL;
01097 
01098    ao2_lock(bridge);
01099 
01100    /* Try to find the channel that we want to remove */
01101    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01102       ao2_unlock(bridge);
01103       return -1;
01104    }
01105 
01106    ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_HANGUP);
01107 
01108    ao2_unlock(bridge);
01109 
01110    return 0;
01111 }

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:

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

References ao2_lock, ao2_unlock, ast_bridge_channel::bridge, bridge_channel_suspend(), ast_bridge_channel::chan, and find_bridge_channel().

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

01195 {
01196    struct ast_bridge_channel *bridge_channel;
01197 
01198    ao2_lock(bridge);
01199 
01200    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01201       ao2_unlock(bridge);
01202       return -1;
01203    }
01204 
01205    bridge_channel_suspend(bridge, bridge_channel);
01206 
01207    ao2_unlock(bridge);
01208 
01209    return 0;
01210 }

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:

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

References ao2_lock, ao2_unlock, ast_bridge_channel::bridge, bridge_channel_unsuspend(), ast_bridge_channel::chan, and find_bridge_channel().

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

01213 {
01214    struct ast_bridge_channel *bridge_channel;
01215 
01216    ao2_lock(bridge);
01217 
01218    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01219       ao2_unlock(bridge);
01220       return -1;
01221    }
01222 
01223    bridge_channel_unsuspend(bridge, bridge_channel);
01224 
01225    ao2_unlock(bridge);
01226 
01227    return 0;
01228 }


Generated on Mon Mar 19 11:30:36 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7