[svn-commits] mmichelson: branch group/CCSS r214053 - in /team/group/CCSS: apps/ include/as...
SVN commits to the Digium repositories
svn-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 svn-commits
mailing list