bridging_technology.h File Reference

Channel Bridging API. More...

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

Go to the source code of this file.

Data Structures

struct ast_bridge_technology

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

Defines

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

See __ast_bridge_technology_register().

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.

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.

void ast_bridge_notify_talking (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int started_talking)

Lets the bridging indicate when a bridge channel has stopped or started talking.

void ast_bridge_technology_suspend (struct ast_bridge_technology *technology)

Suspend a bridge technology from consideration.

int ast_bridge_technology_unregister (struct ast_bridge_technology *technology)

Unregister a bridge technology from use.

void ast_bridge_technology_unsuspend (struct ast_bridge_technology *technology)

Unsuspend a bridge technology.

Detailed Description

Channel Bridging API.

Author:: Joshua Colp <jcolp@digium.com>

Definition in file bridging_technology.h.

Define Documentation

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

See __ast_bridge_technology_register().

Definition at line 105 of file bridging_technology.h.

Referenced by load_module().

Enumeration Type Documentation

enum ast_bridge_preference

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.

00032                            {
00033    /*! Bridge technology should have high precedence over other bridge technologies */
00034    AST_BRIDGE_PREFERENCE_HIGH = 0,
00035    /*! Bridge technology is decent, not the best but should still be considered over low */
00036    AST_BRIDGE_PREFERENCE_MEDIUM,
00037    /*! Bridge technology is low, it should not be considered unless it is absolutely needed */
00038    AST_BRIDGE_PREFERENCE_LOW,
00039 };

Function Documentation

int __ast_bridge_technology_register	(	struct ast_bridge_technology *	technology,
		struct ast_module *	mod
	)

Register a bridge technology for use.

Parameters:

	technology	The bridge technology to register
	mod	The module that is registering the bridge technology

Return values:

	0	on success
	-1	on 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 62 of file bridging.c.

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

00063 {
00064    struct ast_bridge_technology *current = NULL;
00065 
00066    /* Perform a sanity check to make sure the bridge technology conforms to our needed requirements */
00067    if (ast_strlen_zero(technology->name) || !technology->capabilities || !technology->write) {
00068       ast_log(LOG_WARNING, "Bridge technology %s failed registration sanity check.\n", technology->name);
00069       return -1;
00070    }
00071 
00072    AST_RWLIST_WRLOCK(&bridge_technologies);
00073 
00074    /* Look for duplicate bridge technology already using this name, or already registered */
00075    AST_RWLIST_TRAVERSE(&bridge_technologies, current, entry) {
00076       if ((!strcasecmp(current->name, technology->name)) || (current == technology)) {
00077          ast_log(LOG_WARNING, "A bridge technology of %s already claims to exist in our world.\n", technology->name);
00078          AST_RWLIST_UNLOCK(&bridge_technologies);
00079          return -1;
00080       }
00081    }
00082 
00083    /* Copy module pointer so reference counting can keep the module from unloading */
00084    technology->mod = module;
00085 
00086    /* Insert our new bridge technology into the list and print out a pretty message */
00087    AST_RWLIST_INSERT_TAIL(&bridge_technologies, technology, entry);
00088 
00089    AST_RWLIST_UNLOCK(&bridge_technologies);
00090 
00091    ast_verb(2, "Registered bridge technology %s\n", technology->name);
00092 
00093    return 0;
00094 }

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:

	bridge	The bridge that the notification should influence
	bridge_channel	Bridge channel the notification was received on (if known)
	chan	Channel the notification was received on (if known)
	outfd	File 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 284 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_FRAME_DTMF_END, ast_frfree, ast_read(), ast_read_noaudio(), bridge_drop_control_frame(), bridge_handle_dtmf(), ast_bridge_features::dtmf_passthrough, 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().

