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

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Sun Oct 18 15:51:47 2009
New Revision: 224439

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=224439
Log:
Add doxygen for structs in ccss.h


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=224439&r1=224438&r2=224439
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Sun Oct 18 15:51:47 2009
@@ -460,43 +460,23 @@
 	 * to the core and vice-versa. Note that it is not mentioned 
 	 * in CCSS_architecture.pdf because it is a fairly low-level 
 	 * concept and doesn't bear mentioning there.
-	 *
-	 * XXX This may turn out to not be necessary
 	 */
 	AST_CC_ROOT_MONITOR,
 };
 
-/* The tree app_dial uses must be simple, goddammit. What is needed?
- * The name of the device/extension being dialed, and what ccss is
- * relevant for the specific device.
- *
- * Think about Dial's operation...When a device is called, it all
- * happens within the same thread. However, if Dial calls, say, two
- * Local channels, then there will be two simultaneous threads
- * which will try to manipulate the same structure. We need a lock.
- * Of course the other problem is that if this is going to exist
- * as a datastore on the channel, then dialing local channels should
- * probably result in their increasing a reference count on the data.
- *
- * Actually, there really doesn't need to be a new lock for this structure.
- * After all, since I'll be using a datastore, I'll need to lock the channel
- * to operate on the datastore.
- */
-
-/* So the gory datastore details will be in app_dial. However, the structure
- * it makes use of needs to be accessible to the CC core as well. So that
- * is why this is here and not in app_dial. All right.
- */
-
-/* All right, so while an actual tree-like structure is necessary in order
- * to handle all the intricacies of the weighted graph that a monitor uses,
- * for a simple phone call, that won't be necessary. All that's necessary
- * is a linked list of devices. Each device contains an indication of who
- * its "parent" is. This way, A tree may be easily constructed by traversing
- * the list. We can guarantee that we will generally be going in a top-to-bottom
- * order.
- */
-
+/*!
+ * \brief Structure with information about an outbound interface
+ *
+ * This structure is first created when an outbound interface indicates that
+ * it is capable of accepting a CC request. It is stored in a "tree" on a datastore on
+ * the caller's channel. Once an agent structure is created, the agent gains
+ * a reference to the tree of interfaces. If CC is requested, then the
+ * interface tree on the agent is converted into a tree of monitors. Each
+ * monitor will contain a pointer to an individual ast_cc_interface. Finally,
+ * the tree of interfaces is also present on a second datastore during a
+ * CC recall so thta the CC_INTERFACES channel variable may be properly
+ * populated.
+ */
 struct ast_cc_interface {
 	/* What class of monitor is being offered here
 	 */
@@ -520,7 +500,14 @@
 	char name[1];
 };
 
-/* This may be a candidate for opacity. Who the heck knows. */
+/*!
+ * \brief An item in a CC interface tree.
+ *
+ * These are the individual items in an interface tree.
+ * The key difference between this structure and the ast_cc_interface
+ * is that this structure contains data which is intrinsic to the item's
+ * placement in the tree, such as who its parent is.
+ */
 struct ast_cc_tree_item {
 	/* Information regarding the interface.
 	 */