features.h File Reference

Call Parking and Pickup API Includes code and algorithms from the Zapata library. More...

#include "asterisk/pbx.h"
#include "asterisk/linkedlists.h"
#include "asterisk/bridge.h"

Include dependency graph for features.h:

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

Go to the source code of this file.

Enumerations
enum	{   AST_FEATURE_FLAG_NEEDSDTMF = (1 << 0), AST_FEATURE_FLAG_ONPEER = (1 << 1), AST_FEATURE_FLAG_ONSELF = (1 << 2), AST_FEATURE_FLAG_BYCALLEE = (1 << 3),   AST_FEATURE_FLAG_BYCALLER = (1 << 4), AST_FEATURE_FLAG_BYBOTH = (3 << 3) }
	main call feature structure More...

Functions
int	ast_bridge_add_channel (struct ast_bridge *bridge, struct ast_channel *chan, struct ast_bridge_features *features, int play_tone, const char *xfersound)
	Add an arbitrary channel to a bridge. More...
int	ast_bridge_call (struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config)
	Bridge a call, optionally allowing redirection. More...
int	ast_bridge_call_with_flags (struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, unsigned int flags)
	Bridge a call, and add additional flags to the bridge. More...
int	ast_bridge_timelimit (struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit)
	parse L option and read associated channel variables to set warning, warning frequency, and timelimit More...

Detailed Description

Call Parking and Pickup API Includes code and algorithms from the Zapata library.

Definition in file features.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

main call feature structure

Enumerator
AST_FEATURE_FLAG_NEEDSDTMF
AST_FEATURE_FLAG_ONPEER
AST_FEATURE_FLAG_ONSELF
AST_FEATURE_FLAG_BYCALLEE
AST_FEATURE_FLAG_BYCALLER
AST_FEATURE_FLAG_BYBOTH

Definition at line 33 of file features.h.

     {
   AST_FEATURE_FLAG_NEEDSDTMF = (1 << 0),
   AST_FEATURE_FLAG_ONPEER =    (1 << 1),
   AST_FEATURE_FLAG_ONSELF =    (1 << 2),
   AST_FEATURE_FLAG_BYCALLEE =  (1 << 3),
   AST_FEATURE_FLAG_BYCALLER =  (1 << 4),
   AST_FEATURE_FLAG_BYBOTH  =   (3 << 3),
};

Function Documentation

ast_bridge_add_channel()

int ast_bridge_add_channel	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan,
		struct ast_bridge_features *	features,
		int	play_tone,
		const char *	xfersound
	)

Add an arbitrary channel to a bridge.

Since

12.0.0

The channel that is being added to the bridge can be in any state: unbridged, bridged, answered, unanswered, etc. The channel will be added asynchronously, meaning that when this function returns once the channel has been added to the bridge, not once the channel has been removed from the bridge.

In addition, a tone can optionally be played to the channel once the channel is placed into the bridge.

Note

When this function returns, there is no guarantee that the channel that was passed in is valid any longer. Do not attempt to operate on the channel after this function returns.

Parameters

bridge	Bridge to which the channel should be added
chan	The channel to add to the bridge
features	Features for this channel in the bridge
play_tone	Indicates if a tone should be played to the channel
xfersound	Sound that should be used to indicate transfer with play_tone

Note

The features parameter must be NULL or obtained by ast_bridge_features_new(). You must not dereference features after calling even if the call fails.

Return values

0	Success
-1	Failure

Definition at line 2519 of file bridge.c.

References ao2_cleanup, ast_answer(), ast_assert, ast_bridge_channel_queue_playfile(), ast_bridge_features_destroy(), ast_bridge_impart(), AST_BRIDGE_IMPART_CHAN_INDEPENDENT, ast_bridge_lock_both, ast_bridge_unlock, ast_channel_get_bridge(), ast_channel_get_bridge_channel(), ast_channel_lock, ast_channel_name(), ast_channel_pbx(), ast_channel_ref, ast_channel_unlock, ast_channel_unref, ast_channel_yank(), ast_hangup(), ast_log, ast_moh_stop(), AST_STATE_UP, ast_strlen_zero, bridge_dissolve_check_stolen(), bridge_find_channel(), bridge_move_locked(), LOG_WARNING, NULL, and RAII_VAR.

Referenced by action_bridge(), bridge_exec(), and manager_park_unbridged().

