Wed Jan 8 2020 09:49:58

Asterisk developer's documentation


bridging.h File Reference

Channel Bridging API. More...

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. More...
 
int ast_bridge_check (enum ast_bridge_capability capabilities)
 See if it is possible to create a bridge. More...
 
int ast_bridge_depart (struct ast_bridge *bridge, struct ast_channel *chan)
 Depart a channel from a bridge. More...
 
int ast_bridge_destroy (struct ast_bridge *bridge)
 Destroy a bridge. More...
 
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. More...
 
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. More...
 
int ast_bridge_merge (struct ast_bridge *bridge0, struct ast_bridge *bridge1)
 Merge two bridges together. More...
 
struct ast_bridgeast_bridge_new (enum ast_bridge_capability capabilities, int flags)
 Create a new bridge. More...
 
int ast_bridge_remove (struct ast_bridge *bridge, struct ast_channel *chan)
 Remove a channel from a bridge. More...
 
int ast_bridge_suspend (struct ast_bridge *bridge, struct ast_channel *chan)
 Suspend a channel temporarily from a bridge. More...
 
int ast_bridge_unsuspend (struct ast_bridge *bridge, struct ast_channel *chan)
 Unsuspend a channel from a bridge. More...
 

Detailed Description

Channel Bridging API.

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

Definition in file bridging.h.

Enumeration Type Documentation

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.

68  {
69  /*! Bridge is only capable of mixing 2 channels */
71  /*! Bridge is capable of mixing 2 or more channels */
73  /*! Bridge should natively bridge two channels if possible */
75  /*! Bridge should run using the multithreaded model */
77  /*! Bridge should run a central bridge thread */
79  /*! Bridge technology can do video mixing (or something along those lines) */
80  AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6),
81  /*! Bridge technology can optimize things based on who is talking */
83 };

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.

86  {
87  /*! Waiting for a signal */
89  /*! Bridged channel has ended itself (it has hung up) */
91  /*! Bridged channel should be hung up */
93  /*! Bridged channel should be removed from the bridge without being hung up */
95  /*! Bridged channel is executing a feature hook */
97  /*! Bridged channel is sending a DTMF stream out */
99 };

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.

102  {
103  /*! Bridge technology wrote out frame fine */
105  /*! Bridge technology attempted to write out the frame but failed */
107  /*! Bridge technology does not support writing out a frame of this type */
109 };

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_channelChannel to change the state on
new_stateThe 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 122 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().

123 {
124  /* Change the state on the bridge channel */
125  bridge_channel->state = new_state;
126 
127  /* Only poke the channel's thread if it is not us */
128  if (!pthread_equal(pthread_self(), bridge_channel->thread)) {
129  pthread_kill(bridge_channel->thread, SIGURG);
130  ast_mutex_lock(&bridge_channel->lock);
131  ast_cond_signal(&bridge_channel->cond);
132  ast_mutex_unlock(&bridge_channel->lock);
133  }
134 
135  return;
136 }
pthread_t thread
Definition: bridging.h:133
#define ast_mutex_lock(a)
Definition: lock.h:155
#define ast_cond_signal(cond)
Definition: lock.h:169
ast_cond_t cond
Definition: bridging.h:121
ast_mutex_t lock
Definition: bridging.h:119
enum ast_bridge_channel_state state
Definition: bridging.h:123
#define ast_mutex_unlock(a)
Definition: lock.h:156
int ast_bridge_check ( enum ast_bridge_capability  capabilities)

See if it is possible to create a bridge.

Parameters
capabilitiesThe capabilities that the bridge will use
Return values
1if possible
0if not possible

Example usage:

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

Definition at line 502 of file bridging.c.

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

503 {
504  struct ast_bridge_technology *bridge_technology = NULL;
505 
506  if (!(bridge_technology = find_best_technology(capabilities))) {
507  return 0;
508  }
509 
510  ast_module_unref(bridge_technology->mod);
511 
512  return 1;
513 }
void ast_module_unref(struct ast_module *)
Definition: loader.c:1312
static struct aji_capabilities * capabilities
Definition: res_jabber.c:393
static struct ast_bridge_technology * find_best_technology(enum ast_bridge_capability capabilities)
Helper function used to find the &quot;best&quot; bridge technology given a specified capabilities.
Definition: bridging.c:386
struct ast_module * mod
Structure that is the essence of a bridge technology.
int ast_bridge_depart ( struct ast_bridge bridge,
struct ast_channel chan 
)

