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

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Mon Aug 17 14:53:30 CDT 2009


Author: mmichelson
Date: Mon Aug 17 14:53:26 2009
New Revision: 212624

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=212624
Log:
Progress commit.

Making some progress by creating a skeleton of a ccss.h file.
Much needs to be done to flesh this out further, but at least
now it can be seen that work is being done. :)


Added:
    team/group/CCSS/include/asterisk/ccss.h   (with props)

Added: team/group/CCSS/include/asterisk/ccss.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/CCSS/include/asterisk/ccss.h?view=auto&rev=212624
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (added)
+++ team/group/CCSS/include/asterisk/ccss.h Mon Aug 17 14:53:26 2009
@@ -1,0 +1,271 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 1999 - 2007, Digium, Inc.
+ *
+ * Mark Michelson <mmichelson at digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ * \brief Call Completion Supplementary Services API
+ * \author Mark Michelson <mmichelson at digium.com>
+ */
+
+#ifndef _ASTERISK_CCSS_H
+#define _ASTERISK_CCSS_H
+
+enum service_type {
+	/* Call Completion Busy Subscriber */
+	AST_CCSS_CCBS;
+	/* Call Completion No Response */
+	AST_CCSS_CCNR;
+	/* Call Completion Not Logged In (currently SIP only) */
+	AST_CCSS_CCNL;
+};
+
+/*!
+ * \since 1.6.4
+ * \brief The states used in the CCSS core state machine
+ *
+ * For more information, see doc/CCSS_architecture.pdf
+ */
+enum ast_ccss_state {
+	/*! Entered when it is determined that CCSS may be used for the call */
+	CC_AVAILABLE,
+	/*! Entered when a CCSS agent has offered CCSS to a caller */
+	CC_CALLER_OFFERED,
+	/*! Entered when a CCSS agent confirms that a caller has 
+	 * requested CCSS */
+	CC_CALLER_REQUESTED,
+	/*! Entered when a CCSS monitor confirms acknowledgment of an 
+	 * outbound CCSS request */
+	CC_ACTIVE,
+	/*! Entered when a CCSS monitor alerts the core that the called party 
+	 * has become available */
+	CC_CALLEE_READY,
+	/*! Entered when a CCSS agent alerts the core that the calling party 
+	 * may not be recalled because he is unavailable
+	 */
+	CC_CALLER_BUSY,
+	/*! Entered when a CCSS agent alerts the core that the calling party
+	 * is attempting to recall the called party
+	 */
+	CC_RECALLING,
+	/*! Entered when an application alerts the core that the calling party's
+	 * recall attempt has had a call progress response indicated
+	 */
+	CC_COMPLETE,
+	/*! Entered any time that something goes wrong during the process, thus
+	 * resulting in the failure of the attempted CCSS transaction
+	 */
+	CC_FAILED,
+};
+
+/* XXX Several of these structures may be modified to be opaque, with
+ * get and set functions in order to read/write values. This will provide
+ * ABI protection at the expense of having a bunch of API calls. For now,
+ * though, since I am in the rudimentary stages of coding this, all structures
+ * will be completely open.
+ */
+
+/*!
+ * \since 1.6.4
+ * \brief A structure for holding the configuration parameters 
+ * relating to CCSS
+ */
+struct ast_cc_config_params {
+	enum ccss_policy cc_agent_policy;
+	enum ccss_policy cc_monitor_policy;
+	unsigned int offer_timer;
+	unsigned int ccnr_available_timer;
+	unsigned int ccbs_available_timer;
+	unsigned int cc_max_agents;
+	unsigned int cc_max_monitors;
+	const char *callback_macro;
+};
+
+/*!
+ * \brief a link that connects two monitors in the weighted graph of 
+ * monitor structures.
+ *
+ * The parent and child pointers are ao2 objects. This way, when a 
+ * monitor has no more links pointing to it, it will be automatically 
+ * destroyed.
+ */
+struct ast_ccss_monitor_link {
+	/* The parent monitor (always an extension monitor) */
+	struct ast_ccss_monitor *parent;
+	/* The child monitor (may be extension or device monitor) */
+	struct ast_ccss_monitor *child;
+	/* The weight associated with this link. Lower weights have higher 
+	 * priority 
+	 */
+	unsigned long weight;
+	/* Boolean indicator of whether the link is currently suspended */
+	unsigned char is_suspended;
+	/* Which instance of the core state machine does this link correspond
+	 * to
+	 */
+	const unsigned int core_id;
+};
+
+/*! Used to determine which type
+ * of monitor an ast_ccss_device_monitor
+ * is.
+ */
+enum ast_ccss_monitor_type {
+	AST_CCSS_DEVICE_MONITOR,
+	AST_CCSS_EXTENSION_MONITOR,
+	/* A root monitor is a placeholder type, which serves
+	 * as a central root for a CCSS monitor tree. Its only job
+	 * is to pipe requests it receives from an extension monitor
+	 * 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_CCSS_ROOT_MONITOR,
+};
+
+/*! 
+ * \brief Relevant data for a device monitor
+ * 
+ * Device monitors communicate directly with outside devices, and they have
+ * specific duties to accomplish during operation of the core state machine.
+ * 
+ * In addition, a device monitor will always be a "leaf" in the tree of
+ * CCSS monitors, so they will only have parents, no children.
+ */
+struct ast_ccss_device_monitor_data {
+	/*! We need to remember which type of service to request/was requested
+	 * by this specific device monitor so we don't cause problems downstream
+	 */
+	enum service_type service_requested;
+	/*! A device name, formatted in a way that is understood by ast_device_state*
+	 * functions.
+	 */
+	const char *device_name;
+	/*! A device monitor will have at least one extension monitor as a parent,
+	 * but if a device is dialed by multiple extensions, then it is possible
+	 * to have a list of multiple extension monitors as parents. 
+	 */
+	AST_LIST_HEAD(,ast_ccss_monitor_link) parent_links;
+	/*! Device monitor operations which will vary between implementations. Think
+	 * of this sort of like the ast_channel_tech structure
+	 */
+	const struct device_monitor_cbs *callbacks;
+	/*! Different implementations of device monitors will have to remember
+	 * different data in order to facilitate the service.
+	 */
+	void *private_data;
+};
+
+struct ast_ccss_extension_monitor_data {
+	/*! List of extensions which have failed outstanding calls to this extension.
+	 * I find it unlikely that this will ever be largely populated. If this list
+	 * is empty, it means that this extension monitor is the root of a tree and
+	 * should send any upstream requests to the CCSS core.
+	 */
+	AST_LIST_HEAD(,ast_ccss_monitor_link) parent_links;
+	/*! List of downstream device monitors. This list will have multiple elements
+	 * in it for extensions which dial multiple devices.
+	 */
+	AST_LIST_HEAD(,ast_ccss_monitor_link) child_links;
+	const char *extension;
+	const char *context;
+};
+
+struct ast_ccss_root_monitor_data {
+	AST_LIST_HEAD(,ast_ccss_monitor_link) child_links;
+};
+
+/*! 
+ * \brief Structure that represents a CCSS monitor
+ * Both extension and device monitors will be represented
+ * with this structure. Information specific to each monitor
+ * type can be retrieved through the monitor_data union.
+ */
+struct ast_ccss_monitor {
+	enum ast_ccss_monitor_type type;
+	union {
+		struct ast_ccss_device_monitor_data;
+		struct ast_ccss_extension_monitor_data;
+		struct ast_ccss_root_monitor_data;
+	} monitor_data;
+	/*! One of CCBS or CCNR. */
+	/*! The name of the device/extension being monitored */
+	const char *name
+	/*! The list of links to upstream extension monitors */
+	AST_LIST_HEAD(,ast_ccss_monitor_link) parent_links;
+	/*! Callback functions needed for specific device monitor
+	 * implementations
+	 */
+	const struct ast_ccss_device_monitor_callbacks *callbacks;
+	/*! Data specific to a device monitor implementation */
+	void *private_data;
+};
+
+struct ast_ccss_device_monitor_callbacks {
+	/* Allocate callback */
+	/* Request CCSS callback */
+	/* Suspend monitoring callback */
+	/* Status request callback */
+	/* Destroy callback (XXX handled in ao2 destructor?) */
+};
+
+struct ast_ccss_agent {
+	/*! Which instance of the core state machine does this
+	 * agent pertain to?
+	 */
+	unsigned int core_id;
+	/*! Callback functions needed for specific agent
+	 * implementations
+	 */
+	const struct ast_ccss_agent_callbacks *callbacks;
+	/*! Data specific to agent implementation */
+	void *private_data;
+};
+
+struct ast_ccss_agent_callbacks {
+	/* Allocate callback */
+	/* Acknowledge CCSS request callback */
+	/* Status request callback */
+	/* Initiate recall callback */
+	/* Destroy_callback */
+};
+
+/*!
+ * \since 1.6.4
+ * \brief Allocate and initialize an instance of the CCSS core
+ * \param caller The identity of the caller
+ * \param called_tree A tree indicating the interfaces dialed during 
+ * this call, as well as which type of call completion service should 
+ * be requested for each device
+ * \retval negative The CCSS core failed to be initialized.
+ * \retval non-negative The identifier for this instance of the CCSS core
+ */
+int ast_ccss_core_init_instance(const char *caller, /*Type?*/ called_tree);
+
+/*!
+ * \since 1.6.4
+ * \brief Request that the core change states
+ * \param state The state to which we wish to change
+ * \param core_id The unique identifier for this instance of the CCSS core state machine
+ * \param debug Optional message explaining the reason for the state change
+ * \retval 0 State change successfully queued
+ * \retval -1 Unable to queue state change request
+ */
+int ast_ccss_request_state_change(enum ast_ccss_state state, const unsigned int core_id, const char *debug);
+
+#endif /* _ASTERISK_CCSS_H

Propchange: team/group/CCSS/include/asterisk/ccss.h
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/group/CCSS/include/asterisk/ccss.h
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/group/CCSS/include/asterisk/ccss.h
------------------------------------------------------------------------------
    svn:mime-type = text/plain




More information about the asterisk-commits mailing list