Wed Apr 6 11:29:53 2011

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 (format_t 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 (format_t 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 ( format_t  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 506 of file bridging.c.

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

00507 {
00508    struct ast_bridge_technology *bridge_technology = NULL;
00509 
00510    if (!(bridge_technology = find_best_technology(capabilities))) {
00511       return 0;
00512    }
00513 
00514    ast_module_unref(bridge_technology->mod);
00515 
00516    return 1;
00517 }

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

01079 {
01080    struct ast_bridge_channel *bridge_channel = NULL;
01081    pthread_t thread;
01082 
01083    ao2_lock(bridge);
01084 
01085    /* Try to find the channel that we want to depart */
01086    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01087       ao2_unlock(bridge);
01088       return -1;
01089    }
01090 
01091    ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_DEPART);
01092    thread = bridge_channel->thread;
01093 
01094    ao2_unlock(bridge);
01095 
01096    pthread_join(thread, NULL);
01097 
01098    return 0;
01099 }

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

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

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

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

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

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

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

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

struct ast_bridge* ast_bridge_new ( format_t  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 451 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_getformatname_multiple(), 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().

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

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

01102 {
01103    struct ast_bridge_channel *bridge_channel = NULL;
01104 
01105    ao2_lock(bridge);
01106 
01107    /* Try to find the channel that we want to remove */
01108    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01109       ao2_unlock(bridge);
01110       return -1;
01111    }
01112 
01113    ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_HANGUP);
01114 
01115    ao2_unlock(bridge);
01116 
01117    return 0;
01118 }

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

01202 {
01203    struct ast_bridge_channel *bridge_channel;
01204 
01205    ao2_lock(bridge);
01206 
01207    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01208       ao2_unlock(bridge);
01209       return -1;
01210    }
01211 
01212    bridge_channel_suspend(bridge, bridge_channel);
01213 
01214    ao2_unlock(bridge);
01215 
01216    return 0;
01217 }

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

01220 {
01221    struct ast_bridge_channel *bridge_channel;
01222 
01223    ao2_lock(bridge);
01224 
01225    if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
01226       ao2_unlock(bridge);
01227       return -1;
01228    }
01229 
01230    bridge_channel_unsuspend(bridge, bridge_channel);
01231 
01232    ao2_unlock(bridge);
01233 
01234    return 0;
01235 }


Generated on Wed Apr 6 11:29:53 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7