00285 {
00286    /* If no bridge channel has been provided and the actual channel has been provided find it */
00287    if (chan && !bridge_channel) {
00288       bridge_channel = find_bridge_channel(bridge, chan);
00289    }
00290 
00291    /* If a bridge channel with actual channel is present read a frame and handle it */
00292    if (chan && bridge_channel) {
00293       struct ast_frame *frame = (((bridge->features.mute) || (bridge_channel->features && bridge_channel->features->mute)) ? ast_read_noaudio(chan) : ast_read(chan));
00294 
00295       /* This is pretty simple... see if they hung up */
00296       if (!frame || (frame->frametype == AST_FRAME_CONTROL && frame->subclass.integer == AST_CONTROL_HANGUP)) {
00297          /* Signal the thread that is handling the bridged channel that it should be ended */
00298          ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
00299       } else if (frame->frametype == AST_FRAME_CONTROL && bridge_drop_control_frame(frame->subclass.integer)) {
00300          ast_debug(1, "Dropping control frame from bridge channel %p\n", bridge_channel);
00301       } else if (frame->frametype == AST_FRAME_DTMF_BEGIN || frame->frametype == AST_FRAME_DTMF_END) {
00302          int dtmf_passthrough = bridge_channel->features ?
00303             bridge_channel->features->dtmf_passthrough :
00304             bridge->features.dtmf_passthrough;
00305 
00306          if (frame->frametype == AST_FRAME_DTMF_BEGIN) {
00307             frame = bridge_handle_dtmf(bridge, bridge_channel, frame);
00308          }
00309 
00310          if (frame && dtmf_passthrough) {
00311             bridge->technology->write(bridge, bridge_channel, frame);
00312          }
00313       } else {
00314          /* Simply write the frame out to the bridge technology if it still exists */
00315          bridge->technology->write(bridge, bridge_channel, frame);
00316       }
00317 
00318       if (frame) {
00319          ast_frfree(frame);
00320       }
00321       return;
00322    }
00323 
00324    /* If a file descriptor actually tripped pass it off to the bridge technology */
00325    if (outfd > -1 && bridge->technology->fd) {
00326       bridge->technology->fd(bridge, bridge_channel, outfd);
00327       return;
00328    }
00329 
00330    /* If all else fails just poke the bridge */
00331    if (bridge->technology->poke && bridge_channel) {
00332       bridge->technology->poke(bridge, bridge_channel);
00333       return;
00334    }
00335 
00336    return;
00337 }

void ast_bridge_notify_talking	(	struct ast_bridge *	bridge,
		struct ast_bridge_channel *	bridge_channel,
		int	started_talking
	)

Lets the bridging indicate when a bridge channel has stopped or started talking.

Note:: All DSP functionality on the bridge has been pushed down to the lowest possible layer, which in this case is the specific bridging technology being used. Since it is necessary for the knowledge of which channels are talking to make its way up to the application, this function has been created to allow the bridging technology to communicate that information with the bridging core.

Parameters:

	bridge	The bridge that the channel is a part of.
	bridge_channel	The bridge channel that has either started or stopped talking.
	started_talking,set	to 1 when this indicates the channel has started talking, set to 0 when this indicates the channel has stopped talking.

Definition at line 275 of file bridging.c.

References ast_bridge_change_state(), AST_BRIDGE_CHANNEL_STATE_START_TALKING, and AST_BRIDGE_CHANNEL_STATE_STOP_TALKING.

Referenced by softmix_bridge_write().

00276 {
00277    if (started_talking) {
00278       ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_START_TALKING);
00279    } else {
00280       ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_STOP_TALKING);
00281    }
00282 }

void ast_bridge_technology_suspend ( struct ast_bridge_technology * technology )

Suspend a bridge technology from consideration.

Parameters:

technology

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

References ast_bridge_technology::suspended.

01324 {
01325    technology->suspended = 1;
01326    return;
01327 }

int ast_bridge_technology_unregister ( struct ast_bridge_technology * technology )

Unregister a bridge technology from use.

Parameters:

technology

The bridge technology to unregister

Return values:

	0	on success
	-1	on 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 96 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_verb, and ast_bridge_technology::name.

Referenced by unload_module().

00097 {
00098    struct ast_bridge_technology *current = NULL;
00099 
00100    AST_RWLIST_WRLOCK(&bridge_technologies);
00101 
00102    /* Ensure the bridge technology is registered before removing it */
00103    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&bridge_technologies, current, entry) {
00104       if (current == technology) {
00105          AST_RWLIST_REMOVE_CURRENT(entry);
00106          ast_verb(2, "Unregistered bridge technology %s\n", technology->name);
00107          break;
00108       }
00109    }
00110    AST_RWLIST_TRAVERSE_SAFE_END;
00111 
00112    AST_RWLIST_UNLOCK(&bridge_technologies);
00113 
00114    return current ? 0 : -1;
00115 }

void ast_bridge_technology_unsuspend ( struct ast_bridge_technology * technology )

Unsuspend a bridge technology.

Parameters:

technology

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

References ast_bridge_technology::suspended.

01330 {
01331    technology->suspended = 0;
01332    return;
01333 }


Data Structures
struct	ast_bridge_technology
	Structure that is the essence of a bridge technology. More...
Defines
#define	ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
	See __ast_bridge_technology_register().
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.
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.
void	ast_bridge_notify_talking (struct ast_bridge bridge, struct ast_bridge_channel bridge_channel, int started_talking)
	Lets the bridging indicate when a bridge channel has stopped or started talking.
void	ast_bridge_technology_suspend (struct ast_bridge_technology *technology)
	Suspend a bridge technology from consideration.
int	ast_bridge_technology_unregister (struct ast_bridge_technology *technology)
	Unregister a bridge technology from use.
void	ast_bridge_technology_unsuspend (struct ast_bridge_technology *technology)
	Unsuspend a bridge technology.

Asterisk developer's documentation

bridging_technology.h File Reference

Data Structures

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation