[asterisk-commits] mmichelson: branch group/CCSS r214053 - in /team/group/CCSS: apps/ include/as...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Tue Aug 25 12:21:44 CDT 2009


Author: mmichelson
Date: Tue Aug 25 12:21:42 2009
New Revision: 214053

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=214053
Log:
Doxygenify app_dial functions for CC.


Modified:
    team/group/CCSS/apps/app_dial.c
    team/group/CCSS/include/asterisk/ccss.h

Modified: team/group/CCSS/apps/app_dial.c
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/CCSS/apps/app_dial.c?view=diff&rev=214053&r1=214052&r2=214053
==============================================================================
--- team/group/CCSS/apps/app_dial.c (original)
+++ team/group/CCSS/apps/app_dial.c Tue Aug 25 12:21:42 2009
@@ -1679,6 +1679,17 @@
 	struct ast_cc_interface_tree *interface_tree;
 };
 
+/*!
+ * \brief Destructor function for cc_interfaces datastore
+ *
+ * This function will free the actual datastore and drop
+ * the refcount for the interface tree by one. In cases
+ * where CC can actually be used, this unref will not
+ * result in the destruction of the interface tree, because
+ * the CC core will still have a reference.
+ *
+ * \param data The dial_cc_interfaces struct to destroy
+ */
 static void dial_cc_interfaces_destroy(void *data)
 {
 	struct dial_cc_interfaces *cc_interfaces = data;
@@ -1686,6 +1697,18 @@
 	ast_free(cc_interfaces);
 }
 
+/*!
+ * \brief Duplicate callback for cc_interfaces datastore
+ *
+ * Integers are copied by value, but the interface tree
+ * is done via a shallow copy and a bump of the refcount.
+ * This way, sub-Dials will be appending interfaces onto
+ * the same list as this call to Dial.
+ *
+ * \param data The old dial_cc_interfaces we want to copy
+ * \retval NULL Could not allocate memory for new dial_cc_interfaces
+ * \retval non-NULL The new copy of the dial_cc_interfaces
+ */
 static void *dial_cc_interfaces_duplicate(void *data)
 {
 	struct dial_cc_interfaces *old_cc_interfaces = data;
@@ -1700,12 +1723,29 @@
 	return new_cc_interfaces;
 }
 
+/*!
+ * \brief information regarding the dial_cc_interfaces datastore
+ *
+ * The dial_cc_interfaces datastore is responsible for keeping track
+ * of what CC-enabled interfaces have been dialed by the caller. For
+ * more information regarding the actual structure of the tree, see
+ * the documentation provided in include/asterisk/ccss.h
+ */
 static const struct ast_datastore_info dial_cc_interfaces_info = {
 	.type = "Dial CC Interfaces",
 	.duplicate = dial_cc_interfaces_duplicate,
 	.destroy = dial_cc_interfaces_destroy,
 };
 
+/*!
+ * \brief Routine to set the done flag on the dial_cc_interfaces datastore
+ *
+ * When we determine that further calls to Dial in a particular thread should
+ * not pay attention to any new CC offers, we set this flag as an indicator.
+ * 
+ * \param chan The calling channel with teh dial_cc_interfaaces datastore on it
+ * \return void
+ */
 static void cc_set_done_flag(struct ast_channel *chan)
 {
 	struct ast_datastore *cc_datastore;
@@ -1719,6 +1759,19 @@
 	ast_channel_unlock(chan);
 }
 
+/*!
+ * \brief Allocate and initialize an "extension" interface for CC purposes
+ *
+ * When app_dial starts, this function is called in order to set up the
+ * information about the extension in which this Dial is occurring. Any
+ * devices dialed will have this particular ast_cc_interface as a parent.
+ *
+ * \param exten Extension from which Dial is occurring
+ * \param context Context to which exten belongs
+ * \param parent_id What should we set the parent_id of this interface to?
+ * \retval NULL Memory allocation failure
+ * \retval non-NULL The newly-created ast_cc_interface for the extension
+ */
 static struct ast_cc_interface *cc_extension_interface_init(const char * const exten, const char * const context, const unsigned int parent_id)
 {
 	struct ast_str *str = ast_str_alloca(2 * AST_MAX_EXTENSION);
@@ -1737,6 +1790,21 @@
 	return cc_interface;
 }
 
+/*!
+ * \brief allocate dial_cc_interfaces datastore and initialize fields
+ *
+ * This function is called when Situation 1 occurs in create_root_cc_interface.
+ * See that function for more information on what Situation 1 is.
+ *
+ * In this particular case, we have to do a lot of memory allocation in order
+ * to create the datastore, the data for the datastore, the tree of interfaces
+ * that we'll be adding to, and the initial extension interface for this Dial
+ * attempt.
+ *
+ * \param chan The channel onto which the datastore should be added.
+ * \retval -1 An error occurred
+ * \retval 0 Success
+ */
 static int cc_interfaces_datastore_init(struct ast_channel *chan) {
 	struct dial_cc_interfaces *interfaces;
 	struct ast_cc_interface *cc_interface;
@@ -1776,6 +1844,30 @@
 	return 0;
 }
 
