ARI: Bridge Playback, Bridge Record

Adds a new channel driver for creating channels for specific purposes
in bridges, primarily to act as either recorders or announcers. Adds
ARI commands for playing announcements to ever participant in a bridge
as well as for recording a bridge. This patch also includes some
documentation/reponse fixes to related ARI models such as playback
controls.

(closes issue ASTERISK-21592)
Reported by: Matt Jordan

(closes issue ASTERISK-21593)
Reported by: Matt Jordan

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


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

4 files changed, 60 insertions, 2 deletions

diff --git a/include/asterisk/core_unreal.h b/include/asterisk/core_unreal.h
index a6e98895a..751c5d455 100644
--- a/include/asterisk/core_unreal.h
+++ b/include/asterisk/core_unreal.h
@@ -31,6 +31,7 @@
 
 #include "asterisk/astobj2.h"
 #include "asterisk/channel.h"
+#include "asterisk/bridging.h"
 #include "asterisk/abstract_jb.h"
 
 #if defined(__cplusplus) || defined(c_plusplus)
@@ -208,6 +209,20 @@ struct ast_channel *ast_unreal_new_channels(struct ast_unreal_pvt *p,
  */
 void ast_unreal_call_setup(struct ast_channel *semi1, struct ast_channel *semi2);
 
+/*!
+ * \brief Push the semi2 unreal channel into a bridge from either member of the unreal pair
+ * \since 12.0.0
+ *
+ * \param ast A member of the unreal channel being pushed
+ * \param bridge Which bridge we want to push the channel to
+ *
+ * \retval 0 if the channel is successfully imparted onto the bridge
+ * \retval -1 on failure
+ *
+ * \note This is equivalent to ast_call() on unreal based channel drivers that are designed to use it instead.
+ */
+int ast_unreal_channel_push_to_bridge(struct ast_channel *ast, struct ast_bridge *bridge);
+
 /* ------------------------------------------------------------------- */
 
 #if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/logger.h b/include/asterisk/logger.h
index 09d2b4c7a..bbad84bb3 100644
--- a/include/asterisk/logger.h
+++ b/include/asterisk/logger.h
@@ -281,7 +281,16 @@ struct ast_callid *ast_read_threadstorage_callid(void);
  *
  * \retval NULL always
  */
-#define ast_callid_unref(c) ({ ao2_ref(c, -1); (NULL); })
+#define ast_callid_unref(c) ({ ao2_ref(c, -1); (struct ast_callid *) (NULL); })
+
+/*!
+ * \brief Cleanup a callid reference (NULL safe ao2 unreference)
+ *
+ * \param c the ast_callid
+ *
+ * \retval NULL always
+ */
+#define ast_callid_cleanup(c) ({ ao2_cleanup(c); (struct ast_callid *) (NULL); })
 
 /*!
  * \brief Sets what is stored in the thread storage to the given
diff --git a/include/asterisk/stasis_app.h b/include/asterisk/stasis_app.h
index 731133674..244d9d1e5 100644
--- a/include/asterisk/stasis_app.h
+++ b/include/asterisk/stasis_app.h
@@ -127,6 +127,29 @@ struct stasis_app_control *stasis_app_control_find_by_channel_id(
 	const char *channel_id);
 
 /*!
+ * \brief Creates a control handler for a channel that isn't in a stasis app.
+ * \since 12.0.0
+ *
+ * \param chan Channel to create controller handle for
+ *
+ * \return NULL on failure to create the handle
+ * \return Pointer to \c res_stasis handler.
+ */
+struct stasis_app_control *stasis_app_control_create(
+	struct ast_channel *chan);
+
+/*!
+ * \brief Act on a stasis app control queue until it is empty
+ * \since 12.0.0
+ *
+ * \param chan Channel to handle
+ * \param control Control object to execute
+ */
+void stasis_app_control_execute_until_exhausted(
+	struct ast_channel *chan,
+	struct stasis_app_control *control);
+
+/*!
  * \brief Returns the uniqueid of the channel associated with this control
  *
  * \param control Control object.
diff --git a/include/asterisk/stasis_app_playback.h b/include/asterisk/stasis_app_playback.h
index 59c2aab49..3587871a9 100644
--- a/include/asterisk/stasis_app_playback.h
+++ b/include/asterisk/stasis_app_playback.h
@@ -69,6 +69,13 @@ enum stasis_app_playback_media_operation {
 	STASIS_PLAYBACK_MEDIA_OP_MAX,
 };
 
+enum stasis_app_playback_target_type {
+	/*! The target is a channel */
+	STASIS_PLAYBACK_TARGET_CHANNEL = 0,
+	/*! The target is a bridge */
+	STASIS_PLAYBACK_TARGET_BRIDGE,
+};
+
 /*!
  * \brief Play a file to the control's channel.
  *
@@ -79,6 +86,8 @@ enum stasis_app_playback_media_operation {
  * \param control Control for \c res_stasis.
  * \param file Base filename for the file to play.
  * \param language Selects the file based on language.
+ * \param target_id ID of the target bridge or channel.
+ * \param target_type What the target type is
  * \param skipms Number of milliseconds to skip for forward/reverse operations.
  * \param offsetms Number of milliseconds to skip before playing.
  * \return Playback control object.
@@ -86,7 +95,9 @@ enum stasis_app_playback_media_operation {
  */
 struct stasis_app_playback *stasis_app_control_play_uri(
 	struct stasis_app_control *control, const char *file,
-	const char *language, int skipms, long offsetms);
+	const char *language, const char *target_id,
+	enum stasis_app_playback_target_type target_type,
+	int skipms, long offsetms);
 
 /*!
  * \brief Gets the current state of a playback operation.