{
   RAII_VAR(struct ast_bridge *, chan_bridge, NULL, ao2_cleanup);
   RAII_VAR(struct ast_channel *, yanked_chan, NULL, ao2_cleanup);

   ast_moh_stop(chan);

   ast_channel_lock(chan);
   chan_bridge = ast_channel_get_bridge(chan);
   ast_channel_unlock(chan);

   if (chan_bridge) {
      struct ast_bridge_channel *bridge_channel;

      /* The channel is in a bridge so it is not getting any new features. */
      ast_bridge_features_destroy(features);

      ast_bridge_lock_both(bridge, chan_bridge);
      bridge_channel = bridge_find_channel(chan_bridge, chan);

      if (bridge_move_locked(bridge, chan_bridge, chan, NULL, 1)) {
         ast_bridge_unlock(chan_bridge);
         ast_bridge_unlock(bridge);
         return -1;
      }

      /*
       * bridge_move_locked() will implicitly ensure that
       * bridge_channel is not NULL.
       */
      ast_assert(bridge_channel != NULL);

      /*
       * Additional checks if the channel we just stole dissolves the
       * original bridge.
       */
      bridge_dissolve_check_stolen(chan_bridge, bridge_channel);
      ast_bridge_unlock(chan_bridge);
      ast_bridge_unlock(bridge);
   } else {
      /* Slightly less easy case. We need to yank channel A from
       * where he currently is and impart him into our bridge.
       */
      yanked_chan = ast_channel_yank(chan);
      if (!yanked_chan) {
         ast_log(LOG_WARNING, "Could not gain control of channel %s\n", ast_channel_name(chan));
         ast_bridge_features_destroy(features);
         return -1;
      }
      if (ast_channel_state(yanked_chan) != AST_STATE_UP) {
         ast_answer(yanked_chan);
      }
      ast_channel_ref(yanked_chan);
      if (ast_bridge_impart(bridge, yanked_chan, NULL, features,
         AST_BRIDGE_IMPART_CHAN_INDEPENDENT)) {
         /* It is possible for us to yank a channel and have some other
          * thread start a PBX on the channl after we yanked it. In particular,
          * this can theoretically happen on the ;2 of a Local channel if we
          * yank it prior to the ;1 being answered. Make sure that it isn't
          * executing a PBX before hanging it up.
          */
         if (ast_channel_pbx(yanked_chan)) {
            ast_channel_unref(yanked_chan);
         } else {
            ast_hangup(yanked_chan);
         }
         return -1;
      }
   }

   if (play_tone && !ast_strlen_zero(xfersound)) {
      struct ast_channel *play_chan = yanked_chan ?: chan;
      RAII_VAR(struct ast_bridge_channel *, play_bridge_channel, NULL, ao2_cleanup);

      ast_channel_lock(play_chan);
      play_bridge_channel = ast_channel_get_bridge_channel(play_chan);
      ast_channel_unlock(play_chan);

      if (!play_bridge_channel) {
         ast_log(LOG_WARNING, "Unable to play tone for channel %s. No longer in a bridge.\n",
            ast_channel_name(play_chan));
      } else {
         ast_bridge_channel_queue_playfile(play_bridge_channel, NULL, xfersound, NULL);
      }
   }
   return 0;
}

ast_bridge_call()

int ast_bridge_call	(	struct ast_channel *	chan,
		struct ast_channel *	peer,
		struct ast_bridge_config *	config
	)

Bridge a call, optionally allowing redirection.

Note

The function caller is assumed to have already done the COLP exchange for the initial bridging of the two channels if it was desired.

Bridge a call, optionally allowing redirection.

Parameters

chan	The bridge considers this channel the caller.
peer	The bridge considers this channel the callee.
config	Configuration for this bridge.

Set start time, check for two channels,check if monitor on check for feature activation, create new CDR

Return values

res	on success.
-1	on failure to bridge.

Definition at line 716 of file features.c.

References ast_bridge_call_with_flags().

Referenced by app_exec(), and dial_exec_full().

{
   return ast_bridge_call_with_flags(chan, peer, config, 0);
}

ast_bridge_call_with_flags()

int ast_bridge_call_with_flags	(	struct ast_channel *	chan,
		struct ast_channel *	peer,
		struct ast_bridge_config *	config,
		unsigned int	flags
	)

Bridge a call, and add additional flags to the bridge.

This does the same thing as ast_bridge_call, except that once the bridge is created, the provided flags are set on the bridge. The provided flags are added to the bridge's flags; they will not clear any flags already set.

Parameters

chan	The calling channel
peer	The called channel
config	Bridge configuration for the channels
flags	Additional flags to set on the created bridge

Note

The function caller is assumed to have already done the COLP exchange for the initial bridging of the two channels if it was desired.

Definition at line 633 of file features.c.

