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

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Thu Oct  1 13:45:49 2009
New Revision: 221689

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=221689
Log:
Doxygenify the API functions created in previous commit.


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=221689&r1=221688&r2=221689
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Thu Oct  1 13:45:49 2009
@@ -346,9 +346,74 @@
 /* END CONFIGURATION FUNCTIONS */
 
 /* BEGIN TREE STRUCTURES AND APIS FOR APP_DIAL'S USE */
+/*!
+ * \since 1.6.4
+ *
+ * \brief Properly react to a CC control frame.
+ *
+ * When a CC-capable application, such as Dial, receives a frame
+ * of type AST_CONTROL_CC, then it may call this function in order
+ * to have the device which sent the frame added to the tree of interfaces
+ * which is kept on the inbound channel.
+ *
+ * \param inbound The inbound channel
+ * \param outbound The outbound channel (The one from which the CC frame was read)
+ * \param frame_data The ast_frame's data.ptr field.
+ * \retval void
+ */
 void ast_handle_cc_control_frame(struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data);
+
+/*!
+ * \since 1.6.4
+ *
+ * \brief Mark the channel to ignore further CC activity.
+ *
+ * When a CC-capable application, such as Dial, has finished
+ * with all CC processing for a channel and knows that any further
+ * CC processing should be ignored, this function should be called.
+ * 
+ * \param chan The channel for which further CC processing should be ignored.
+ * \retval void
+ */
 void ast_ignore_cc(struct ast_channel *chan);
+
+/*!
+ * \since 1.6.4
+ *
+ * \brief Start the CC process.
+ *
+ * Whenever a CC-capable application, such as Dial, wishes to
+ * engage in CC activity, it initiates the process by calling this
+ * function. If the CC core should discover that a previous application
+ * has called ast_ignore_cc on this channel or a "parent" channel, then
+ * the value of the ignore_cc integer passed in will be set nonzero.
+ *
+ * The ignore_cc parameter is a convenience parameter. It can save an
+ * application the trouble of trying to call CC APIs when it knows that
+ * it should just ignore further attempts at CC actions.
+ *
+ * \param chan The inbound channel calling the CC-capable application.
+ * \param[out] ignore_cc Will be set non-zero if no further CC actions need to be taken
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
 int ast_cc_create_root_tree_item(struct ast_channel *chan, int *ignore_cc);
+
+/*!
+ * \since 1.6.4
+ *
+ * \brief Create a new core instance
+ *
+ * CC-capable applications, such as Dial, will call this function
+ * after it is known that all interfaces which may have possibly
+ * offered CC to the caller have done so. This function will start
+ * the process of creating a new instance of the CC core to be used
+ * for this CC transaction.
+ *
+ * \param inbound The inbound channel which has called the CC-capable application
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
 int ast_cc_create_new_core(struct ast_channel *inbound);
 
 /*! Used to determine which type