pickup.c File Reference

Routines implementing call pickup. More...

#include "asterisk.h"
#include "asterisk/pickup.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/app.h"
#include "asterisk/callerid.h"
#include "asterisk/causes.h"
#include "asterisk/stasis.h"
#include "asterisk/stasis_channels.h"
#include "asterisk/features_config.h"

Include dependency graph for pickup.c:

Go to the source code of this file.

Functions
int	ast_can_pickup (struct ast_channel *chan)
	Test if a channel can be picked up. More...
int	ast_do_pickup (struct ast_channel *chan, struct ast_channel *target)
	Pickup a call target. More...
int	ast_pickup_call (struct ast_channel *chan)
	Pickup a call. More...
struct ast_channel *	ast_pickup_find_by_group (struct ast_channel *chan)
	Find a pickup channel target by group. More...
int	ast_pickup_init (void)
	Initialize pickup. More...
static struct ast_manager_event_blob *	call_pickup_to_ami (struct stasis_message *message)
static int	find_channel_by_group (void *obj, void *arg, void *data, int flags)
static void	pickup_shutdown (void)
static int	send_call_pickup_stasis_message (struct ast_channel *picking_up, struct ast_channel_snapshot *chan, struct ast_channel_snapshot *target)
	STASIS_MESSAGE_TYPE_DEFN (ast_call_pickup_type,.to_ami=call_pickup_to_ami)

Variables
static const struct ast_datastore_info	pickup_active

Detailed Description

Routines implementing call pickup.

Author

Matt Jordan mjord.nosp@m.an@d.nosp@m.igium.nosp@m..com

Definition in file pickup.c.

Function Documentation

ast_can_pickup()

int ast_can_pickup

(

struct ast_channel *

chan

)

Test if a channel can be picked up.

Parameters

chan	Channel to test if can be picked up.

Note

This function assumes that chan is locked.

Returns

TRUE if channel can be picked up.

Definition at line 77 of file pickup.c.

References ast_channel_datastore_find(), ast_channel_flags(), ast_channel_masq(), ast_channel_pbx(), AST_FLAG_ZOMBIE, AST_STATE_DOWN, AST_STATE_RING, AST_STATE_RINGING, ast_test_flag, and NULL.

Referenced by ast_pickup_find_by_group(), find_by_mark(), find_by_name(), find_by_uniqueid(), find_channel_by_group(), handle_invite_replaces(), and pickup_by_exten().

{
   if (!ast_channel_pbx(chan) && !ast_channel_masq(chan) && !ast_test_flag(ast_channel_flags(chan), AST_FLAG_ZOMBIE)
      && (ast_channel_state(chan) == AST_STATE_RINGING
         || ast_channel_state(chan) == AST_STATE_RING
         /*
          * Check the down state as well because some SIP devices do not
          * give 180 ringing when they can just give 183 session progress
          * instead.  Issue 14005.  (Some ISDN switches as well for that
          * matter.)
          */
         || ast_channel_state(chan) == AST_STATE_DOWN)
      && !ast_channel_datastore_find(chan, &pickup_active, NULL)) {
      return 1;
   }
   return 0;
}

ast_do_pickup()

int ast_do_pickup	(	struct ast_channel *	chan,
		struct ast_channel *	target
	)

Pickup a call target.

Parameters

chan	channel that initiated pickup.
target	channel to be picked up.

Note

This function assumes that target is locked.

Return values

0	on success.
-1	on failure.

< A masquerade changes channel names.

< A masquerade changes channel names.

Definition at line 302 of file pickup.c.

References ao2_cleanup, ast_answer(), AST_CAUSE_ANSWERED_ELSEWHERE, ast_channel_caller(), ast_channel_connected(), ast_channel_connected_line_macro(), ast_channel_connected_line_sub(), ast_channel_datastore_add(), ast_channel_datastore_remove(), ast_channel_hangupcause_set(), ast_channel_lock, ast_channel_move(), ast_channel_name(), ast_channel_queue_connected_line_update(), ast_channel_snapshot_create(), ast_channel_snapshot_get_latest(), ast_channel_uniqueid(), ast_channel_unlock, ast_channel_update_connected_line(), ast_connected_line_copy_from_caller(), AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER, AST_CONTROL_ANSWER, ast_datastore_alloc, ast_datastore_free(), ast_debug, ast_log, ast_party_connected_line_copy(), ast_party_connected_line_free(), ast_party_connected_line_init(), ast_party_id_reset(), ast_queue_control(), ast_strdupa, LOG_WARNING, NULL, ast_party_connected_line::priv, RAII_VAR, send_call_pickup_stasis_message(), and ast_party_connected_line::source.

Referenced by ast_pickup_call(), AST_TEST_DEFINE(), handle_invite_replaces(), pickup_by_channel(), pickup_by_exten(), pickup_by_group(), pickup_by_mark(), and pickup_by_part().

{
   struct ast_party_connected_line connected_caller;
   struct ast_datastore *ds_pickup;
   const char *chan_name;/*!< A masquerade changes channel names. */
   const char *target_name;/*!< A masquerade changes channel names. */
   int res = -1;

   RAII_VAR(struct ast_channel_snapshot *, chan_snapshot, NULL, ao2_cleanup);
   RAII_VAR(struct ast_channel_snapshot *, target_snapshot, NULL, ao2_cleanup);

   target_name = ast_strdupa(ast_channel_name(target));
   ast_debug(1, "Call pickup on '%s' by '%s'\n", target_name, ast_channel_name(chan));

   /* Mark the target to block any call pickup race. */
   ds_pickup = ast_datastore_alloc(&pickup_active, NULL);
   if (!ds_pickup) {
      ast_log(LOG_WARNING,
         "Unable to create channel datastore on '%s' for call pickup\n", target_name);
      return -1;
   }
   ast_channel_datastore_add(target, ds_pickup);

   ast_party_connected_line_init(&connected_caller);
   ast_party_connected_line_copy(&connected_caller, ast_channel_connected(target));
   ast_channel_unlock(target);/* The pickup race is avoided so we do not need the lock anymore. */
   /* Reset any earlier private connected id representation */
   ast_party_id_reset(&connected_caller.priv);

   connected_caller.source = AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER;
   if (ast_channel_connected_line_sub(NULL, chan, &connected_caller, 0) &&
      ast_channel_connected_line_macro(NULL, chan, &connected_caller, 0, 0)) {
      ast_channel_update_connected_line(chan, &connected_caller, NULL);
   }
   ast_party_connected_line_free(&connected_caller);

   ast_channel_lock(chan);
   chan_name = ast_strdupa(ast_channel_name(chan));
   ast_connected_line_copy_from_caller(&connected_caller, ast_channel_caller(chan));
   ast_channel_unlock(chan);
   connected_caller.source = AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER;

   if (ast_answer(chan)) {
      ast_log(LOG_WARNING, "Unable to answer '%s'\n", chan_name);
      goto pickup_failed;
   }

   if (ast_queue_control(chan, AST_CONTROL_ANSWER)) {
      ast_log(LOG_WARNING, "Unable to queue answer on '%s'\n", chan_name);
      goto pickup_failed;
   }

   ast_channel_queue_connected_line_update(chan, &connected_caller, NULL);

   /* setting the HANGUPCAUSE so the ringing channel knows this call was not a missed call */
   ast_channel_hangupcause_set(chan, AST_CAUSE_ANSWERED_ELSEWHERE);

   ast_channel_lock(chan);
   chan_snapshot = ast_channel_snapshot_create(chan);
   ast_channel_unlock(chan);
   if (!chan_snapshot) {
      goto pickup_failed;
   }

   target_snapshot = ast_channel_snapshot_get_latest(ast_channel_uniqueid(target));
   if (!target_snapshot) {
      goto pickup_failed;
   }

   if (ast_channel_move(target, chan)) {
      ast_log(LOG_WARNING, "Unable to complete call pickup of '%s' with '%s'\n",
         chan_name, target_name);
      goto pickup_failed;
   }

   /* target points to the channel that did the pickup at this point, so use that channel's topic instead of chan */
   send_call_pickup_stasis_message(target, chan_snapshot, target_snapshot);

   res = 0;

pickup_failed:
   ast_channel_lock(target);
   if (!ast_channel_datastore_remove(target, ds_pickup)) {
      ast_datastore_free(ds_pickup);
   }
   ast_party_connected_line_free(&connected_caller);

   return res;
}

ast_pickup_call()

int ast_pickup_call

(

struct ast_channel *

chan

)

Pickup a call.

Parameters

chan	channel that initiated pickup.

Walk list of channels, checking it is not itself, channel is pbx one, check that the callgroup for both channels are the same and the channel is ringing. Answer calling channel, flag channel as answered on queue, masq channels together.

< Potential pickup target

Definition at line 200 of file pickup.c.

References ao2_cleanup, ast_answer(), ast_channel_lock, ast_channel_name(), ast_channel_unlock, ast_channel_unref, ast_debug, ast_do_pickup(), ast_get_chan_features_pickup_config(), ast_log, ast_pickup_find_by_group(), ast_strdupa, ast_stream_and_wait(), ast_strlen_zero, LOG_ERROR, LOG_NOTICE, LOG_WARNING, NULL, pbx_builtin_setvar_helper(), and RAII_VAR.

Referenced by __analog_ss_thread(), analog_ss_thread(), call_pickup_incoming_request(), cb_events(), handle_call_outgoing(), handle_soft_key_event_message(), mgcp_ss(), and sip_pickup_thread().

{
   struct ast_channel *target;/*!< Potential pickup target */
   int res = -1;
   RAII_VAR(struct ast_features_pickup_config *, pickup_cfg, NULL, ao2_cleanup);
   const char *pickup_sound;
   const char *fail_sound;

   ast_debug(1, "Pickup attempt by %s\n", ast_channel_name(chan));
   ast_channel_lock(chan);
   pickup_cfg = ast_get_chan_features_pickup_config(chan);
   if (!pickup_cfg) {
      ast_log(LOG_ERROR, "Unable to retrieve pickup configuration. Unable to play pickup sounds\n");
   }
   pickup_sound = ast_strdupa(pickup_cfg ? pickup_cfg->pickupsound : "");
   fail_sound = ast_strdupa(pickup_cfg ? pickup_cfg->pickupfailsound : "");
   ast_channel_unlock(chan);

   /* The found channel is already locked. */
   target = ast_pickup_find_by_group(chan);
   if (target) {
      ast_log(LOG_NOTICE, "Pickup %s attempt by %s\n", ast_channel_name(target), ast_channel_name(chan));

      res = ast_do_pickup(chan, target);
      ast_channel_unlock(target);
      if (!res) {
         if (!ast_strlen_zero(pickup_sound)) {
            pbx_builtin_setvar_helper(target, "BRIDGE_PLAY_SOUND", pickup_sound);
         }
      } else {
         ast_log(LOG_WARNING, "Pickup %s failed by %s\n", ast_channel_name(target), ast_channel_name(chan));
      }
      target = ast_channel_unref(target);
   }

   if (res < 0) {
      ast_debug(1, "No call pickup possible... for %s\n", ast_channel_name(chan));
      if (!ast_strlen_zero(fail_sound)) {
         ast_answer(chan);
         ast_stream_and_wait(chan, fail_sound, "");
      }
   }

   return res;
}

ast_pickup_find_by_group()

struct ast_channel* ast_pickup_find_by_group

(

struct ast_channel *

chan

)

Find a pickup channel target by group.

Parameters

chan	channel that initiated pickup.

Return values

target	on success. The returned channel is locked and reffed.
NULL	on error.

< Candidate channels found to pickup.

< Potential pickup target

< Potential new older target

Definition at line 133 of file pickup.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_container_alloc_list, ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, ao2_unlink, ast_can_pickup(), ast_channel_callback(), ast_channel_creationtime(), ast_channel_lock, ast_channel_unlock, ast_channel_unref, ast_tvcmp(), find_channel_by_group(), and NULL.

Referenced by ast_pickup_call(), and pickup_by_group().

{
   struct ao2_container *candidates;/*!< Candidate channels found to pickup. */
   struct ast_channel *target;/*!< Potential pickup target */

   candidates = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, 0, NULL, NULL);
   if (!candidates) {
      return NULL;
   }

   /* Find all candidate targets by group. */
   ast_channel_callback(find_channel_by_group, chan, candidates, 0);

   /* Find the oldest pickup target candidate */
   target = NULL;
   for (;;) {
      struct ast_channel *candidate;/*!< Potential new older target */
      struct ao2_iterator iter;

      iter = ao2_iterator_init(candidates, 0);
      while ((candidate = ao2_iterator_next(&iter))) {
         if (!target) {
            /* First target. */
            target = candidate;
            continue;
         }
         if (ast_tvcmp(ast_channel_creationtime(candidate), ast_channel_creationtime(target)) < 0) {
            /* We have a new target. */
            ast_channel_unref(target);
            target = candidate;
            continue;
         }
         ast_channel_unref(candidate);
      }
      ao2_iterator_destroy(&iter);
      if (!target) {
         /* No candidates found. */
         break;
      }

      /* The found channel must be locked and ref'd. */
      ast_channel_lock(target);

      /* Recheck pickup ability */
      if (ast_can_pickup(target)) {
         /* This is the channel to pickup. */
         break;
      }

      /* Someone else picked it up or the call went away. */
      ast_channel_unlock(target);
      ao2_unlink(candidates, target);
      target = ast_channel_unref(target);
   }
   ao2_ref(candidates, -1);

   return target;
}

ast_pickup_init()

int ast_pickup_init

(

void

)

Initialize pickup.

Return values

0	on success
non-zero	on failure

Definition at line 401 of file pickup.c.

References ast_call_pickup_type(), ast_register_cleanup(), pickup_shutdown(), and STASIS_MESSAGE_TYPE_INIT.

Referenced by asterisk_daemon().

{
   STASIS_MESSAGE_TYPE_INIT(ast_call_pickup_type);
   ast_register_cleanup(pickup_shutdown);

   return 0;
}

call_pickup_to_ami()

static struct ast_manager_event_blob * call_pickup_to_ami ( struct stasis_message *  message )

static

Definition at line 246 of file pickup.c.

References ast_assert, ast_free, ast_manager_build_channel_state_string(), ast_manager_build_channel_state_string_prefix(), ast_manager_event_blob_create(), ast_multi_channel_blob_get_channel(), ast_str_buffer(), contents, EVENT_FLAG_CALL, NULL, RAII_VAR, and stasis_message_data().

{
   struct ast_multi_channel_blob *contents = stasis_message_data(message);
   struct ast_channel_snapshot *chan;
   struct ast_channel_snapshot *target;
   struct ast_manager_event_blob *res;

   RAII_VAR(struct ast_str *, channel_str, NULL, ast_free);
   RAII_VAR(struct ast_str *, target_str, NULL, ast_free);

   chan = ast_multi_channel_blob_get_channel(contents, "channel");
   target = ast_multi_channel_blob_get_channel(contents, "target");

   ast_assert(chan != NULL && target != NULL);

   if (!(channel_str = ast_manager_build_channel_state_string(chan))) {
      return NULL;
   }

   if (!(target_str = ast_manager_build_channel_state_string_prefix(target, "Target"))) {
      return NULL;
   }

   res = ast_manager_event_blob_create(EVENT_FLAG_CALL, "Pickup",
      "%s"
      "%s",
      ast_str_buffer(channel_str),
      ast_str_buffer(target_str));

   return res;
}

