[asterisk-commits] mmichelson: branch group/CCSS r227473 - /team/group/CCSS/include/asterisk/ccss.h

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Tue Nov  3 16:21:03 2009
New Revision: 227473

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=227473
Log:
Remove mentions of state machine states from agent callback doxygen.


Modified:
    team/group/CCSS/include/asterisk/ccss.h

Modified: team/group/CCSS/include/asterisk/ccss.h
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/include/asterisk/ccss.h?view=diff&rev=227473&r1=227472&r2=227473
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Tue Nov  3 16:21:03 2009
@@ -755,7 +755,9 @@
 	 * is initialized. Agents should allocate
 	 * any private data necessary for the
 	 * call and assign it to the private_data
-	 * on the agent.
+	 * on the agent. Additionally, if any ast_cc_agent_flags
+	 * are pertinent to the specific agent type, they should
+	 * be set in this function as well.
 	 */
 	int (*init)(struct ast_cc_agent *agent, struct ast_channel *chan);
 	/*!
@@ -776,35 +778,34 @@
 	/*!
 	 * \brief Start the offer timer
 	 *
-	 * The core will call this when the
-	 * CC_CALLER_OFFERED state is entered.
-	 * The agent needs to start its configured
-	 * offer timer. Preferably this will be done
-	 * in the same scheduler context as other
-	 * operations within the realm of the
-	 * particular agent.
+	 * This is called by the core when the caller hangs up after
+	 * a call for which CC may be requested. The agent should
+	 * begin the timer as configured.
+	 *
+	 * The primary reason why this functionality is left to
+	 * the specific agent implementations is due to the differing
+	 * use of schedulers throughout the code. Some channel drivers
+	 * may already have a scheduler context they wish to use, and
+	 * amongst those, some may use the ast_sched API while others
+	 * may use the ast_sched_thread API, which are incompatible.
 	 */
 	int (*start_offer_timer)(struct ast_cc_agent *agent);
 	/*!
 	 * \brief Stop the offer timer
 	 *
-	 * The core will call this when the CC_CALLER_REQUESTED
-	 * state has been reached. The duty of the agent here
-	 * is to stop the configured offer timer.
-	 *
-	 * This callback is also called from the CC_COMPLETE and
-	 * CC_FAILED states, so it is important that this callback
-	 * accounts for the fact that it may be called even if there
-	 * is no offer timer running on the agent.
+	 * This callback is called by the CC core when the caller
+	 * has requested CC.
 	 */
 	int (*stop_offer_timer)(struct ast_cc_agent *agent);
 	/*!
 	 * \brief Acknowledge CC request callback.
 	 *
-	 * The core will call this callback when
-	 * the CC_ACTIVE state is entered. Agents
-	 * should send whatever message is necessary
-	 * to acknowledge a pending CC request.
+	 * When the core receives knowledge that a called
+	 * party has accepted a CC request, it will call
+	 * this callback.
+	 *
+	 * The duty of this is to accept a CC request from
+	 * the caller by acknowledging receipt of that request.
 	 */
 	void (*ack)(struct ast_cc_agent *agent);
 	/*!
@@ -828,24 +829,23 @@
 	 */
 	int (*start_monitoring)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Initiate the recall to the agent's device
-	 *
-	 * The core will call this callback when the
-	 * CC_RECALLING state is reached. The agent should
-	 * take whatever action is necessary in order to
-	 * make his device initiate a CC recall.
+	 * \brief Alert the caller that it is time to try recalling.
+	 *
+	 * The core will call this function when it receives notice
+	 * that a monitored party has become available.
+	 *
+	 * The agent's job is to send a message to the caller to
+	 * notify it of such a change. If the agent is able to
+	 * discern that the caller is currently unavailable, then
+	 * the agent should react by calling the ast_cc_caller_unavailable
+	 * function.
 	 */
 	int (*callee_available)(struct ast_cc_agent *agent);
 	/*!
 	 * \brief Destroy private data on the agent
 	 *
-	 * The core will call this callback when the
-	 * CC_COMPLETE or CC_FAILED state is reached.
-	 *
-	 * XXX A SIP agent will not actually fully destroy
-	 * its private data when this is called. It actually
-	 * will wait for the upstream element to cancel
-	 * its CCSS subscription.
+	 * The core will call this function upon completion
+	 * or failure of CC. 
 	 */
 	void (*destructor)(struct ast_cc_agent *agent);
 };