Wed Jan 8 2020 09:49:58

Asterisk developer's documentation


bridging_technology.h File Reference

Channel Bridging API. More...

Go to the source code of this file.

Data Structures

struct  ast_bridge_technology
 Structure that is the essence of a bridge technology. More...
 

Macros

#define ast_bridge_technology_register(technology)   __ast_bridge_technology_register(technology, ast_module_info->self)
 See __ast_bridge_technology_register() More...
 

Enumerations

enum  ast_bridge_preference { AST_BRIDGE_PREFERENCE_HIGH = 0, AST_BRIDGE_PREFERENCE_MEDIUM, AST_BRIDGE_PREFERENCE_LOW }
 Preference for choosing the bridge technology. More...
 

Functions

int __ast_bridge_technology_register (struct ast_bridge_technology *technology, struct ast_module *mod)
 Register a bridge technology for use. More...
 
void ast_bridge_handle_trip (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd)
 Feed notification that a frame is waiting on a channel into the bridging core. More...
 
void ast_bridge_technology_suspend (struct ast_bridge_technology *technology)
 Suspend a bridge technology from consideration. More...
 
int ast_bridge_technology_unregister (struct ast_bridge_technology *technology)
 Unregister a bridge technology from use. More...
 
void ast_bridge_technology_unsuspend (struct ast_bridge_technology *technology)
 Unsuspend a bridge technology. More...
 

Detailed Description

Channel Bridging API.

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

Definition in file bridging_technology.h.

Macro Definition Documentation

#define ast_bridge_technology_register (   technology)    __ast_bridge_technology_register(technology, ast_module_info->self)

See __ast_bridge_technology_register()

Definition at line 104 of file bridging_technology.h.

Referenced by load_module().

Enumeration Type Documentation

Preference for choosing the bridge technology.

Enumerator
AST_BRIDGE_PREFERENCE_HIGH 

Bridge technology should have high precedence over other bridge technologies

AST_BRIDGE_PREFERENCE_MEDIUM 

Bridge technology is decent, not the best but should still be considered over low

AST_BRIDGE_PREFERENCE_LOW 

Bridge technology is low, it should not be considered unless it is absolutely needed

Definition at line 32 of file bridging_technology.h.

32  {
33  /*! Bridge technology should have high precedence over other bridge technologies */
35  /*! Bridge technology is decent, not the best but should still be considered over low */
37  /*! Bridge technology is low, it should not be considered unless it is absolutely needed */
39 };

Function Documentation

int __ast_bridge_technology_register ( struct ast_bridge_technology technology,
struct ast_module mod 
)

Register a bridge technology for use.

Parameters
technologyThe bridge technology to register
modThe module that is registering the bridge technology
Return values
0on success
-1on failure

Example usage:

* ast_bridge_technology_register(&simple_bridge_tech);
*

This registers a bridge technology declared as the structure simple_bridge_tech with the bridging core and makes it available for use when creating bridges.

Definition at line 63 of file bridging.c.

References ast_log(), AST_RWLIST_INSERT_TAIL, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero(), ast_verbose(), ast_bridge_technology::capabilities, LOG_WARNING, ast_bridge_technology::mod, ast_bridge_technology::name, option_verbose, VERBOSE_PREFIX_2, and ast_bridge_technology::write.