+/*!
+ * \brief Allocate and intitialize a device ast_cc_interface
+ *
+ * For all intents and purposes, this is the same as
+ * cc_extension_interface_init, except that there is only
+ * a single parameter used for naming the interface.
+ *
+ * This function is called when handling AST_CONTROL_CC frames.
+ * The device has reported that CC is possible, so we add it
+ * to the interface_tree.
+ *
+ * Note that it is not necessarily erroneous to add the same
+ * device to the tree twice. If the same device is called by
+ * two different extension during the same call, then
+ * that is a legitimate situation. Of course, I'm pretty sure
+ * the dialed_interfaces global datastore will not allow that
+ * to happen anyway.
+ *
+ * \param name The name of the device being added to the tree
+ * \param name_len The length of name, in bytes
+ * \param parent_id The parent of this new tree node.
+ * \retval NULL Memory allocation failure
+ * \retval non-NULL The new ast_cc_interface created.
+ */
 static struct ast_cc_interface *cc_device_interface_init(const char * const name, const size_t name_len, const int parent_id)
 {
 	struct ast_cc_interface *cc_interface = ast_calloc(1, sizeof(*cc_interface) + name_len);
@@ -1791,6 +1883,29 @@
 	return cc_interface;
 }
 
+/*!
+ * \brief Function for handling AST_CONTROL_CC frames
+ *
+ * Unless we are ignoring CC for some reason, we will always
+ * call this function when we read an AST_CONTROL_CC frame
+ * from an outbound channel.
+ *
+ * This function will call cc_device_interface_init to
+ * create the new ast_cc_interface for the device from which
+ * we read the frame. In addition, the new device will be added
+ * to the interface tree on the dial_cc_interfaces datastore
+ * on the inbound channel.
+ *
+ * If this is the first AST_CONTROL_CC frame that we have handled
+ * for this call, then we will also initialize the CC core for
+ * this call.
+ *
+ * \param inbound The caller's channel
+ * \param outbound The channel we read the control frame from
+ * \param frame_data The data on the frame (XXX currently unused)
+ * \param first Indicator of whether the frame we are reading is the first for the call.
+ * \return void
+ */
 static void handle_cc_control_frame(struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data, int *first)
 {
 	char device_name[AST_CHANNEL_NAME];
@@ -1804,7 +1919,7 @@
 		*dash = '\0';
 	}
 
-	if (!(cc_datastore = ast_channel_datastore_find(outbound, &dial_cc_interfaces_info, NULL))) {
+	if (!(cc_datastore = ast_channel_datastore_find(inbound, &dial_cc_interfaces_info, NULL))) {
 		ast_log(LOG_WARNING, "Unable to retrieve CC datastore while processing CC frame from '%s'. CC services will be unavailable.\n", device_name);
 		return;
 	}
@@ -1829,10 +1944,23 @@
 	}
 }
 
+/*!
+ * \brief Create the root extension interface for this Dial attempt
+ *
+ * This function is called at the beginning of a dial attempt to get the
+ * ball rolling as far as CC is concerned. See the in-line comments about the
+ * three situations that can occur for more details.
+ *
+ * \param chan The channel on which the dial_cc_interfaces datastore is on or needs
+ * to be created on
+ * \param[out] ignore_cc If the datastore is already on the channel and the done flag
+ * is set, then we will set this so that new CC offers will be ignored
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
 static int create_root_cc_interface(struct ast_channel *chan, int *ignore_cc)
 {
-	/* All right. So here's the deal. There are three things
-	 * that can happen here:
+	/* There are three situations to deal with here:
 	 *
 	 * 1. The channel does not have a cc_interface datastore on
 	 * it. This means that this is the first time that Dial has

Modified: team/group/CCSS/include/asterisk/ccss.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/CCSS/include/asterisk/ccss.h?view=diff&rev=214053&r1=214052&r2=214053
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Tue Aug 25 12:21:42 2009
@@ -410,20 +410,6 @@
  */
 void ast_cc_interface_tree_destroy(void *cc_interface_tree);
 
-/* So what APIs do we need... At least preliminarily, I'll need
- * a debugging function so I can be sure the "tree" is built properly.
- * Then, there will need to be a function to store the information in 
- * the CC core once app_dial has completed. Further, there should
- * be some core internal functions to build the monitor tree (or add
- * to the existing monitor graph as it may be) using the given list.
- */
-
-int ast_store_cc_interface_tree(struct ast_cc_interface_tree *cc_interface_tree);
-
-int ast_add_cc_interface_to_tree(struct ast_cc_interface_tree *cc_interface_tree, struct ast_cc_interface *cc_interface);
-
-void ast_print_cc_interface_tree(struct ast_cc_interface_tree *cc_interface_tree);
-
 /* END TREE STRUCTURES AND API FOR APP_DIAL'S USE */
 
 
@@ -585,6 +571,20 @@
 /*!
  * \since 1.6.4
  * \brief Allocate and initialize an instance of the CCSS core
+ *
+ * This function takes as arguments the caller's channel and the
+ * current list of called interfaces that app_dial has created. Note
+ * that after this function is called, it is perfectly acceptable
+ * for app_dial to continue adding interfaces to the called_tree.
+ *
+ * This function currently will add a reference to the called_tree
+ * so that it will not be deleted once the initial call has been
+ * hung up.
+ *
+ * TODO: This function also needs to allocate the agent structure
+ * for the caller's side and start the core state machine in the 
+ * CC_AVAILABLE state.
+ *
  * \param caller The caller's channel
  * \param called_tree A tree indicating the interfaces dialed during 
  * this call, as well as which type of call completion service should 




More information about the asterisk-commits mailing list