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

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Wed Sep 30 10:14:36 2009
New Revision: 221092

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=221092
Log:
Doxygenify the monitor callbacks.


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=221092&r1=221091&r2=221092
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Wed Sep 30 10:14:36 2009
@@ -559,17 +559,52 @@
 };
 
 struct ast_cc_monitor_callbacks {
-	/* Type of the monitor callbacks */
+	/*!
+	 * Type of the monitor callbacks
+	 *
+	 * Examples include "generic" and "SIP"
+	 */
 	const char *type;
-	/* Allocate callback */
+	/*! 
+	 * Init callback
+	 *
+	 * Implementors must allocate the monitor's private_data
+	 * and initialize it to whatever may be necessary.
+	 *
+	 * Return 0 on success and -1 on failure.
+	 */
 	int (*init)(struct ast_cc_monitor *monitor, const int core_id);
-	/* Request CCSS callback */
+	/*! 
+	 * Request CCSS callback
+	 *
+	 * Perform whatever steps are necessary in order to request CC.
+	 * In addition, the monitor implementation is responsible for
+	 * starting the available timer in this callback. The scheduler
+	 * ID for the callback must be stored in the parent_link's child_avail_id
+	 * field.
+	 */
 	int (*request_cc)(struct ast_cc_monitor *monitor, const int core_id, struct ast_cc_monitor_link *parent_link);
-	/* Suspend monitoring callback */
+	/*!
+	 * Suspend monitoring callback
+	 *
+	 * Implementors must perform the necessary steps to suspend
+	 * monitoring.
+	 */
 	int (*suspend)(struct ast_cc_monitor *monitor, const int core_id);
-	/* Status request callback */
+	/*!
+	 * Status request callback
+	 *
+	 * Return the current status of the monitored device, in the form
+	 * of an ast_device_state enum. The core is only concerned with whether
+	 * the state of the device is AST_DEVICE_NOT_INUSE. Other device states
+	 * are considered "busy" by the core.
+	 */
 	enum ast_device_state(*status_request)(struct ast_cc_monitor *monitor, const int core_id);
-	/* Unsuspend monitoring callback */
+	/*! 
+	 * Unsuspend monitoring callback
+	 *
+	 * Perform the necessary steps to unsuspend monitoring.
+	 */
 	int (*unsuspend)(struct ast_cc_monitor *monitor, const int core_id);
 	/*!
 	 * Cancel the running available timer.
@@ -583,16 +618,11 @@
 	/*!
 	 * Destroy callback 
 	 *
-	 * This destructor is never called directly. Instead, it is passed
-	 * to the astobj2 system so that when the refcount for the monitor
-	 * reaches zero, this function is called.
-	 *
-	 * The parameter is a void pointer since that is what ao2 requires
-	 * for its destructors. However, the contents passed will always
-	 * be a pointer to the monitor being destroyed.
-	 */
-	void (*destructor)(void *monitor);
-	/* Pass status upstream callback (XXX ???) */
+	 * Implementors of this callback are responsible for destroying
+	 * all heap-allocated data in the monitor's private_data pointer, including
+	 * the private_data itself.
+	 */
+	 void (*destructor)(void *monitor);
 };
 
 struct ast_cc_agent {