pickup.h File Reference

Call Pickup API. More...

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

Go to the source code of this file.

Functions
struct stasis_message_type *	ast_call_pickup_type (void)
	accessor for call pickup message type More...
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...

Detailed Description

Call Pickup API.

Includes code and algorithms from the Zapata library.

Definition in file pickup.h.

Function Documentation

ast_call_pickup_type()

struct stasis_message_type* ast_call_pickup_type

(

void

)

accessor for call pickup message type

Since

12.0.0

Return values

pointer	to the stasis message type
NULL	if not initialized

Referenced by ast_pickup_init(), create_routes(), pickup_shutdown(), and send_call_pickup_stasis_message().

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	The channel that initiated the pickup

Return values

0	on success
-1	on failure

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