Depart a channel from a bridge.

Parameters
bridgeBridge to depart from
chanChannel to depart
Return values
0on success
-1on 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 1077 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().

1078 {
1079  struct ast_bridge_channel *bridge_channel = NULL;
1080  pthread_t thread;
1081 
1082  ao2_lock(bridge);
1083 
1084  /* Try to find the channel that we want to depart */
1085  if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
1086  ao2_unlock(bridge);
1087  return -1;
1088  }
1089 
1091  thread = bridge_channel->thread;
1092 
1093  ao2_unlock(bridge);
1094 
1095  pthread_join(thread, NULL);
1096 
1097  return 0;
1098 }
pthread_t thread
Definition: app_meetme.c:962
pthread_t thread
Definition: bridging.h:133
#define ao2_unlock(a)
Definition: astobj2.h:497
void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state)
Change the state of a bridged channel.
Definition: bridging.c:122
#define ao2_lock(a)
Definition: astobj2.h:488
static struct ast_bridge_channel * find_bridge_channel(struct ast_bridge *bridge, struct ast_channel *chan)
Helper function to find a bridge channel given a channel.
Definition: bridging.c:208
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
int ast_bridge_destroy ( struct ast_bridge bridge)

Destroy a bridge.

Parameters
bridgeBridge to destroy
Return values
0on success
-1on failure

Example usage:

*

This destroys a bridge that was previously created using ast_bridge_new.

Definition at line 515 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_PTHREADT_NULL, bridge_poke(), ast_bridge::stop, ast_bridge::thread, and thread.

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

516 {
517  struct ast_bridge_channel *bridge_channel = NULL;
518 
519  ao2_lock(bridge);
520 
521  if (bridge->thread != AST_PTHREADT_NULL) {
522  pthread_t thread = bridge->thread;
523  bridge->stop = 1;
524  bridge_poke(bridge);
525  ao2_unlock(bridge);
526  pthread_join(thread, NULL);
527  ao2_lock(bridge);
528  }
529 
530  ast_debug(1, "Telling all channels in bridge %p to end and leave the party\n", bridge);
531 
532  /* Drop every bridged channel, the last one will cause the bridge thread (if it exists) to exit */
533  AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
535  }
536 
537  ao2_unlock(bridge);
538 
539  ao2_ref(bridge, -1);
540 
541  return 0;
542 }
pthread_t thread
Definition: app_meetme.c:962
#define ao2_unlock(a)
Definition: astobj2.h:497
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state)
Change the state of a bridged channel.
Definition: bridging.c:122
#define AST_PTHREADT_NULL
Definition: lock.h:65
static void bridge_poke(struct ast_bridge *bridge)
Helper function to poke the bridge thread.
Definition: bridging.c:139
#define ao2_ref(o, delta)
Definition: astobj2.h:472
#define ao2_lock(a)
Definition: astobj2.h:488
unsigned int stop
Definition: bridging.h:155
pthread_t thread
Definition: bridging.h:165
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
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
bridgeBridge to impart on
chanChannel to impart
swapChannel to swap out if swapping
featuresBridge features structure
Return values
0on success
-1on 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 1043 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().

