[asterisk-commits] mmichelson: branch mmichelson/atxfer_features r393283 - /team/mmichelson/atxf...

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Sat Jun 29 15:04:05 2013
New Revision: 393283

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=393283
Log:
Add a bit of doxygen to some of the easier-to-explain structures.

Modified:
    team/mmichelson/atxfer_features/main/bridging_basic.c

Modified: team/mmichelson/atxfer_features/main/bridging_basic.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/atxfer_features/main/bridging_basic.c?view=diff&rev=393283&r1=393282&r2=393283
==============================================================================
--- team/mmichelson/atxfer_features/main/bridging_basic.c (original)
+++ team/mmichelson/atxfer_features/main/bridging_basic.c Sat Jun 29 15:04:05 2013
@@ -365,21 +365,41 @@
 	TRANSFER_FAIL,
 };
 
+/*!
+ * \brief Stimuli that can cause transfer state changes
+ */
 enum attended_transfer_stimulus {
+	/*! No stimulus. This literally can never happen. */
 	STIMULUS_NONE,
+	/*! All of the transferee channels have been hung up. */
 	STIMULUS_TRANSFEREE_HANGUP,
+	/*! The transferer has hung up. */
 	STIMULUS_TRANSFERER_HANGUP,
+	/*! The transfer target channel has hung up. */
 	STIMULUS_TRANSFER_TARGET_HANGUP,
+	/*! The transfer target channel has answered. */
 	STIMULUS_TRANSFER_TARGET_ANSWER,
+	/*! The recall target channel has hung up. */
 	STIMULUS_RECALL_TARGET_HANGUP,
+	/*! The recall target channel has answered. */
 	STIMULUS_RECALL_TARGET_ANSWER,
+	/*! The current state's timer has expired. */
 	STIMULUS_TIMEOUT,
+	/*! The transferer pressed the abort DTMF sequence. */
 	STIMULUS_DTMF_ATXFER_ABORT,
+	/*! The transferer pressed the complete DTMF sequence. */
 	STIMULUS_DTMF_ATXFER_COMPLETE,
+	/*! The transferer pressed the three-way DTMF sequence. */
 	STIMULUS_DTMF_ATXFER_THREEWAY,
+	/*! The transferer pressed the swap DTMF sequence. */
 	STIMULUS_DTMF_ATXFER_SWAP,
 };
 
+/*!
+ * \brief String representations of the various stimuli
+ *
+ * Used for debugging purposes
+ */
 const char *stimulus_strs[] = {
 	[STIMULUS_NONE] = "None",
 	[STIMULUS_TRANSFEREE_HANGUP] = "Transferee Hangup",
@@ -400,29 +420,61 @@
 	AST_LIST_ENTRY(stimulus_list) next;
 };
 
+/*!
+ * \brief Collection of data related to an attended transfer attempt
+ */
 struct attended_transfer_properties {
+	/*! This lock protects the stimulus queue and is used in tandem with cond */
 	ast_mutex_t lock;
+	/*! Condition used to synchronize when stimuli are reported to the monitor thread */
 	ast_cond_t cond;
+	/*! The bridge where the transferee resides. This bridge is also the bridge that
+	 * survives a successful attended transfer.
+	 */
 	struct ast_bridge *transferee_bridge;
+	/*! The bridge used to place an outbound call to the transfer target. This
+	 * bridge is merged with the transferee_bridge on a successful transfer.
+	 */
 	struct ast_bridge *target_bridge;
+	/*! The party that performs the attended transfer. */
 	struct ast_channel *transferer;
+	/*! The local channel dialed to reach the transfer target. */
 	struct ast_channel *transfer_target;
+	/*! The party that is currently being recalled. Depending on
+	 * the current state, this may be either the party that originally
+	 * was the transferer or the original transfer target
+	 */
 	struct ast_channel *recall_target;
+	/*! The absolute starting time for running timers */
 	struct timeval start;
-	AST_LIST_HEAD(,stimulus_list) stimulus_queue;
+	AST_LIST_HEAD_NOLOCK(,stimulus_list) stimulus_queue;
+	/*! The current state of the attended transfer */
 	enum attended_transfer_state state;
+	/*! The current superstate of the attended transfer */
 	enum attended_transfer_superstate superstate;
+	/*! Configured atxferdropcall from features.conf */
 	int atxferdropcall;
+	/*! Configured atxfercallbackretries from features.conf */
 	int atxfercallbackretries;
+	/*! Configured atxferloopdelay from features.conf */
 	int atxferloopdelay;
+	/*! Configured atxfernoanswertimeout from features.conf */
 	int atxfernoanswertimeout;
+	/*! Count of the number of times that recalls have been attempted */
 	int retry_attempts;
+	/*! Framehook ID for outbounc call to transfer target or recall target */
 	int target_framehook_id;
+	/*! Extension of transfer target */
 	char exten[AST_MAX_EXTENSION];
+	/*! Context of transfer target */
 	char context[AST_MAX_CONTEXT];
+	/*! Sound to play on failure */
 	char failsound[PATH_MAX];
+	/*! The channel technology of the transferer channel */
 	char transferer_type[AST_CHANNEL_NAME];
+	/*! The transferer channel address */
 	char transferer_addr[AST_CHANNEL_NAME];
+	/*! Dial structure used when recalling transferer channel */
 	struct ast_dial *dial;
 };