bridge_holding.c File Reference

Bridging technology for storing channels in a bridge for the purpose of holding, parking, queues, and other such states where a channel may need to be in a bridge but not actually communicating with anything. More...

#include "asterisk.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <sys/stat.h>
#include "asterisk/module.h"
#include "asterisk/channel.h"
#include "asterisk/bridge.h"
#include "asterisk/bridge_technology.h"
#include "asterisk/frame.h"
#include "asterisk/musiconhold.h"
#include "asterisk/format_cache.h"

Include dependency graph for bridge_holding.c:

Go to the source code of this file.

Data Structures
struct	deferred_data
struct	holding_channel
	Structure which contains per-channel role information. More...

Typedefs
typedef void(*	deferred_cb) (struct ast_bridge_channel *bridge_channel)

Enumerations
enum	holding_roles { HOLDING_ROLE_PARTICIPANT, HOLDING_ROLE_ANNOUNCER }
enum	idle_modes {   IDLE_MODE_NONE, IDLE_MODE_MOH, IDLE_MODE_RINGING, IDLE_MODE_SILENCE,   IDLE_MODE_HOLD }

Functions
static void	__reg_module (void)
static void	__unreg_module (void)
struct ast_module *	AST_MODULE_SELF_SYM (void)
static int	defer_action (struct ast_bridge_channel *bridge_channel, deferred_cb callback)
static void	deferred_action (struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size)
static void	handle_participant_join (struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *announcer_channel)
static int	holding_bridge_join (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
static void	holding_bridge_leave (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
static void	holding_bridge_suspend (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
static void	holding_bridge_unsuspend (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
static int	holding_bridge_write (struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame)
static int	load_module (void)
static void	participant_entertainment_start (struct ast_bridge_channel *bridge_channel)
static void	participant_entertainment_stop (struct ast_bridge_channel *bridge_channel)
static void	participant_idle_mode_setup (struct ast_bridge_channel *bridge_channel)
static void	participant_reaction_announcer_join (struct ast_bridge_channel *bridge_channel)
static void	participant_reaction_announcer_leave (struct ast_bridge_channel *bridge_channel)
static int	unload_module (void)

Variables
static struct ast_module_info	__mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_LOAD_ORDER , .description = "Holding bridge module" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "30ef0c93b36035ec78c9cfd712d36d9b" , .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_DEFAULT, .support_level = AST_MODULE_SUPPORT_CORE, }
static const struct ast_module_info *	ast_module_info = &__mod_info
static struct ast_bridge_technology	holding_bridge

Detailed Description

Bridging technology for storing channels in a bridge for the purpose of holding, parking, queues, and other such states where a channel may need to be in a bridge but not actually communicating with anything.

Author

Jonathan Rose jrose.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file bridge_holding.c.

Typedef Documentation

deferred_cb

typedef void(* deferred_cb) (struct ast_bridge_channel *bridge_channel)

Definition at line 73 of file bridge_holding.c.

Enumeration Type Documentation

holding_roles

enum holding_roles

Enumerator
HOLDING_ROLE_PARTICIPANT
HOLDING_ROLE_ANNOUNCER

Definition at line 51 of file bridge_holding.c.

                   {
   HOLDING_ROLE_PARTICIPANT,
   HOLDING_ROLE_ANNOUNCER,
};

idle_modes

enum idle_modes

Enumerator
IDLE_MODE_NONE
IDLE_MODE_MOH
IDLE_MODE_RINGING
IDLE_MODE_SILENCE
IDLE_MODE_HOLD

Definition at line 56 of file bridge_holding.c.

                {
   IDLE_MODE_NONE,
   IDLE_MODE_MOH,
   IDLE_MODE_RINGING,
   IDLE_MODE_SILENCE,
   IDLE_MODE_HOLD,
};

Function Documentation

__reg_module()

static void __reg_module ( void  )

static

Definition at line 446 of file bridge_holding.c.

__unreg_module()

static void __unreg_module ( void  )

static

Definition at line 446 of file bridge_holding.c.

AST_MODULE_SELF_SYM()

struct ast_module* AST_MODULE_SELF_SYM

(

void

)

Definition at line 446 of file bridge_holding.c.

defer_action()

static int defer_action ( struct ast_bridge_channel *  bridge_channel, deferred_cb  callback  )

static

Definition at line 93 of file bridge_holding.c.

References ast_bridge_channel_queue_callback(), ast_channel_name(), ast_log, ast_bridge_channel::bridge, deferred_data::callback, ast_bridge_channel::chan, deferred_action(), LOG_WARNING, and ast_bridge::uniqueid.

Referenced by handle_participant_join(), holding_bridge_join(), and holding_bridge_leave().

{
   struct deferred_data data = { .callback = callback };
   int res;

   res = ast_bridge_channel_queue_callback(bridge_channel, 0, deferred_action,
      &data, sizeof(data));
   if (res) {
      ast_log(LOG_WARNING, "Bridge %s: Could not defer action on %s.\n",
         bridge_channel->bridge->uniqueid, ast_channel_name(bridge_channel->chan));
   }
   return res;
}

deferred_action()

static void deferred_action ( struct ast_bridge_channel *  bridge_channel, const void *  payload, size_t  payload_size  )

static

Definition at line 416 of file bridge_holding.c.

References ast_bridge_channel_lock_bridge(), ast_bridge_unlock, ast_bridge_channel::bridge, deferred_data::callback, ast_bridge_channel::tech_pvt, and ast_bridge::technology.

Referenced by defer_action(), and smart_bridge_operation().

{
   const struct deferred_data *data = payload;

   ast_bridge_channel_lock_bridge(bridge_channel);
   if (bridge_channel->bridge->technology != &holding_bridge
      || !bridge_channel->tech_pvt) {
      /* Not valid anymore. */
      ast_bridge_unlock(bridge_channel->bridge);
      return;
   }
   data->callback(bridge_channel);
   ast_bridge_unlock(bridge_channel->bridge);
}

handle_participant_join()

static void handle_participant_join ( struct ast_bridge_channel *  bridge_channel, struct ast_bridge_channel *  announcer_channel  )

static

Definition at line 228 of file bridge_holding.c.

References ast_channel_name(), ast_format_slin, ast_log, ast_set_write_format(), ast_bridge_channel::chan, defer_action(), LOG_WARNING, and participant_entertainment_start().

Referenced by holding_bridge_join().

{
   struct ast_channel *us = bridge_channel->chan;

   /* If the announcer channel isn't present, we need to set up ringing, music on hold, or whatever. */
   if (!announcer_channel) {
      defer_action(bridge_channel, participant_entertainment_start);
      return;
   }

   /* We need to get compatible with the announcer. */
   if (ast_set_write_format(us, ast_format_slin)) {
      ast_log(LOG_WARNING, "Could not make participant %s compatible.\n", ast_channel_name(us));
   }
}

holding_bridge_join()

static int holding_bridge_join ( struct ast_bridge *  bridge, struct ast_bridge_channel *  bridge_channel  )

static

Definition at line 244 of file bridge_holding.c.

References ast_assert, ast_bridge_channel_has_role(), ast_calloc, ast_channel_name(), ast_format_slin, ast_free, AST_LIST_TRAVERSE, ast_log, ast_set_read_format(), ast_bridge_channel::chan, ast_bridge::channels, defer_action(), handle_participant_join(), HOLDING_ROLE_ANNOUNCER, HOLDING_ROLE_PARTICIPANT, LOG_ERROR, LOG_WARNING, NULL, participant_reaction_announcer_join(), holding_channel::role, ast_bridge_channel::tech_pvt, ast_bridge::tech_pvt, and ast_bridge::uniqueid.

{
   struct ast_bridge_channel *other_channel;
   struct ast_bridge_channel *announcer_channel;
   struct holding_channel *hc;
   struct ast_channel *us = bridge_channel->chan; /* The joining channel */

   ast_assert(bridge_channel->tech_pvt == NULL);

   if (!(hc = ast_calloc(1, sizeof(*hc)))) {
      return -1;
   }

   bridge_channel->tech_pvt = hc;

   /* The bridge pvt holds the announcer channel if we have one. */
   announcer_channel = bridge->tech_pvt;

   if (ast_bridge_channel_has_role(bridge_channel, "announcer")) {
      if (announcer_channel) {
         /* Another announcer already exists. */
         bridge_channel->tech_pvt = NULL;
         ast_free(hc);
         ast_log(LOG_WARNING, "Bridge %s: Channel %s tried to be an announcer.  Bridge already has one.\n",
            bridge->uniqueid, ast_channel_name(bridge_channel->chan));
         return -1;
      }

      bridge->tech_pvt = bridge_channel;
      hc->role = HOLDING_ROLE_ANNOUNCER;

      /* The announcer should always be made compatible with signed linear */
      if (ast_set_read_format(us, ast_format_slin)) {
         ast_log(LOG_ERROR, "Could not make announcer %s compatible.\n", ast_channel_name(us));
      }

      /* Make everyone listen to the announcer. */
      AST_LIST_TRAVERSE(&bridge->channels, other_channel, entry) {
         /* Skip the reaction if we are the channel in question */
         if (bridge_channel == other_channel) {
            continue;
         }
         defer_action(other_channel, participant_reaction_announcer_join);
      }

      return 0;
   }

   hc->role = HOLDING_ROLE_PARTICIPANT;
   handle_participant_join(bridge_channel, announcer_channel);
   return 0;
}

holding_bridge_leave()

static void holding_bridge_leave ( struct ast_bridge *  bridge, struct ast_bridge_channel *  bridge_channel  )

static

Definition at line 303 of file bridge_holding.c.

References ast_free, AST_LIST_TRAVERSE, ast_bridge::channels, defer_action(), HOLDING_ROLE_ANNOUNCER, NULL, participant_entertainment_stop(), participant_reaction_announcer_leave(), holding_channel::role, ast_bridge_channel::tech_pvt, and ast_bridge::tech_pvt.

{
   struct ast_bridge_channel *other_channel;
   struct holding_channel *hc = bridge_channel->tech_pvt;

   if (!hc) {
      return;
   }

   switch (hc->role) {
   case HOLDING_ROLE_ANNOUNCER:
      /* The announcer is leaving */
      bridge->tech_pvt = NULL;

      /* Reset the other channels back to moh/ringing. */
      AST_LIST_TRAVERSE(&bridge->channels, other_channel, entry) {
         defer_action(other_channel, participant_reaction_announcer_leave);
      }
      break;
   default:
      /* Nothing needs to react to its departure. */
      participant_entertainment_stop(bridge_channel);
      break;
   }
   bridge_channel->tech_pvt = NULL;
   ast_free(hc);
}

holding_bridge_suspend()

static void holding_bridge_suspend ( struct ast_bridge *  bridge, struct ast_bridge_channel *  bridge_channel  )

static

Definition at line 354 of file bridge_holding.c.

References HOLDING_ROLE_PARTICIPANT, participant_entertainment_stop(), holding_channel::role, and ast_bridge_channel::tech_pvt.

{
   struct holding_channel *hc = bridge_channel->tech_pvt;

   if (!hc) {
      return;
   }

   switch (hc->role) {
   case HOLDING_ROLE_PARTICIPANT:
      participant_entertainment_stop(bridge_channel);
      break;
   default:
      break;
   }
}

holding_bridge_unsuspend()

static void holding_bridge_unsuspend ( struct ast_bridge *  bridge, struct ast_bridge_channel *  bridge_channel  )

static

Definition at line 371 of file bridge_holding.c.

References HOLDING_ROLE_PARTICIPANT, participant_entertainment_start(), holding_channel::role, ast_bridge_channel::tech_pvt, and ast_bridge::tech_pvt.

{
   struct holding_channel *hc = bridge_channel->tech_pvt;
   struct ast_bridge_channel *announcer_channel = bridge->tech_pvt;

   if (!hc) {
      return;
   }

   switch (hc->role) {
   case HOLDING_ROLE_PARTICIPANT:
      if (announcer_channel) {
         /* There is an announcer channel in the bridge. */
         break;
      }
      /* We need to restart the entertainment. */
      participant_entertainment_start(bridge_channel);
      break;
   default:
      break;
   }
}

holding_bridge_write()

static int holding_bridge_write ( struct ast_bridge *  bridge, struct ast_bridge_channel *  bridge_channel, struct ast_frame *  frame  )

static

Definition at line 331 of file bridge_holding.c.

References ast_bridge_queue_everyone_else(), HOLDING_ROLE_ANNOUNCER, NULL, holding_channel::role, and ast_bridge_channel::tech_pvt.

{
   struct holding_channel *hc = bridge_channel ? bridge_channel->tech_pvt : NULL;

   /* If there is no tech_pvt, then the channel failed to allocate one when it joined and is borked. Don't listen to him. */
   if (!hc) {
      /* "Accept" the frame and discard it. */
      return 0;
   }

   switch (hc->role) {
   case HOLDING_ROLE_ANNOUNCER:
      /* Write the frame to all other channels if any. */
      ast_bridge_queue_everyone_else(bridge, bridge_channel, frame);
      break;
   default:
      /* "Accept" the frame and discard it. */
      break;
   }

   return 0;
}

load_module()

static int load_module ( void  )

static

Definition at line 437 of file bridge_holding.c.

References ast_bridge_technology_register, AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, and unload_module().

{
   if (ast_bridge_technology_register(&holding_bridge)) {
      unload_module();
      return AST_MODULE_LOAD_DECLINE;
   }
   return AST_MODULE_LOAD_SUCCESS;
}

participant_entertainment_start()

static void participant_entertainment_start ( struct ast_bridge_channel *  bridge_channel )

static

Definition at line 188 of file bridge_holding.c.

References ast_assert, ast_bridge_channel_get_role_option(), ast_channel_start_silence_generator(), AST_CONTROL_HOLD, AST_CONTROL_RINGING, ast_indicate(), ast_indicate_data(), ast_log, ast_moh_start(), ast_bridge_channel::chan, holding_channel::entertainment_active, holding_channel::idle_mode, IDLE_MODE_HOLD, IDLE_MODE_MOH, IDLE_MODE_NONE, IDLE_MODE_RINGING, IDLE_MODE_SILENCE, LOG_WARNING, NULL, participant_idle_mode_setup(), holding_channel::silence_generator, and ast_bridge_channel::tech_pvt.

Referenced by handle_participant_join(), holding_bridge_unsuspend(), and participant_reaction_announcer_leave().

{
   struct holding_channel *hc = bridge_channel->tech_pvt;
   const char *moh_class;
   size_t moh_length;

   ast_assert(hc != NULL);

   if (hc->entertainment_active) {
      /* Already started */
      return;
   }
   hc->entertainment_active = 1;

   participant_idle_mode_setup(bridge_channel);
   switch(hc->idle_mode) {
   case IDLE_MODE_MOH:
      moh_class = ast_bridge_channel_get_role_option(bridge_channel, "holding_participant", "moh_class");
      if (ast_moh_start(bridge_channel->chan, moh_class, NULL)) {
         ast_log(LOG_WARNING, "Failed to start moh, starting silence generator instead\n");
         hc->idle_mode = IDLE_MODE_SILENCE;
         hc->silence_generator = ast_channel_start_silence_generator(bridge_channel->chan);
      }
      break;
   case IDLE_MODE_RINGING:
      ast_indicate(bridge_channel->chan, AST_CONTROL_RINGING);
      break;
   case IDLE_MODE_NONE:
      break;
   case IDLE_MODE_SILENCE:
      hc->silence_generator = ast_channel_start_silence_generator(bridge_channel->chan);
      break;
   case IDLE_MODE_HOLD:
      moh_class = ast_bridge_channel_get_role_option(bridge_channel, "holding_participant", "moh_class");
      moh_length = moh_class ? strlen(moh_class + 1) : 0;
      ast_indicate_data(bridge_channel->chan, AST_CONTROL_HOLD, moh_class, moh_length);
      break;
   }
}

participant_entertainment_stop()

static void participant_entertainment_stop ( struct ast_bridge_channel *  bridge_channel )

static

Definition at line 143 of file bridge_holding.c.

References ast_assert, ast_channel_stop_silence_generator(), AST_CONTROL_UNHOLD, ast_indicate(), ast_moh_stop(), ast_bridge_channel::chan, holding_channel::entertainment_active, holding_channel::idle_mode, IDLE_MODE_HOLD, IDLE_MODE_MOH, IDLE_MODE_NONE, IDLE_MODE_RINGING, IDLE_MODE_SILENCE, NULL, holding_channel::silence_generator, and ast_bridge_channel::tech_pvt.

Referenced by holding_bridge_leave(), holding_bridge_suspend(), and participant_reaction_announcer_join().

{
   struct holding_channel *hc = bridge_channel->tech_pvt;

   ast_assert(hc != NULL);

   if (!hc->entertainment_active) {
      /* Already stopped */
      return;
   }
   hc->entertainment_active = 0;

   switch (hc->idle_mode) {
   case IDLE_MODE_MOH:
      ast_moh_stop(bridge_channel->chan);
      break;
   case IDLE_MODE_RINGING:
      ast_indicate(bridge_channel->chan, -1);
      break;
   case IDLE_MODE_NONE:
      break;
   case IDLE_MODE_SILENCE:
      if (hc->silence_generator) {
         ast_channel_stop_silence_generator(bridge_channel->chan, hc->silence_generator);
         hc->silence_generator = NULL;
      }
      break;
   case IDLE_MODE_HOLD:
      ast_indicate(bridge_channel->chan, AST_CONTROL_UNHOLD);
      break;
   }
}

participant_idle_mode_setup()

static void participant_idle_mode_setup ( struct ast_bridge_channel *  bridge_channel )

static

Definition at line 116 of file bridge_holding.c.

References ast_assert, ast_bridge_channel_get_role_option(), ast_channel_name(), ast_debug, ast_strlen_zero, ast_bridge_channel::chan, holding_channel::idle_mode, IDLE_MODE_HOLD, IDLE_MODE_MOH, IDLE_MODE_NONE, IDLE_MODE_RINGING, IDLE_MODE_SILENCE, NULL, and ast_bridge_channel::tech_pvt.

Referenced by participant_entertainment_start().

{
   const char *idle_mode = ast_bridge_channel_get_role_option(bridge_channel, "holding_participant", "idle_mode");
   struct holding_channel *hc = bridge_channel->tech_pvt;

   ast_assert(hc != NULL);

   if (ast_strlen_zero(idle_mode)) {
      hc->idle_mode = IDLE_MODE_MOH;
   } else if (!strcmp(idle_mode, "musiconhold")) {
      hc->idle_mode = IDLE_MODE_MOH;
   } else if (!strcmp(idle_mode, "ringing")) {
      hc->idle_mode = IDLE_MODE_RINGING;
   } else if (!strcmp(idle_mode, "none")) {
      hc->idle_mode = IDLE_MODE_NONE;
   } else if (!strcmp(idle_mode, "silence")) {
      hc->idle_mode = IDLE_MODE_SILENCE;
   } else if (!strcmp(idle_mode, "hold")) {
      hc->idle_mode = IDLE_MODE_HOLD;
   } else {
      /* Invalid idle mode requested. */
      ast_debug(1, "channel %s idle mode '%s' doesn't match any defined idle mode\n",
         ast_channel_name(bridge_channel->chan), idle_mode);
      ast_assert(0);
   }
}

participant_reaction_announcer_join()

static void participant_reaction_announcer_join ( struct ast_bridge_channel *  bridge_channel )

static

Definition at line 176 of file bridge_holding.c.

References ast_channel_name(), ast_format_slin, ast_log, ast_set_write_format(), ast_bridge_channel::chan, LOG_WARNING, and participant_entertainment_stop().

Referenced by holding_bridge_join().

{
   struct ast_channel *chan;

   chan = bridge_channel->chan;
   participant_entertainment_stop(bridge_channel);
   if (ast_set_write_format(chan, ast_format_slin)) {
      ast_log(LOG_WARNING, "Could not make participant %s compatible.\n", ast_channel_name(chan));
   }
}

participant_reaction_announcer_leave()

static void participant_reaction_announcer_leave ( struct ast_bridge_channel *  bridge_channel )

static

Definition at line 297 of file bridge_holding.c.

References ast_bridge_channel_restore_formats(), and participant_entertainment_start().

Referenced by holding_bridge_leave().

{
   ast_bridge_channel_restore_formats(bridge_channel);
   participant_entertainment_start(bridge_channel);
}

unload_module()

static int unload_module ( void  )

static

Definition at line 431 of file bridge_holding.c.

References ast_bridge_technology_unregister().

Referenced by load_module().

{
   ast_bridge_technology_unregister(&holding_bridge);
   return 0;
}

Variable Documentation

__mod_info

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_LOAD_ORDER , .description = "Holding bridge module" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "30ef0c93b36035ec78c9cfd712d36d9b" , .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_DEFAULT, .support_level = AST_MODULE_SUPPORT_CORE, }

static

Definition at line 446 of file bridge_holding.c.

ast_module_info

const struct ast_module_info* ast_module_info = &__mod_info

static

Definition at line 446 of file bridge_holding.c.

holding_bridge

struct ast_bridge_technology holding_bridge

static

Definition at line 394 of file bridge_holding.c.