[svn-commits] mmichelson: branch group/CCSS r212624 - /team/group/CCSS/include/asterisk/ccss.h
SVN commits to the Digium repositories
svn-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 svn-commits
mailing list