64 {
65  struct ast_bridge_technology *current = NULL;
66 
67  /* Perform a sanity check to make sure the bridge technology conforms to our needed requirements */
68  if (ast_strlen_zero(technology->name) || !technology->capabilities || !technology->write) {
69  ast_log(LOG_WARNING, "Bridge technology %s failed registration sanity check.\n", technology->name);
70  return -1;
71  }
72 
74 
75  /* Look for duplicate bridge technology already using this name, or already registered */
76  AST_RWLIST_TRAVERSE(&bridge_technologies, current, entry) {
77  if ((!strcasecmp(current->name, technology->name)) || (current == technology)) {
78  ast_log(LOG_WARNING, "A bridge technology of %s already claims to exist in our world.\n", technology->name);
80  return -1;
81  }
82  }
83 
84  /* Copy module pointer so reference counting can keep the module from unloading */
85  technology->mod = module;
86 
87  /* Insert our new bridge technology into the list and print out a pretty message */
88  AST_RWLIST_INSERT_TAIL(&bridge_technologies, technology, entry);
89 
91 
92  if (option_verbose > 1) {
93  ast_verbose(VERBOSE_PREFIX_2 "Registered bridge technology %s\n", technology->name);
94  }
95 
96  return 0;
97 }
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
#define LOG_WARNING
Definition: logger.h:144
void ast_verbose(const char *fmt,...)
Definition: logger.c:1568
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
int option_verbose
Definition: asterisk.c:181
#define VERBOSE_PREFIX_2
Definition: logger.h:42
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
#define AST_RWLIST_TRAVERSE
Definition: linkedlists.h:493
struct ast_module * mod
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
enum ast_bridge_write_result(* write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame)
#define AST_RWLIST_INSERT_TAIL
Definition: linkedlists.h:726
Structure that is the essence of a bridge technology.
void ast_bridge_handle_trip ( struct ast_bridge bridge,
struct ast_bridge_channel bridge_channel,
struct ast_channel chan,
int  outfd 
)

Feed notification that a frame is waiting on a channel into the bridging core.

Parameters
bridgeThe bridge that the notification should influence
bridge_channelBridge channel the notification was received on (if known)
chanChannel the notification was received on (if known)
outfdFile descriptor that the notification was received on (if known)

Example usage:

* ast_bridge_handle_trip(bridge, NULL, chan, -1);
*

This tells the bridging core that a frame has been received on the channel pointed to by chan and that it should be read and handled.

Note
This should only be used by bridging technologies.

Definition at line 277 of file bridging.c.

References ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_END, AST_CONTROL_HANGUP, ast_debug, AST_FRAME_CONTROL, AST_FRAME_DTMF_BEGIN, ast_frfree, ast_read(), ast_read_noaudio(), bridge_drop_control_frame(), bridge_handle_dtmf(), ast_bridge_technology::fd, ast_bridge_channel::features, ast_bridge::features, find_bridge_channel(), ast_frame::frametype, ast_frame_subclass::integer, ast_bridge_features::mute, ast_bridge_technology::poke, ast_frame::subclass, ast_bridge::technology, and ast_bridge_technology::write.

Referenced by bridge_channel_join_multithreaded(), generic_thread_loop(), and multiplexed_thread_function().

