ari/pjsip: Make it possible to control transfers through ARI

Introduce a ChannelTransfer event and the ability to notify progress to
ARI. Implement emitting this event from the PJSIP channel instead of
handling the transfer in Asterisk when configured.

Introduce a dialplan function to the PJSIP channel to switch between the
"core" and "ari-only" behavior.

UserNote: Call transfers on the PJSIP channel can now be controlled by
ARI. This can be enabled by using the PJSIP_TRANSFER_HANDLING(ari-only)
dialplan function.

include/asterisk/frame.h

@@ -408,6 +408,9 @@ struct ast_control_t38_parameters {
 enum ast_control_transfer {
 	AST_TRANSFER_SUCCESS = 0, /*!< Transfer request on the channel worked */
 	AST_TRANSFER_FAILED,      /*!< Transfer request on the channel failed */
+	AST_TRANSFER_PROGRESS,    /*!< Transfer request on the channel is in progress */
+	AST_TRANSFER_UNAVAILABLE, /*!< Transfer request on the channel is unavailable */
+	AST_TRANSFER_INVALID,     /*!< Invalid state for none of the above. */
 };
 
 struct ast_control_pvt_cause_code {

include/asterisk/refer.h

@@ -37,6 +37,11 @@
 extern "C" {
 #endif
 
+#include "asterisk/vector.h"
+#include "asterisk/frame.h"
+
+struct ast_channel;
+
 /*!
  * \brief A refer structure.
  *
@@ -73,6 +78,13 @@ struct ast_refer_tech {
 	int (* const refer_send)(const struct ast_refer *refer);
 };
 
+struct ast_refer_param {
+	const char *param_name;
+	const char *param_value;
+};
+
+AST_VECTOR(ast_refer_params, struct ast_refer_param);
+
 /*!
  * \brief Register a refer technology
  *
@@ -314,6 +326,20 @@ void ast_refer_var_iterator_destroy(struct ast_refer_var_iterator *iter);
  */
 void ast_refer_var_unref_current(struct ast_refer_var_iterator *iter);
 
+/*!
+ * \brief Notify a transfer request.
+ * \param originating_chan The channel that received the transfer request
+ * \param referred_by Information about the requesting identity
+ * \param exten The extension for blind transfers
+ * \param protocol_id Technology specific replace indication
+ * \param dest The identified replace target for attended requests.
+ * \param params List of protocol specific params.
+ * \param state The state of the transfer
+ */
+int ast_refer_notify_transfer_request(struct ast_channel *originating_chan, const char *referred_by, const char *exten,
+				      const char *protocol_id, struct ast_channel *dest, struct ast_refer_params *params,
+				      enum ast_control_transfer state);
+
 /*!
  *  @}
  */

include/asterisk/res_pjsip_session.h

@@ -217,6 +217,8 @@ struct ast_sip_session {
 	unsigned int defer_terminate:1;
 	/*! Termination requested while termination deferred */
 	unsigned int terminate_while_deferred:1;
+	/*! Transferhandling ari */
+	unsigned int transferhandling_ari:1;
 	/*! Deferred incoming re-invite */
 	pjsip_rx_data *deferred_reinvite;
 	/*! Current T.38 state */

include/asterisk/stasis_channels.h

@@ -20,6 +20,7 @@
 #ifndef STASIS_CHANNELS_H_
 #define STASIS_CHANNELS_H_
 
+#include "asterisk/refer.h"
 #include "asterisk/stringfields.h"
 #include "asterisk/stasis.h"
 #include "asterisk/channel.h"
@@ -673,6 +674,14 @@ struct stasis_message_type *ast_channel_talking_start(void);
  */
 struct stasis_message_type *ast_channel_talking_stop(void);
 
+/*
+ * \since 23
+ * \brief Message type for a attended or blind transfer request
+ *
+ * \return A stasis message type
+ */
+struct stasis_message_type *ast_channel_transfer_request_type(void);
+
 /*!
  * \since 12
  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
@@ -766,6 +775,44 @@ int ast_channel_snapshot_connected_line_equal(
 	const struct ast_channel_snapshot *old_snapshot,
 	const struct ast_channel_snapshot *new_snapshot);
 
+
+/*!
+ * \since 23
+ * \brief Message published during an "ARI" transfer
+ */
+struct ast_ari_transfer_message {
+	/*! The channel receiving the transfer request */
+	struct ast_channel_snapshot *source;
+	/*! The bridge associated with the source channel */
+	struct ast_bridge_snapshot *source_bridge;
+	/*! The peer channel */
+	struct ast_channel_snapshot *source_peer;
+	/*! Referer identity */
+	char *referred_by;
+
+
+	/*! Destination extension */
+	char destination[AST_MAX_EXTENSION];
+	/*! Information for attended transfers */
+	char *protocol_id;
+	/*! The identified destination channel. */
+	struct ast_channel_snapshot *dest;
+	/*! The bridge associated with the channel. */
+	struct ast_bridge_snapshot *dest_bridge;
+	/*! The peer of the destination channel. */
+	struct ast_channel_snapshot *dest_peer;
+	/*! An array of protocol specific params, e.g. from/to information */
+	struct ast_refer_params *refer_params;
+	/*! The current state of the transfer. */
+	enum ast_control_transfer state;
+};
+
+
+struct ast_ari_transfer_message *ast_ari_transfer_message_create(struct ast_channel *originating_chan,
+								 const char *referred_by, const char *exten,
+								 const char *protocol_id, struct ast_channel *dest,
+								 struct ast_refer_params *params, enum ast_control_transfer);
+
 /*!
  * \brief Initialize the stasis channel topic and message types
  * \retval 0 on success