bridge_holding.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2013, Digium, Inc.
 *
 * Jonathan Rose <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief 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 <[email protected]>
 *
 * \ingroup bridges
 */

/*** MODULEINFO
   <support_level>core</support_level>
 ***/

#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"

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,
};

/*! \brief Structure which contains per-channel role information */
struct holding_channel {
   struct ast_silence_generator *silence_generator;
   enum holding_roles role;
   enum idle_modes idle_mode;
   /*! TRUE if the entertainment is started. */
   unsigned int entertainment_active:1;
};

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

struct deferred_data {
   /*! Deferred holding technology callback */
   deferred_cb callback;
};

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

/*!
 * \internal
 * \brief Defer an action to a bridge_channel.
 * \since 12.0.0
 *
 * \param bridge_channel Which channel to operate on.
 * \param callback action to defer.
 *
 * \retval 0 on success.
 * \retval -1 on error.
 */
static int defer_action(struct ast_bridge_channel *bridge_channel, deferred_cb callback)
{
   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;
}

/*!
 * \internal
 * \brief Setup participant idle mode from channel.
 * \since 12.0.0
 *
 * \param bridge_channel Channel to setup idle mode.
 *
 * \return Nothing
 */
static void participant_idle_mode_setup(struct ast_bridge_channel *bridge_channel)
{
   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);
   }
}

static void participant_entertainment_stop(struct ast_bridge_channel *bridge_channel)
{
   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;
   }
}

static void participant_reaction_announcer_join(struct ast_bridge_channel *bridge_channel)
{
   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));
   }
}

/* This should only be called on verified holding_participants. */
static void participant_entertainment_start(struct ast_bridge_channel *bridge_channel)
{
   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;
   }
}

static void handle_participant_join(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *announcer_channel)
{
   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));
   }
}

static int holding_bridge_join(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
{
   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;
}

static void participant_reaction_announcer_leave(struct ast_bridge_channel *bridge_channel)
{
   ast_bridge_channel_restore_formats(bridge_channel);
   participant_entertainment_start(bridge_channel);
}

static void holding_bridge_leave(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
{
   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);
}

static int holding_bridge_write(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame)
{
   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;
}

static void holding_bridge_suspend(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
{
   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;
   }
}

static void holding_bridge_unsuspend(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
{
   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;
   }
}

static struct ast_bridge_technology holding_bridge = {
   .name = "holding_bridge",
   .capabilities = AST_BRIDGE_CAPABILITY_HOLDING,
   .preference = AST_BRIDGE_PREFERENCE_BASE_HOLDING,
   .write = holding_bridge_write,
   .join = holding_bridge_join,
   .leave = holding_bridge_leave,
   .suspend = holding_bridge_suspend,
   .unsuspend = holding_bridge_unsuspend,
};

/*!
 * \internal
 * \brief Deferred action to start/stop participant entertainment.
 * \since 12.0.0
 *
 * \param bridge_channel Which channel to operate on.
 * \param payload Data to pass to the callback. (NULL if none).
 * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
 *
 * \return Nothing
 */
static void deferred_action(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size)
{
   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);
}

static int unload_module(void)
{
   ast_bridge_technology_unregister(&holding_bridge);
   return 0;
}

static int load_module(void)
{
   if (ast_bridge_technology_register(&holding_bridge)) {
      unload_module();
      return AST_MODULE_LOAD_DECLINE;
   }
   return AST_MODULE_LOAD_SUCCESS;
}

AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Holding bridge module");