[svn-commits] mmichelson: branch group/CCSS r247912 - /team/group/CCSS/main/ccss.c

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Fri Feb 19 11:30:56 2010
New Revision: 247912

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=247912
Log:
Add doxygen to the ast_control_cc_payload structure to better explain the components.


Modified:
    team/group/CCSS/main/ccss.c

Modified: team/group/CCSS/main/ccss.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/main/ccss.c?view=diff&rev=247912&r1=247911&r2=247912
==============================================================================
--- team/group/CCSS/main/ccss.c (original)
+++ team/group/CCSS/main/ccss.c Fri Feb 19 11:30:56 2010
@@ -136,8 +136,23 @@
 	char cc_agent_dialstring[AST_MAX_EXTENSION];
 };
 
+/*!
+ * \brief The payload for an AST_CONTROL_CC frame
+ * 
+ * \details
+ * This contains all the necessary data regarding
+ * a called device so that the CC core will be able
+ * to allocate the proper monitoring resources.
+ */
 struct ast_control_cc_payload {
 	/*!
+	 * \brief The type of monitor to allocate.
+	 *
+	 * \details
+	 * The type of monitor to allocate. This is a string which corresponds
+	 * to a set of monitor callbacks registered. Examples include "generic"
+	 * and "SIP"
+	 *
 	 * \note This really should be an array of characters in case this payload
 	 * is sent accross an IAX2 link.  However, this would not make too much sense
 	 * given this type may not be recognized by the other end.
@@ -148,11 +163,70 @@
 	 * 2) Alignment padding issues for the element types.
 	 */
 	const char *monitor_type;
+	/*!
+	 * \brief Private data allocated by the callee
+	 *
+	 * \details
+	 * All channel drivers that monitor endpoints will need to allocate
+	 * data that is not usable by the CC core. In most cases, some or all
+	 * of this data is allocated at the time that the channel driver offers
+	 * CC to the caller. There are many opportunities for failures to occur
+	 * between when a channel driver offers CC and when a monitor is actually
+	 * allocated to watch the endpoint. For this reason, the channel driver
+	 * must give the core a pointer to the private data that was allocated so
+	 * that the core can call back into the channel driver to destroy it if
+	 * a failure occurs. If no private data has been allocated at the time that
+	 * CC is offered, then it is perfectly acceptable to pass NULL for this
+	 * field.
+	 */
 	void *private_data;
+	/*!
+	 * \brief Service offered by the endpoint
+	 *
+	 * \details
+	 * This indicates the type of call completion service offered by the
+	 * endpoint. This data is not crucial to the machinations of the CC core,
+	 * but it is helpful for debugging purposes.
+	 */
 	enum ast_cc_service_type service;
+	/*!
+	 * \brief Configuration parameters used by this endpoint
+	 *
+	 * \details
+	 * Each time an endpoint offers call completion, it must provide its call
+	 * completion configuration parameters. This is because settings may be different
+	 * depending on the circumstances.
+	 */
 	struct ast_cc_config_params config_params;
+	/*!
+	 * \brief ID of parent extension
+	 *
+	 * \details
+	 * This is the only datum that the CC core derives on its own and is not
+	 * provided by the offerer of CC. This provides the core with information on
+	 * which extension monitor is the most immediate parent of this device.
+	 */
 	int parent_interface_id;
+	/*!
+	 * \brief Name of device to be monitored
+	 *
+	 * \details
+	 * The device name by which this monitored endpoint will be referred in the
+	 * CC core. It is highly recommended that this device name is derived by using
+	 * the function ast_channel_get_device_name.
+	 */
 	char device_name[AST_CHANNEL_NAME];
+	/*!
+	 * \brief Recall dialstring
+	 *
+	 * \details
+	 * Certain channel drivers (DAHDI in particular) will require that a special
+	 * dialstring be used to indicate that the outgoing call is to interpreted as
+	 * a CC recall. If the channel driver has such a requirement, then this is
+	 * where that special recall dialstring is placed. If no special dialstring
+	 * is to be used, then the channel driver must provide the original dialstring
+	 * used to call this endpoint.
+	 */
 	char dialstring[AST_CHANNEL_NAME];
 };