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

Mon Dec 21 12:46:23 CST 2009

Author: mmichelson
Date: Mon Dec 21 12:46:22 2009
New Revision: 235903

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=235903
Log:
Add doxygen for core functions needed by ISDN PTMP monitors.


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=235903&r1=235902&r2=235903
==============================================================================

--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Mon Dec 21 12:46:22 2009
@@ -1062,16 +1062,87 @@
 
 /* END STATE CHANGE API */
 
-/* BEGIN STATUS REQUEST/RESPONSE API */
-
+/* The following are all functions which are required due to the unique
+ * case where Asterisk is is acting as the NT side of an ISDN PTMP
+ * connection to the caller and as the TE side of an ISDN PTMP connection
+ * to the callee. In such a case, there are several times where the
+ * PTMP monitor needs information from the agent in order to formulate
+ * the appropriate messages to send.
+ */
+
+/*!
+ * \brief Request the status of a caller or callers.
+ *
+ * When an ISDN PTMP monitor senses that the callee has become
+ * available, it needs to know the current status of the caller
+ * in order to determine the appropriate response to send to
+ * the caller. In order to do this, the monitor calls this function.
+ * Responses will arrive asynchronously.
+ * \param core_id The core ID of the CC transaction
+ * \retval 0 Successfully requested status
+ * \retval -1 Failed to request status
+ */
 int ast_cc_monitor_status_request(int core_id);
 
+/*!
+ * \brief Response with a caller's current status
+ *
+ * When an ISDN PTMP monitor requests the caller's status, the
+ * agent must respond to the request using this function. For
+ * simplicity it is recommended that the devstate parameter
+ * be one of AST_DEVICE_INUSE or AST_DEVICE_NOT_INUSE.
+ *
+ * \param core_id The core ID of the CC transaction
+ * \param devstate The current state of the caller to which the agent pertains
+ * \retval 0 Successfully responded with our status
+ * \retval -1 Failed to respond with our status
+ */
 int ast_cc_agent_status_response(int core_id, enum ast_device_state devstate);
 
-/* END STATUS REQUEST/RESPONSE API */
-
+/*!
+ * \brief Alert a caller to stop ringing
+ *
+ * When an ISDN PTMP monitor becomes available, it is assumed
+ * that the agent will then cause the caller's phone to ring. In
+ * some cases, this is literally what happens. In other cases, it may
+ * be that the caller gets a visible indication on his phone that he
+ * may attempt to recall the callee. If multiple callers are recalled
+ * (since it may be possible to have a group of callers configured as
+ * a single party A), and one of those callers picks up his phone, then
+ * the ISDN PTMP monitor will alert the other callers to stop ringing.
+ * The agent's stop_ringing callback will be called, and it is up to the
+ * agent's driver to send an appropriate message to make his caller
+ * stop ringing.
+ *
+ * \param core_id The core ID of the CC transaction
+ * \retval 0 Successfully requested for the phone to stop ringing
+ * \retval -1 Could not request for the phone to stop ringing
+ */
 int ast_cc_monitor_stop_ringing(int core_id);
 
+/*!
+ * \brief Alert a caller that though the callee has become free, the caller
+ * himself is not and may not call back.
+ * 
+ * When an ISDN PTMP monitor senses that his monitored party has become
+ * available, he will request the status of the called party. If he determines
+ * that the caller is currently not available, then he will call this function
+ * so that an appropriate message is sent to the caller.
+ *
+ * Yes, you just read that correctly. The callee asks the caller what his
+ * current status is, and if the caller is currently unavailable, the monitor
+ * must send him a message anyway. WTF?
+ *
+ * This function results in the agent's party_b_free callback being called.
+ * It is most likely that you will not need to actually implement the
+ * party_b_free callback in an agent because it is not likely that you will
+ * need to or even want to send a caller a message indicating the callee's
+ * status if the caller himself is not also free.
+ *
+ * \param core_id The core ID of the CC transaction
+ * \retval 0 Successfully alerted the core that party B is free
+ * \retval -1 Could not alert the core that party B is free
+ */
 int ast_cc_monitor_party_b_free(int core_id);
 
 /* BEGIN API FOR USE WITH/BY MONITORS */