278 {
279  /* If no bridge channel has been provided and the actual channel has been provided find it */
280  if (chan && !bridge_channel) {
281  bridge_channel = find_bridge_channel(bridge, chan);
282  }
283 
284  /* If a bridge channel with actual channel is present read a frame and handle it */
285  if (chan && bridge_channel) {
286  struct ast_frame *frame = (((bridge->features.mute) || (bridge_channel->features && bridge_channel->features->mute)) ? ast_read_noaudio(chan) : ast_read(chan));
287 
288  /* This is pretty simple... see if they hung up */
289  if (!frame || (frame->frametype == AST_FRAME_CONTROL && frame->subclass.integer == AST_CONTROL_HANGUP)) {
290  /* Signal the thread that is handling the bridged channel that it should be ended */
292  } else if (frame->frametype == AST_FRAME_CONTROL && bridge_drop_control_frame(frame->subclass.integer)) {
293  ast_debug(1, "Dropping control frame from bridge channel %p\n", bridge_channel);
294  } else {
295  if (frame->frametype == AST_FRAME_DTMF_BEGIN) {
296  frame = bridge_handle_dtmf(bridge, bridge_channel, frame);
297  }
298  /* Simply write the frame out to the bridge technology if it still exists */
299  if (frame) {
300  bridge->technology->write(bridge, bridge_channel, frame);
301  }
302  }
303 
304  if (frame) {
305  ast_frfree(frame);
306  }
307  return;
308  }
309 
310  /* If a file descriptor actually tripped pass it off to the bridge technology */
311  if (outfd > -1 && bridge->technology->fd) {
312  bridge->technology->fd(bridge, bridge_channel, outfd);
313  return;
314  }
315 
316  /* If all else fails just poke the bridge */
317  if (bridge->technology->poke && bridge_channel) {
318  bridge->technology->poke(bridge, bridge_channel);
319  return;
320  }
321 
322  return;
323 }
union ast_frame_subclass subclass
Definition: frame.h:146
struct ast_bridge_features * features
Definition: bridging.h:139
struct ast_frame * ast_read(struct ast_channel *chan)
Reads a frame.
Definition: channel.c:4383
static int bridge_drop_control_frame(int subclass)
Internal function used to determine whether a control frame should be dropped or not.
Definition: bridging.c:266
int(* poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
struct ast_bridge_features features
Definition: bridging.h:167
struct ast_bridge_technology * technology
Definition: bridging.h:161
#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
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
enum ast_bridge_write_result(* write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame)
static struct ast_frame * bridge_handle_dtmf(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame)
Internal function to handle DTMF from a channel.
Definition: bridging.c:242
int(* fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd)
Data structure associated with a single frame of data.
Definition: frame.h:142
enum ast_frame_type frametype
Definition: frame.h:144
#define ast_frfree(fr)
Definition: frame.h:583
struct ast_frame * ast_read_noaudio(struct ast_channel *chan)
Reads a frame, returning AST_FRAME_NULL frame if audio.
Definition: channel.c:4388
void ast_bridge_technology_suspend ( struct ast_bridge_technology technology)

Suspend a bridge technology from consideration.

Parameters
technologyThe bridge technology to suspend

Example usage:

* ast_bridge_technology_suspend(&simple_bridge_tech);
*

This suspends the bridge technology simple_bridge_tech from being considered when creating a new bridge. Existing bridges using the bridge technology are not affected.

Definition at line 1236 of file bridging.c.

References ast_bridge_technology::suspended.

1237 {
1238  technology->suspended = 1;
1239  return;
1240 }
int ast_bridge_technology_unregister ( struct ast_bridge_technology technology)

Unregister a bridge technology from use.

Parameters
technologyThe bridge technology to unregister
Return values
0on success
-1on failure

Example usage:

* ast_bridge_technology_unregister(&simple_bridge_tech);
*

This unregisters a bridge technlogy declared as the structure simple_bridge_tech with the bridging core. It will no longer be considered when creating a new bridge.

Definition at line 99 of file bridging.c.

References AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verbose(), ast_bridge_technology::name, option_verbose, and VERBOSE_PREFIX_2.

Referenced by unload_module().

100 {
101  struct ast_bridge_technology *current = NULL;
102 
104 
105  /* Ensure the bridge technology is registered before removing it */
107  if (current == technology) {
109  if (option_verbose > 1) {
110  ast_verbose(VERBOSE_PREFIX_2 "Unregistered bridge technology %s\n", technology->name);
111  }
112  break;
113  }
114  }
116 
118 
119  return current ? 0 : -1;
120 }
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
void ast_verbose(const char *fmt,...)
Definition: logger.c:1568
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
int option_verbose
Definition: asterisk.c:181
#define VERBOSE_PREFIX_2
Definition: logger.h:42
#define AST_RWLIST_REMOVE_CURRENT
Definition: linkedlists.h:565
#define AST_RWLIST_TRAVERSE_SAFE_BEGIN
Definition: linkedlists.h:542
Structure that is the essence of a bridge technology.
#define AST_RWLIST_TRAVERSE_SAFE_END
Definition: linkedlists.h:602
void ast_bridge_technology_unsuspend ( struct ast_bridge_technology technology)

Unsuspend a bridge technology.

Parameters
technologyThe bridge technology to unsuspend

Example usage:

* ast_bridge_technology_unsuspend(&simple_bridge_tech);
*

This makes the bridge technology simple_bridge_tech considered when creating a new bridge again.

Definition at line 1242 of file bridging.c.

References ast_bridge_technology::suspended.

1243 {
1244  technology->suspended = 0;
1245  return;
1246 }