1044 {
1045  struct ast_bridge_channel *bridge_channel = NULL;
1046 
1047  /* Try to allocate a structure for the bridge channel */
1048  if (!(bridge_channel = ast_calloc(1, sizeof(*bridge_channel)))) {
1049  return -1;
1050  }
1051 
1052  /* Setup various parameters */
1053  bridge_channel->chan = chan;
1054  bridge_channel->swap = swap;
1055  bridge_channel->bridge = bridge;
1056  bridge_channel->features = features;
1057 
1058  /* Initialize our mutex lock and condition */
1059  ast_mutex_init(&bridge_channel->lock);
1060  ast_cond_init(&bridge_channel->cond, NULL);
1061 
1062  /* Bump up the reference count on the bridge, it'll get decremented later */
1063  ao2_ref(bridge, +1);
1064 
1065  /* Actually create the thread that will handle the channel */
1066  if (ast_pthread_create(&bridge_channel->thread, NULL, bridge_channel_thread, bridge_channel)) {
1067  ao2_ref(bridge, -1);
1068  ast_cond_destroy(&bridge_channel->cond);
1069  ast_mutex_destroy(&bridge_channel->lock);
1070  ast_free(bridge_channel);
1071  return -1;
1072  }
1073 
1074  return 0;
1075 }
struct ast_bridge_features * features
Definition: bridging.h:139
pthread_t thread
Definition: bridging.h:133
static void * bridge_channel_thread(void *data)
Thread responsible for imparted bridged channels.
Definition: bridging.c:1021
#define ast_cond_init(cond, attr)
Definition: lock.h:167
struct ast_bridge * bridge
Definition: bridging.h:129
#define ao2_ref(o, delta)
Definition: astobj2.h:472
ast_cond_t cond
Definition: bridging.h:121
#define ast_cond_destroy(cond)
Definition: lock.h:168
#define ast_free(a)
Definition: astmm.h:97
#define ast_pthread_create(a, b, c, d)
Definition: utils.h:418
struct ast_channel * swap
Definition: bridging.h:127
struct ast_channel * chan
Definition: bridging.h:125
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
#define ast_calloc(a, b)
Definition: astmm.h:82
ast_mutex_t lock
Definition: bridging.h:119
#define ast_mutex_init(pmutex)
Definition: lock.h:152
#define ast_mutex_destroy(a)
Definition: lock.h:154
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
bridgeBridge to join
chanChannel to join
swapChannel to swap out if swapping
featuresBridge features structure
Return values
statethat 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 993 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_channel::features, ast_bridge::features, ast_bridge_channel::lock, state, and ast_bridge_channel::swap.

Referenced by confbridge_exec(), and feature_attended_transfer().

994 {
995  struct ast_bridge_channel bridge_channel = {
996  .chan = chan,
997  .swap = swap,
998  .bridge = bridge,
999  .features = features,
1000  };
1002 
1003  /* Initialize various other elements of the bridge channel structure that we can't do above */
1004  ast_mutex_init(&bridge_channel.lock);
1005  ast_cond_init(&bridge_channel.cond, NULL);
1006 
1007  ao2_ref(bridge_channel.bridge, +1);
1008 
1009  state = bridge_channel_join(&bridge_channel);
1010 
1011  ao2_ref(bridge_channel.bridge, -1);
1012 
1013  /* Destroy some elements of the bridge channel structure above */
1014  ast_mutex_destroy(&bridge_channel.lock);
1015  ast_cond_destroy(&bridge_channel.cond);
1016 
1017  return state;
1018 }
enum sip_cc_notify_state state
Definition: chan_sip.c:842
struct ast_bridge_features * features
Definition: bridging.h:139
#define ast_cond_init(cond, attr)
Definition: lock.h:167
struct ast_bridge * bridge
Definition: bridging.h:129
struct ast_bridge_features features
Definition: bridging.h:167
#define ao2_ref(o, delta)
Definition: astobj2.h:472
ast_cond_t cond
Definition: bridging.h:121
#define ast_cond_destroy(cond)
Definition: lock.h:168
struct ast_bridge * bridge
Definition: channel.h:865
static enum ast_bridge_channel_state bridge_channel_join(struct ast_bridge_channel *bridge_channel)
Join a channel to a bridge and handle anything the bridge may want us to do.
Definition: bridging.c:873
struct ast_channel * swap
Definition: bridging.h:127
struct ast_channel * chan
Definition: bridging.h:125
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
ast_bridge_channel_state
State information about a bridged channel.
Definition: bridging.h:86
ast_mutex_t lock
Definition: bridging.h:119
#define ast_mutex_init(pmutex)
Definition: lock.h:152
#define ast_mutex_destroy(a)
Definition: lock.h:154
int ast_bridge_merge ( struct ast_bridge bridge0,
struct ast_bridge bridge1 
)

Merge two bridges together.

Parameters
bridge0First bridge
bridge1Second bridge
Return values
0on success
-1on 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 1119 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_channel::thread, and ast_bridge::thread.