find_channel_by_group()

static int find_channel_by_group ( void *  obj, void *  arg, void *  data, int  flags  )

static

< Potential pickup target

< Channel wanting to pickup call

< Candidate channels found.

Definition at line 95 of file pickup.c.

References ao2_link, ast_can_pickup(), ast_channel_callgroup(), ast_channel_lock, ast_channel_named_callgroups(), ast_channel_named_pickupgroups(), ast_channel_pickupgroup(), ast_channel_trylock, ast_channel_unlock, and ast_namedgroups_intersect().

Referenced by ast_pickup_find_by_group().

{
   struct ast_channel *target = obj; /*!< Potential pickup target */
   struct ast_channel *chan = arg;   /*!< Channel wanting to pickup call */

   if (chan == target) {
      return 0;
   }

   ast_channel_lock(target);
   if (ast_can_pickup(target)) {
      /* Lock both channels. */
      while (ast_channel_trylock(chan)) {
         ast_channel_unlock(target);
         sched_yield();
         ast_channel_lock(target);
      }

      /*
       * Both callgroup and namedcallgroup pickup variants are
       * matched independently.  Checking for named group match is
       * done last since it's a more expensive operation.
       */
      if ((ast_channel_pickupgroup(chan) & ast_channel_callgroup(target))
         || (ast_namedgroups_intersect(ast_channel_named_pickupgroups(chan),
            ast_channel_named_callgroups(target)))) {
         struct ao2_container *candidates = data;/*!< Candidate channels found. */

         /* This is a candidate to pickup */
         ao2_link(candidates, target);
      }
      ast_channel_unlock(chan);
   }
   ast_channel_unlock(target);

   return 0;
}

pickup_shutdown()

static void pickup_shutdown ( void  )

static

Definition at line 396 of file pickup.c.

References ast_call_pickup_type(), and STASIS_MESSAGE_TYPE_CLEANUP.

Referenced by ast_pickup_init().

{
   STASIS_MESSAGE_TYPE_CLEANUP(ast_call_pickup_type);
}

send_call_pickup_stasis_message()

static int send_call_pickup_stasis_message ( struct ast_channel *  picking_up, struct ast_channel_snapshot *  chan, struct ast_channel_snapshot *  target  )

static

Definition at line 278 of file pickup.c.

References ao2_cleanup, ast_call_pickup_type(), ast_channel_topic(), ast_json_null(), ast_multi_channel_blob_add_channel(), ast_multi_channel_blob_create(), NULL, RAII_VAR, stasis_message_create(), and stasis_publish().

Referenced by ast_do_pickup().

{
   RAII_VAR(struct ast_multi_channel_blob *, pickup_payload, NULL, ao2_cleanup);
   RAII_VAR(struct stasis_message *, msg, NULL, ao2_cleanup);

   if (!ast_call_pickup_type()) {
      return -1;
   }

   if (!(pickup_payload = ast_multi_channel_blob_create(ast_json_null()))) {
      return -1;
   }

   ast_multi_channel_blob_add_channel(pickup_payload, "channel", chan);
   ast_multi_channel_blob_add_channel(pickup_payload, "target", target);

   if (!(msg = stasis_message_create(ast_call_pickup_type(), pickup_payload))) {
      return -1;
   }

   stasis_publish(ast_channel_topic(picking_up), msg);
   return 0;
}

STASIS_MESSAGE_TYPE_DEFN()

STASIS_MESSAGE_TYPE_DEFN	(	ast_call_pickup_type	,
		.	to_ami = call_pickup_to_ami
	)

Variable Documentation

pickup_active

const struct ast_datastore_info pickup_active

static

Initial value:

= {
   .type = "pickup-active",
}

The presence of this datastore on the channel indicates that someone is attemting to pickup or has picked up the channel. The purpose is to prevent a race between two channels attempting to pickup the same channel.

Definition at line 73 of file pickup.c.