[asterisk-commits] mmichelson: branch mmichelson/transfer_stasis r391587 - /team/mmichelson/tran...

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Wed Jun 12 17:52:09 2013
New Revision: 391587

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=391587
Log:
Add documentation for publication information on attended transfers.


Modified:
    team/mmichelson/transfer_stasis/main/bridging.c

Modified: team/mmichelson/transfer_stasis/main/bridging.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/transfer_stasis/main/bridging.c?view=diff&rev=391587&r1=391586&r2=391587
==============================================================================
--- team/mmichelson/transfer_stasis/main/bridging.c (original)
+++ team/mmichelson/transfer_stasis/main/bridging.c Wed Jun 12 17:52:09 2013
@@ -5602,8 +5602,14 @@
 	return AST_BRIDGE_TRANSFER_SUCCESS;
 }
 
+/*!
+ * \internal
+ * \brief Base data to publish for stasis attended transfer messages
+ */
 struct stasis_attended_transfer_publish_data {
+	/* The bridge between the transferer and transferee, and the transferer channel in this bridge */
 	struct ast_bridge_channel_pair to_transferee;
+	/* The bridge between the transferer and transfer target, and the transferer channel in this bridge */
 	struct ast_bridge_channel_pair to_transfer_target;
 };
 
@@ -5615,6 +5621,16 @@
 	ao2_cleanup(publication->to_transfer_target.bridge);
 }
 
+/*!
+ * \internal
+ * \brief Set up base data for an attended transfer stasis publication
+ *
+ * \param to_transferee The original transferer channel, which may be bridged to a transferee
+ * \param to_transferee_bridge The bridge that to_transferee is in.
+ * \param to_transfer_target The second transferer channel, which may be bridged to a transfer target
+ * \param to_target_bridge The bridge that to_transfer_target_is in.
+ * \param[out] publication A structure to hold the other parameters
+ */
 static void stasis_publish_data_init(struct ast_channel *to_transferee,
 		struct ast_bridge *to_transferee_bridge, struct ast_channel *to_transfer_target,
 		struct ast_bridge *to_target_bridge,
@@ -5634,6 +5650,13 @@
 	}
 }
 
+/*
+ * \internal
+ * \brief Publish a stasis attended transfer resulting in a bridge merge
+ *
+ * \param publication Base data about the attended transfer
+ * \param final_bridge The surviving bridge of the attended transfer
+ */
 static void publish_attended_transfer_bridge_merge(struct stasis_attended_transfer_publish_data *publication,
 		struct ast_bridge *final_bridge)
 {
@@ -5641,6 +5664,13 @@
 			&publication->to_transferee, &publication->to_transfer_target, final_bridge);
 }
 
+/*
+ * \internal
+ * \brief Publish a stasis attended transfer to an application
+ *
+ * \param publication Base data about the attended transfer
+ * \param app The app that is running at the conclusion of the transfer
+ */
 static void publish_attended_transfer_app(struct stasis_attended_transfer_publish_data *publication,
 		const char *app)
 {
@@ -5648,6 +5678,16 @@
 			&publication->to_transferee, &publication->to_transfer_target, app);
 }
 
+/*
+ * \internal
+ * \brief Publish a stasis attended transfer showing a link between bridges
+ *
+ * \param publication Base data about the attended transfer
+ * \param local_channel1 Local channel in the original bridge
+ * \param local_bridge1 Bridge that local_channel1 is in
+ * \param local_channel2 Local channel in the second bridge
+ * \param local_bridge2 Bridge taht local_channel2 is in
+ */
 static void publish_attended_transfer_link(struct stasis_attended_transfer_publish_data *publication,
 		struct ast_channel *local_channel1, struct ast_bridge *local_bridge1,
 		struct ast_channel *local_channel2, struct ast_bridge *local_bridge2)
@@ -5666,8 +5706,15 @@
 			&publication->to_transferee, &publication->to_transfer_target, locals);
 }
 
-static void publish_attended_transfer_fail(enum ast_transfer_result result,
-		struct stasis_attended_transfer_publish_data *publication)
+/*
+ * \internal
+ * \brief Publish a stasis attended transfer failure
+ *
+ * \param publication Base data about the attended transfer
+ * \param result The transfer result
+ */
+static void publish_attended_transfer_fail(struct stasis_attended_transfer_publish_data *publication,
+		enum ast_transfer_result result)
 {
 	ast_bridge_publish_attended_transfer_fail(1, result, &publication->to_transferee,
 			&publication->to_transfer_target);
@@ -5691,6 +5738,7 @@
  * \param chan2 Other transferer channel. May or may not be bridged.
  * \param bridge1 Bridge that chan1 is in. Guaranteed to be non-NULL.
  * \param bridge2 Bridge that chan2 is in. If NULL, then chan2 is not bridged.
+ * \param publication Data to publish for a stasis attended transfer message.
  * \retval AST_BRIDGE_TRANSFER_FAIL Internal error occurred
  * \retval AST_BRIDGE_TRANSFER_SUCCESS Succesfully transferred the bridge
  */
@@ -6093,6 +6141,7 @@
  * \param to_target_bridge_channel to_transfer_target's bridge_channel
  * \param to_transferee_bridge The bridge between to_transferee and the transferee
  * \param to_target_bridge The bridge between to_transfer_target and the transfer_target
+ * \param publication Data to publish for a stasis attended transfer message
  * \return The success or failure of the attended transfer
  */
 static enum ast_transfer_result two_bridge_attended_transfer(struct ast_channel *to_transferee,
@@ -6306,7 +6355,7 @@
 	 * All failure paths have deferred publishing a stasis message until this point
 	 */
 	if (res != AST_BRIDGE_TRANSFER_SUCCESS) {
-		publish_attended_transfer_fail(res, &publication);
+		publish_attended_transfer_fail(&publication, res);
 	}
 	stasis_publish_data_cleanup(&publication);
 	return res;