Adds support for a core attended transfer function plus adds some hiding of masquerades.

The attended transfer API call can complete the attended transfer in a number of ways
depending on the current bridged states of the channels involved.

The hiding of masquerades is done in some bridging-related functions, such as the manager
Bridge action and the Bridge dialplan application. In addition, call pickup was edited
to "move" a channel rather than masquerade it.

Review: https://reviewboard.asterisk.org/r/2511

(closes issue ASTERISK-21334)
Reported by Matt Jordan

(closes issue Asterisk-21336)
Reported by Matt Jordan



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@389848 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/bridging.h

@@ -225,6 +225,8 @@ enum ast_bridge_action_type {
 	AST_BRIDGE_ACTION_RUN_APP,
 	/*! Bridge channel is to execute a blind transfer. */
 	AST_BRIDGE_ACTION_BLIND_TRANSFER,
+	/*! Bridge channel is to execute an attended transfer */
+	AST_BRIDGE_ACTION_ATTENDED_TRANSFER,
 
 	/*
 	 * Bridge actions put after this comment must never be put onto
@@ -878,6 +880,45 @@ int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
  */
 int ast_bridge_unreal_optimized_out(struct ast_channel *chan, struct ast_channel *peer);
 
+/*!
+ * \brief Tells, if optimization is allowed, how the optimization would be performed
+ */
+enum ast_bridge_optimization {
+	/*! Optimization would swap peer into the chan_bridge */
+	AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
+	/*! Optimization would swap chan into the peer_bridge */
+	AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
+	/*! Optimization would merge peer_bridge into chan_bridge */
+	AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
+	/*! Optimization would merge chan_bridge into peer_bridge */
+	AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
+	/*! Optimization is not permitted on one or both bridges */
+	AST_BRIDGE_OPTIMIZE_PROHIBITED,
+};
+
+/*!
+ * \brief Determine if bridges allow for optimization to occur betweem them
+ * \since 12.0.0
+ *
+ * \param chan_bridge First bridge being tested
+ * \param peer_bridge Second bridge being tested
+ *
+ * This determines if two bridges allow for unreal channel optimization
+ * to occur between them. The function does not require for unreal channels
+ * to already be in the bridges when called.
+ *
+ * \note It is assumed that both bridges are locked prior to calling this function
+ *
+ * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
+ * that an optimization attempt will succeed. However, a return of
+ * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
+ * never succeed.
+ *
+ * \returns Optimization allowability for the bridges
+ */
+enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
+		struct ast_bridge *peer_bridge);
+
 /*!
  * \brief Try locking the bridge_channel.
  *
@@ -1288,7 +1329,26 @@ enum ast_transfer_result {
 	AST_BRIDGE_TRANSFER_FAIL,
 };
 
-typedef void (*transfer_channel_cb)(struct ast_channel *chan, void *user_data);
+enum ast_transfer_type {
+	/*! Transfer of a single party */
+	AST_BRIDGE_TRANSFER_SINGLE_PARTY,
+	/*! Transfer of multiple parties */
+	AST_BRIDGE_TRANSFER_MULTI_PARTY,
+};
+
+/*!
+ * \brief Callback function type called during blind transfers
+ *
+ * A caller of ast_bridge_transfer_blind() may wish to set data on
+ * the channel that ends up running dialplan. For instance, it may
+ * be useful to set channel variables on the channel.
+ *
+ * \param chan The involved channel
+ * \param user_data User-provided data needed in the callback
+ * \param transfer_type The type of transfer being completed
+ */
+typedef void (*transfer_channel_cb)(struct ast_channel *chan, void *user_data,
+		enum ast_transfer_type transfer_type);
 
 /*!
  * \brief Blind transfer target to the extension and context provided
@@ -1326,20 +1386,15 @@ enum ast_transfer_result ast_bridge_transfer_blind(struct ast_channel *transfere
  * the transfer). The second is the channel that is bridged to the transfer
  * target (or if unbridged, the 'second' call of the transfer).
  *
- * Like with a blind transfer, a frame hook can be provided to monitor the
- * resulting call after the transfer completes. If the transfer fails, the
- * hook will not be attached to any call.
- *
  * \note Absolutely _NO_ channel locks should be held before
  * calling this function.
  *
  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
- * \param hook A frame hook to attach to the resultant call
  * \return The success or failure of the attended transfer
  */
 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
-		struct ast_channel *to_transfer_target, struct ast_framehook *hook);
+		struct ast_channel *to_transfer_target);
 /*!
  * \brief Set channel to goto specific location after the bridge.
  * \since 12.0.0
@@ -1511,6 +1566,16 @@ void ast_after_bridge_callback_discard(struct ast_channel *chan, enum ast_after_
  */
 int ast_after_bridge_callback_set(struct ast_channel *chan, ast_after_bridge_cb callback, ast_after_bridge_cb_failed failed, void *data);
 
+/*!
+ * \brief Get a string representation of an after bridge callback reason
+ * \since 12.0.0
+ *
+ * \param reason The reason to interpret to a string
+ * \retval NULL Unrecognized reason
+ * \retval non-NULL String representation of reason
+ */
+const char *ast_after_bridge_cb_reason_string(enum ast_after_bridge_cb_reason reason);
+
 /*!
  * \brief Get a container of all channels in the bridge
  * \since 12.0.0

include/asterisk/channel.h

@@ -4229,4 +4229,55 @@ struct ast_channel *ast_channel_bridge_peer(struct ast_channel *chan);
  */
 struct ast_bridge_channel *ast_channel_get_bridge_channel(struct ast_channel *chan);
 
+/*!
+ * \since 12
+ * \brief Gain control of a channel in the system
+ *
+ * The intention of this function is to take a channel that currently
+ * is running in one thread and gain control of it in the current thread.
+ * This can be used to redirect a channel to a different place in the dialplan,
+ * for instance.
+ *
+ * \note This function is NOT intended to be used on bridged channels. If you
+ * need to control a bridged channel, you can set a callback to be called
+ * once the channel exits the bridge, and run your controlling logic in that
+ * callback
+ *
+ * XXX Put name of callback-setting function in above paragraph once it is written
+ *
+ * \note When this function returns successfully, the yankee channel is in a state where
+ * it cannot be used any further. Always use the returned channel instead.
+ *
+ * \note absolutely _NO_ channel locks should be held before calling this function.
+ *
+ * \param yankee The channel to gain control of
+ * \retval NULL Could not gain control of the channel
+ * \retval non-NULL The channel
+ */
+struct ast_channel *ast_channel_yank(struct ast_channel *yankee);
+
+/*!
+ * \since 12
+ * \brief Move a channel from its current location to a new location
+ *
+ * The intention of this function is to have the destination channel
+ * take on the identity of the source channel.
+ *
+ * \note This function is NOT intended to be used on bridged channels. If you
+ * wish to move an unbridged channel into the place of a bridged channel, then
+ * use ast_bridge_join() or ast_bridge_impart(). If you wish to move a bridged
+ * channel into the place of another bridged channel, then use ast_bridge_move().
+ *
+ * \note When this function returns succesfully, the source channel is in a
+ * state where its continued use is unreliable.
+ *
+ * \note absolutely _NO_ channel locks should be held before calling this function.
+ *
+ * \param dest The place to move the source channel
+ * \param source The channel to move
+ * \retval 0 Success
+ * \retval non-zero Failure
+ */
+int ast_channel_move(struct ast_channel *dest, struct ast_channel *source);
+
 #endif /* _ASTERISK_CHANNEL_H */