References ast_bridge_basic_new(), ast_bridge_basic_set_flags(), ast_bridge_destroy(), ast_bridge_features_cleanup(), ast_bridge_features_destroy(), ast_bridge_features_init(), ast_bridge_features_new(), ast_bridge_impart(), AST_BRIDGE_IMPART_CHAN_INDEPENDENT, AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP, ast_bridge_join(), AST_BRIDGE_JOIN_INHIBIT_JOIN_COLP, AST_BRIDGE_JOIN_PASS_REFERENCE, ast_channel_lock, ast_channel_name(), ast_channel_softhangup_internal_flag(), ast_channel_unlock, AST_SOFTHANGUP_ASYNCGOTO, bridge_failed_peer_goto(), ast_bridge_config::end_bridge_callback, ast_bridge_config::end_bridge_callback_data, NULL, ast_dial_features::peer_features, pre_bridge_setup(), and SCOPE_TRACE.

Referenced by ast_bridge_call(), and try_calling().

{
   int res;
   struct ast_bridge *bridge;
   struct ast_bridge_features chan_features;
   struct ast_bridge_features *peer_features;
   SCOPE_TRACE(1, "%s Peer: %s\n", ast_channel_name(chan), ast_channel_name(peer));

   /* Setup features. */
   res = ast_bridge_features_init(&chan_features);
   peer_features = ast_bridge_features_new();
   if (res || !peer_features) {
      ast_bridge_features_destroy(peer_features);
      ast_bridge_features_cleanup(&chan_features);
      bridge_failed_peer_goto(chan, peer);
      return -1;
   }

   if (pre_bridge_setup(chan, peer, config, &chan_features, peer_features)) {
      ast_bridge_features_destroy(peer_features);
      ast_bridge_features_cleanup(&chan_features);
      bridge_failed_peer_goto(chan, peer);
      return -1;
   }

   /* Create bridge */
   bridge = ast_bridge_basic_new();
   if (!bridge) {
      ast_bridge_features_destroy(peer_features);
      ast_bridge_features_cleanup(&chan_features);
      bridge_failed_peer_goto(chan, peer);
      return -1;
   }

   ast_bridge_basic_set_flags(bridge, flags);

   /* Put peer into the bridge */
   if (ast_bridge_impart(bridge, peer, NULL, peer_features,
      AST_BRIDGE_IMPART_CHAN_INDEPENDENT | AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP)) {
      ast_bridge_destroy(bridge, 0);
      ast_bridge_features_cleanup(&chan_features);
      bridge_failed_peer_goto(chan, peer);
      return -1;
   }

   /* Join bridge */
   ast_bridge_join(bridge, chan, NULL, &chan_features, NULL,
      AST_BRIDGE_JOIN_PASS_REFERENCE | AST_BRIDGE_JOIN_INHIBIT_JOIN_COLP);

   /*
    * If the bridge was broken for a hangup that isn't real, then
    * don't run the h extension, because the channel isn't really
    * hung up.  This should really only happen with
    * AST_SOFTHANGUP_ASYNCGOTO.
    */
   res = -1;
   ast_channel_lock(chan);
   if (ast_channel_softhangup_internal_flag(chan) & AST_SOFTHANGUP_ASYNCGOTO) {
      res = 0;
   }
   ast_channel_unlock(chan);

   ast_bridge_features_cleanup(&chan_features);

   if (res && config->end_bridge_callback) {
      config->end_bridge_callback(config->end_bridge_callback_data);
   }

   return res;
}

ast_bridge_timelimit()

int ast_bridge_timelimit	(	struct ast_channel *	chan,
		struct ast_bridge_config *	config,
		char *	parse,
		struct timeval *	calldurationlimit
	)

parse L option and read associated channel variables to set warning, warning frequency, and timelimit

Note

caller must be aware of freeing memory for warning_sound, end_sound, and start_sound

Definition at line 886 of file features.c.

References ast_channel_lock, ast_channel_unlock, AST_FEATURE_PLAY_WARNING, ast_log, ast_set_flag, ast_strdup, ast_strdupa, ast_strlen_zero, ast_true(), ast_verb, ast_bridge_config::end_sound, ast_bridge_config::features_callee, ast_bridge_config::features_caller, LOG_WARNING, NULL, pbx_builtin_getvar_helper(), ast_bridge_config::play_warning, S_OR, ast_bridge_config::start_sound, strsep(), ast_bridge_config::timelimit, var, ast_bridge_config::warning_freq, and ast_bridge_config::warning_sound.

Referenced by bridge_exec(), and dial_exec_full().

