Thu Apr 28 2011 16:56:55

Asterisk developer's documentation


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

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

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
moduleThe 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 59 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.

{
   struct ast_bridge_technology *current = NULL;

   /* Perform a sanity check to make sure the bridge technology conforms to our needed requirements */
   if (ast_strlen_zero(technology->name) || !technology->capabilities || !technology->write) {
      ast_log(LOG_WARNING, "Bridge technology %s failed registration sanity check.\n", technology->name);
      return -1;
   }

   AST_RWLIST_WRLOCK(&bridge_technologies);

   /* Look for duplicate bridge technology already using this name, or already registered */
   AST_RWLIST_TRAVERSE(&bridge_technologies, current, entry) {
      if ((!strcasecmp(current->name, technology->name)) || (current == technology)) {
         ast_log(LOG_WARNING, "A bridge technology of %s already claims to exist in our world.\n", technology->name);
         AST_RWLIST_UNLOCK(&bridge_technologies);
         return -1;
      }
   }

   /* Copy module pointer so reference counting can keep the module from unloading */
   technology->mod = module;

   /* Insert our new bridge technology into the list and print out a pretty message */
   AST_RWLIST_INSERT_TAIL(&bridge_technologies, technology, entry);

   AST_RWLIST_UNLOCK(&bridge_technologies);

   if (option_verbose > 1) {
      ast_verbose(VERBOSE_PREFIX_2 "Registered bridge technology %s\n", technology->name);
   }

   return 0;
}
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 276 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_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().

{
   /* If no bridge channel has been provided and the actual channel has been provided find it */
   if (chan && !bridge_channel) {
      bridge_channel = find_bridge_channel(bridge, chan);
   }

   /* If a bridge channel with actual channel is present read a frame and handle it */
   if (chan && bridge_channel) {
      struct ast_frame *frame = (((bridge->features.mute) || (bridge_channel->features && bridge_channel->features->mute)) ? ast_read_noaudio(chan) : ast_read(chan));

      /* This is pretty simple... see if they hung up */
      if (!frame || (frame->frametype == AST_FRAME_CONTROL && frame->subclass == AST_CONTROL_HANGUP)) {
         /* Signal the thread that is handling the bridged channel that it should be ended */
         ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
      } else if (frame->frametype == AST_FRAME_CONTROL && bridge_drop_control_frame(frame->subclass)) {
         ast_debug(1, "Dropping control frame from bridge channel %p\n", bridge_channel);
      } else {
         if (frame->frametype == AST_FRAME_DTMF_BEGIN) {
            frame = bridge_handle_dtmf(bridge, bridge_channel, frame);
         }
         /* Simply write the frame out to the bridge technology if it still exists */
         if (frame) {
            bridge->technology->write(bridge, bridge_channel, frame);
         }
      }

      if (frame) {
         ast_frfree(frame);
      }
      return;
   }

   /* If a file descriptor actually tripped pass it off to the bridge technology */
   if (outfd > -1 && bridge->technology->fd) {
      bridge->technology->fd(bridge, bridge_channel, outfd);
      return;
   }

   /* If all else fails just poke the bridge */
   if (bridge->technology->poke && bridge_channel) {
      bridge->technology->poke(bridge, bridge_channel);
      return;
   }

   return;
}
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 1228 of file bridging.c.

References ast_bridge_technology::suspended.

{
   technology->suspended = 1;
   return;
}
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 95 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().

{
   struct ast_bridge_technology *current = NULL;

   AST_RWLIST_WRLOCK(&bridge_technologies);

   /* Ensure the bridge technology is registered before removing it */
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&bridge_technologies, current, entry) {
      if (current == technology) {
         AST_RWLIST_REMOVE_CURRENT(entry);
         if (option_verbose > 1) {
            ast_verbose(VERBOSE_PREFIX_2 "Unregistered bridge technology %s\n", technology->name);
         }
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;

   AST_RWLIST_UNLOCK(&bridge_technologies);

   return current ? 0 : -1;
}
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 1234 of file bridging.c.

References ast_bridge_technology::suspended.

{
   technology->suspended = 0;
   return;
}