1120 {
1121  struct ast_bridge_channel *bridge_channel = NULL;
1122 
1123  ao2_lock(bridge0);
1124  ao2_lock(bridge1);
1125 
1126  /* If the first bridge currently has 2 channels and is not capable of becoming a multimixing bridge we can not merge */
1127  if ((bridge0->num + bridge1->num) > 2 && (!(bridge0->technology->capabilities & AST_BRIDGE_CAPABILITY_MULTIMIX) && !ast_test_flag(&bridge0->feature_flags, AST_BRIDGE_FLAG_SMART))) {
1128  ao2_unlock(bridge1);
1129  ao2_unlock(bridge0);
1130  ast_debug(1, "Can't merge bridge %p into bridge %p, multimix is needed and it could not be acquired.\n", bridge1, bridge0);
1131  return -1;
1132  }
1133 
1134  ast_debug(1, "Merging channels from bridge %p into bridge %p\n", bridge1, bridge0);
1135 
1136  /* Perform smart bridge operation on bridge we are merging into so it can change bridge technology if needed */
1137  if (smart_bridge_operation(bridge0, NULL, bridge0->num + bridge1->num)) {
1138  ao2_unlock(bridge1);
1139  ao2_unlock(bridge0);
1140  ast_debug(1, "Can't merge bridge %p into bridge %p, tried to perform smart bridge operation and failed.\n", bridge1, bridge0);
1141  return -1;
1142  }
1143 
1144  /* If a thread is currently executing on bridge1 tell it to stop */
1145  if (bridge1->thread) {
1146  ast_debug(1, "Telling bridge thread on bridge %p to stop as it is being merged into %p\n", bridge1, bridge0);
1147  bridge1->thread = AST_PTHREADT_STOP;
1148  }
1149 
1150  /* Move channels from bridge1 over to bridge0 */
1151  while ((bridge_channel = AST_LIST_REMOVE_HEAD(&bridge1->channels, entry))) {
1152  /* Tell the technology handling bridge1 that the bridge channel is leaving */
1153  if (bridge1->technology->leave) {
1154  ast_debug(1, "Giving bridge technology %s notification that %p is leaving bridge %p\n", bridge1->technology->name, bridge_channel, bridge1);
1155  if (bridge1->technology->leave(bridge1, bridge_channel)) {
1156  ast_debug(1, "Bridge technology %s failed to allow %p to leave bridge %p\n", bridge1->technology->name, bridge_channel, bridge1);
1157  }
1158  }
1159 
1160  /* Drop channel count and reference count on the bridge they are leaving */
1161  bridge1->num--;
1162  ao2_ref(bridge1, -1);
1163 
1164  bridge_array_remove(bridge1, bridge_channel->chan);
1165 
1166  /* Now add them into the bridge they are joining, increase channel count, and bump up reference count */
1167  bridge_channel->bridge = bridge0;
1168  AST_LIST_INSERT_TAIL(&bridge0->channels, bridge_channel, entry);
1169  bridge0->num++;
1170  ao2_ref(bridge0, +1);
1171 
1172  bridge_array_add(bridge0, bridge_channel->chan);
1173 
1174  /* Make the channel compatible with the new bridge it is joining or else formats would go amuck */
1175  bridge_make_compatible(bridge0, bridge_channel);
1176 
1177  /* Tell the technology handling bridge0 that the bridge channel is joining */
1178  if (bridge0->technology->join) {
1179  ast_debug(1, "Giving bridge technology %s notification that %p is joining bridge %p\n", bridge0->technology->name, bridge_channel, bridge0);
1180  if (bridge0->technology->join(bridge0, bridge_channel)) {
1181  ast_debug(1, "Bridge technology %s failed to join %p to bridge %p\n", bridge0->technology->name, bridge_channel, bridge0);
1182  }
1183  }
1184 
1185  /* Poke the bridge channel, this will cause it to wake up and execute the proper threading model for the new bridge it is in */
1186  pthread_kill(bridge_channel->thread, SIGURG);
1187  ast_mutex_lock(&bridge_channel->lock);
1188  ast_cond_signal(&bridge_channel->cond);
1189  ast_mutex_unlock(&bridge_channel->lock);
1190  }
1191 
1192  ast_debug(1, "Merged channels from bridge %p into bridge %p\n", bridge1, bridge0);
1193 
1194  ao2_unlock(bridge1);
1195  ao2_unlock(bridge0);
1196 
1197  return 0;
1198 }
struct ast_flags feature_flags
Definition: bridging.h:159
static int bridge_make_compatible(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Definition: bridging.c:544
pthread_t thread
Definition: bridging.h:133
#define ast_test_flag(p, flag)
Definition: utils.h:63
#define ast_mutex_lock(a)
Definition: lock.h:155
#define ao2_unlock(a)
Definition: astobj2.h:497
static int smart_bridge_operation(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int count)
Perform the smart bridge operation. Basically sees if a new bridge technology should be used instead ...
Definition: bridging.c:593
#define ast_cond_signal(cond)
Definition: lock.h:169
struct ast_bridge * bridge
Definition: bridging.h:129
static void bridge_array_add(struct ast_bridge *bridge, struct ast_channel *chan)
Helper function to add a channel to the bridge array.
Definition: bridging.c:153
struct ast_bridge_technology * technology
Definition: bridging.h:161
int(* join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
#define ao2_ref(o, delta)
Definition: astobj2.h:472
#define ao2_lock(a)
Definition: astobj2.h:488
#define AST_LIST_REMOVE_HEAD(head, field)
Removes and returns the head entry from a list.
Definition: linkedlists.h:818
ast_cond_t cond
Definition: bridging.h:121
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
pthread_t thread
Definition: bridging.h:165
struct ast_channel * chan
Definition: bridging.h:125
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
static void bridge_array_remove(struct ast_bridge *bridge, struct ast_channel *chan)
Helper function to remove a channel from the bridge array.
Definition: bridging.c:184
#define AST_PTHREADT_STOP
Definition: lock.h:66
ast_mutex_t lock
Definition: bridging.h:119
int(* leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
#define ast_mutex_unlock(a)
Definition: lock.h:156
struct ast_bridge* ast_bridge_new ( enum ast_bridge_capability  capabilities,
int  flags 
)

Create a new bridge.

Parameters
capabilitiesThe capabilities that we require to be used on the bridge
flagsFlags that will alter the behavior of the bridge
Return values
apointer to a new bridge on success
NULLon failure

Example usage:

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

Definition at line 449 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().

450 {
451  struct ast_bridge *bridge = NULL;
452  struct ast_bridge_technology *bridge_technology = NULL;
453 
454  /* If we need to be a smart bridge see if we can move between 1to1 and multimix bridges */
455  if (flags & AST_BRIDGE_FLAG_SMART) {
456  struct ast_bridge *other_bridge;
457 
458  if (!(other_bridge = ast_bridge_new((capabilities & AST_BRIDGE_CAPABILITY_1TO1MIX) ? AST_BRIDGE_CAPABILITY_MULTIMIX : AST_BRIDGE_CAPABILITY_1TO1MIX, 0))) {
459  return NULL;
460  }
461 
462  ast_bridge_destroy(other_bridge);
463  }
464 
465  /* If capabilities were provided use our helper function to find the "best" bridge technology, otherwise we can
466  * just look for the most basic capability needed, single 1to1 mixing. */
467  bridge_technology = (capabilities ? find_best_technology(capabilities) : find_best_technology(AST_BRIDGE_CAPABILITY_1TO1MIX));
468 
469  /* If no bridge technology was found we can't possibly do bridging so fail creation of the bridge */
470  if (!bridge_technology) {
471  ast_debug(1, "Failed to find a bridge technology to satisfy capabilities %u\n", capabilities);
472  return NULL;
473  }
474 
475  /* We have everything we need to create this bridge... so allocate the memory, link things together, and fire her up! */
476  if (!(bridge = ao2_alloc(sizeof(*bridge), destroy_bridge))) {
477  return NULL;
478  }
479 
480  bridge->technology = bridge_technology;
481  bridge->thread = AST_PTHREADT_NULL;
482 
483  /* Create an array of pointers for the channels that will be joining us */
484  bridge->array = ast_calloc(BRIDGE_ARRAY_START, sizeof(struct ast_channel*));
485  bridge->array_size = BRIDGE_ARRAY_START;
486 
487  ast_set_flag(&bridge->feature_flags, flags);
488 
489  /* Pass off the bridge to the technology to manipulate if needed */
490  if (bridge->technology->create) {
491  ast_debug(1, "Giving bridge technology %s the bridge structure %p to setup\n", bridge->technology->name, bridge);
492  if (bridge->technology->create(bridge)) {
493  ast_debug(1, "Bridge technology %s failed to setup bridge structure %p\n", bridge->technology->name, bridge);
494  ao2_ref(bridge, -1);
495  bridge = NULL;
496  }
497  }
498 
499  return bridge;
500 }
static void destroy_bridge(void *obj)
Definition: bridging.c:421
Main Channel structure associated with a channel.
Definition: channel.h:742
struct ast_flags feature_flags
Definition: bridging.h:159
#define ast_set_flag(p, flag)
Definition: utils.h:70
static struct aji_capabilities * capabilities
Definition: res_jabber.c:393
struct ast_bridge * ast_bridge_new(enum ast_bridge_capability capabilities, int flags)
Create a new bridge.
Definition: bridging.c:449
int ast_bridge_destroy(struct ast_bridge *bridge)
Destroy a bridge.
Definition: bridging.c:515
struct ast_bridge_technology * technology
Definition: bridging.h:161
size_t array_size
Definition: bridging.h:173
int(* create)(struct ast_bridge *bridge)
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
#define AST_PTHREADT_NULL
Definition: lock.h:65
#define BRIDGE_ARRAY_START
Definition: bridging.c:52
#define ao2_ref(o, delta)
Definition: astobj2.h:472
static struct ast_bridge_technology * find_best_technology(enum ast_bridge_capability capabilities)
Helper function used to find the &quot;best&quot; bridge technology given a specified capabilities.
Definition: bridging.c:386
Structure that contains information about a bridge.
Definition: bridging.h:149
struct ast_channel ** array
Definition: bridging.h:169
pthread_t thread
Definition: bridging.h:165
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:430
#define ast_calloc(a, b)
Definition: astmm.h:82
Structure that is the essence of a bridge technology.
int ast_bridge_remove ( struct ast_bridge bridge,
struct ast_channel chan 
)

Remove a channel from a bridge.

Parameters
bridgeBridge that the channel is to be removed from
chanChannel to remove
Return values
0on success
-1on 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 1100 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().

1101 {
1102  struct ast_bridge_channel *bridge_channel = NULL;
1103 
1104  ao2_lock(bridge);
1105 
1106  /* Try to find the channel that we want to remove */
1107  if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
1108  ao2_unlock(bridge);
1109  return -1;
1110  }
1111 
1113 
1114  ao2_unlock(bridge);
1115 
1116  return 0;
1117 }
#define ao2_unlock(a)
Definition: astobj2.h:497
void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state)
Change the state of a bridged channel.
Definition: bridging.c:122
#define ao2_lock(a)
Definition: astobj2.h:488
static struct ast_bridge_channel * find_bridge_channel(struct ast_bridge *bridge, struct ast_channel *chan)
Helper function to find a bridge channel given a channel.
Definition: bridging.c:208
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
int ast_bridge_suspend ( struct ast_bridge bridge,
struct ast_channel chan 
)

Suspend a channel temporarily from a bridge.

Parameters
bridgeBridge to suspend the channel from
chanChannel to suspend
Return values
0on success
-1on 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 1200 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().

1201 {
1202  struct ast_bridge_channel *bridge_channel;
1203 
1204  ao2_lock(bridge);
1205 
1206  if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
1207  ao2_unlock(bridge);
1208  return -1;
1209  }
1210 
1211  bridge_channel_suspend(bridge, bridge_channel);
1212 
1213  ao2_unlock(bridge);
1214 
1215  return 0;
1216 }
#define ao2_unlock(a)
Definition: astobj2.h:497
#define ao2_lock(a)
Definition: astobj2.h:488
static struct ast_bridge_channel * find_bridge_channel(struct ast_bridge *bridge, struct ast_channel *chan)
Helper function to find a bridge channel given a channel.
Definition: bridging.c:208
static void bridge_channel_suspend(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Internal function that suspends a channel from a bridge.
Definition: bridging.c:763
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
int ast_bridge_unsuspend ( struct ast_bridge bridge,
struct ast_channel chan 
)

Unsuspend a channel from a bridge.

Parameters
bridgeBridge to unsuspend the channel from
chanChannel to unsuspend
Return values
0on success
-1on 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 1218 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().

1219 {
1220  struct ast_bridge_channel *bridge_channel;
1221 
1222  ao2_lock(bridge);
1223 
1224  if (!(bridge_channel = find_bridge_channel(bridge, chan))) {
1225  ao2_unlock(bridge);
1226  return -1;
1227  }
1228 
1229  bridge_channel_unsuspend(bridge, bridge_channel);
1230 
1231  ao2_unlock(bridge);
1232 
1233  return 0;
1234 }
static void bridge_channel_unsuspend(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Internal function that unsuspends a channel from a bridge.
Definition: bridging.c:777
#define ao2_unlock(a)
Definition: astobj2.h:497
#define ao2_lock(a)
Definition: astobj2.h:488
static struct ast_bridge_channel * find_bridge_channel(struct ast_bridge *bridge, struct ast_channel *chan)
Helper function to find a bridge channel given a channel.
Definition: bridging.c:208
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117