{
   char *stringp = ast_strdupa(parse);
   char *limit_str, *warning_str, *warnfreq_str;
   const char *var;
   int play_to_caller = 0, play_to_callee = 0;
   int delta;

   limit_str = strsep(&stringp, ":");
   warning_str = strsep(&stringp, ":");
   warnfreq_str = strsep(&stringp, ":");

   config->timelimit = atol(limit_str);
   if (warning_str)
      config->play_warning = atol(warning_str);
   if (warnfreq_str)
      config->warning_freq = atol(warnfreq_str);

   if (!config->timelimit) {
      ast_log(LOG_WARNING, "Bridge does not accept L(%s)\n", limit_str);
      config->timelimit = config->play_warning = config->warning_freq = 0;
      config->warning_sound = NULL;
      return -1; /* error */
   } else if ( (delta = config->play_warning - config->timelimit) > 0) {
      int w = config->warning_freq;

      /*
       * If the first warning is requested _after_ the entire call
       * would end, and no warning frequency is requested, then turn
       * off the warning. If a warning frequency is requested, reduce
       * the 'first warning' time by that frequency until it falls
       * within the call's total time limit.
       *
       * Graphically:
       *                timelim->|    delta        |<-playwarning
       *      0__________________|_________________|
       *                       | w  |    |    |    |
       *
       * so the number of intervals to cut is 1+(delta-1)/w
       */
      if (w == 0) {
         config->play_warning = 0;
      } else {
         config->play_warning -= w * ( 1 + (delta-1)/w );
         if (config->play_warning < 1)
            config->play_warning = config->warning_freq = 0;
      }
   }

   ast_channel_lock(chan);

   var = pbx_builtin_getvar_helper(chan, "LIMIT_PLAYAUDIO_CALLER");
   play_to_caller = var ? ast_true(var) : 1;

   var = pbx_builtin_getvar_helper(chan, "LIMIT_PLAYAUDIO_CALLEE");
   play_to_callee = var ? ast_true(var) : 0;

   if (!play_to_caller && !play_to_callee)
      play_to_caller = 1;

   var = pbx_builtin_getvar_helper(chan, "LIMIT_WARNING_FILE");
   config->warning_sound = !ast_strlen_zero(var) ? ast_strdup(var) : ast_strdup("timeleft");

   /* The code looking at config wants a NULL, not just "", to decide
    * that the message should not be played, so we replace "" with NULL.
    * Note, pbx_builtin_getvar_helper _can_ return NULL if the variable is
    * not found.
    */

   var = pbx_builtin_getvar_helper(chan, "LIMIT_TIMEOUT_FILE");
   config->end_sound = !ast_strlen_zero(var) ? ast_strdup(var) : NULL;

   var = pbx_builtin_getvar_helper(chan, "LIMIT_CONNECT_FILE");
   config->start_sound = !ast_strlen_zero(var) ? ast_strdup(var) : NULL;

   ast_channel_unlock(chan);

   /* undo effect of S(x) in case they are both used */
   calldurationlimit->tv_sec = 0;
   calldurationlimit->tv_usec = 0;

   /* more efficient to do it like S(x) does since no advanced opts */
   if (!config->play_warning && !config->start_sound && !config->end_sound && config->timelimit) {
      calldurationlimit->tv_sec = config->timelimit / 1000;
      calldurationlimit->tv_usec = (config->timelimit % 1000) * 1000;
      ast_verb(3, "Setting call duration limit to %.3lf seconds.\n",
         calldurationlimit->tv_sec + calldurationlimit->tv_usec / 1000000.0);
      play_to_caller = 0;
      play_to_callee = 0;
      config->timelimit = 0;
      config->play_warning = 0;
      config->warning_freq = 0;
   } else {
      ast_verb(4, "Limit Data for this call:\n");
      ast_verb(4, "timelimit      = %ld ms (%.3lf s)\n", config->timelimit, config->timelimit / 1000.0);
      ast_verb(4, "play_warning   = %ld ms (%.3lf s)\n", config->play_warning, config->play_warning / 1000.0);
      ast_verb(4, "play_to_caller = %s\n", play_to_caller ? "yes" : "no");
      ast_verb(4, "play_to_callee = %s\n", play_to_callee ? "yes" : "no");
      ast_verb(4, "warning_freq   = %ld ms (%.3lf s)\n", config->warning_freq, config->warning_freq / 1000.0);
      ast_verb(4, "start_sound    = %s\n", S_OR(config->start_sound, ""));
      ast_verb(4, "warning_sound  = %s\n", config->warning_sound);
      ast_verb(4, "end_sound      = %s\n", S_OR(config->end_sound, ""));
   }
   if (play_to_caller)
      ast_set_flag(&(config->features_caller), AST_FEATURE_PLAY_WARNING);
   if (play_to_callee)
      ast_set_flag(&(config->features_callee), AST_FEATURE_PLAY_WARNING);
   return 0;
}