[svn-commits] mmichelson: branch group/CCSS r224564 - in /team/group/CCSS: include/asterisk...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Mon Oct 19 14:43:30 CDT 2009
Author: mmichelson
Date: Mon Oct 19 14:43:26 2009
New Revision: 224564
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=224564
Log:
Some more function and struct rearranging.
Modified:
team/group/CCSS/include/asterisk/ccss.h
team/group/CCSS/main/ccss.c
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=224564&r1=224563&r2=224564
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Mon Oct 19 14:43:26 2009
@@ -359,95 +359,101 @@
/* 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 Set the dialable name for an extension
- *
- * An extension will look like "exten at context." But when it
- * comes time to dial the extension again, what we actually will
- * need to dial may be "Local/exten at context" or "Local/exten at context/n"
- * or something like that. As such, we need to store this information
- * when we call the local channel.
- *
- * Honestly, this function is only used by chan_local.c, and probably
- * will never be used outside of that file, so you can safely ignore
- * this function, most likely.
- */
-void ast_cc_set_extension_dialable_name(struct ast_channel *chan, const char * const dialable_name);
-
-/*!
- * \since 1.6.4
- *
- * \brief Start the CC process on a call.
- *
- * 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_call_init(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
+/* BEGIN AGENT/MONITOR REGISTRATION API */
+
+struct ast_cc_monitor_callbacks;
+
+/*!
+ * \since 1.6.4
+ * \brief Register a set of monitor callbacks with the core
+ *
+ * This is made so that at monitor creation time, the proper callbacks
+ * may be installed and the proper .init callback may be called for the
+ * monitor to establish private data.
+ *
+ * \param callbacks The callbacks used by the monitor implementation
+ * \retval 0 Successfully registered
+ * \retval -1 Failure to register
+ */
+int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks);
+
+struct ast_cc_agent_callbacks;
+
+/*!
+ * \since 1.6.4
+ * \brief Register a set of agent callbacks with the core
+ *
+ * This is made so that at agent creation time, the proper callbacks
+ * may be installed and the proper .init callback may be called for the
+ * monitor to establish private data.
+ *
+ * \param callbacks The callbacks used by the agent implementation
+ * \retval 0 Successfully registered
+ * \retval -1 Failure to register
+ */
+int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks);
+
+/* END AGENT/MONITOR REGISTRATION API */
+
+/* BEGIN SECTION ON MONITORS AND MONITOR CALLBACKS */
+
+/*!
+ * It is recommended that monitors use a pointer to
+ * an ast_cc_monitor_callbacks::type when creating
+ * an AST_CONTROL_CC frame. Since the generic monitor
+ * callbacks are opaque and channel drivers will wish
+ * to use that, this string is made globally available
+ * for all to use
+ */
+#define AST_CC_GENERIC_MONITOR_TYPE "generic"
+
+/*!
+ * \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_cc_monitor_link {
+ /* The parent monitor (always an extension monitor) */
+ struct ast_cc_monitor *parent;
+ /* The child monitor (may be extension or device monitor) */
+ struct ast_cc_monitor *child;
+ /* 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
+ */
+ int core_id;
+ /* Which service is being requested? */
+ enum ast_cc_service_type service;
+ /*!
+ * An ID for the available timer for a corresponding child device
+ * monitor.
+ *
+ * Really, it would seem a bit more logical to have this
+ * ID reside on the monitor itself, but as far as ease-of-coding
+ * is concerned, links already exist as something unique per
+ * instance of a monitor. This way, multiple calls to a single
+ * monitor may have independent available timers running.
+ *
+ * For links between two extension monitors, this field
+ * never will be used.
+ */
+ int child_avail_id;
+ /*!
+ * Why are there two AST_LIST_ENTRY fields in this
+ * struct? The reason is that each link is in a list
+ * parent links of one monitor, and in a list of child
+ * links for another.
+ */
+ AST_LIST_ENTRY(ast_cc_monitor_link) next_child;
+ AST_LIST_ENTRY(ast_cc_monitor_link) next_parent;
+};
+
+/*!
+ * Used to determine which type
* of monitor an ast_cc_device_monitor
* is.
*/
@@ -462,99 +468,6 @@
* concept and doesn't bear mentioning there.
*/
AST_CC_ROOT_MONITOR,
-};
-
-/*!
- * \brief Structure with information about an outbound interface
- *
- * This structure is first created when an outbound interface indicates that
- * it is capable of accepting a CC request. It is stored in a "tree" on a datastore on
- * the caller's channel. Once an agent structure is created, the agent gains
- * a reference to the tree of interfaces. If CC is requested, then the
- * interface tree on the agent is converted into a tree of monitors. Each
- * monitor will contain a pointer to an individual ast_cc_interface. Finally,
- * the tree of interfaces is also present on a second datastore during a
- * CC recall so thta the CC_INTERFACES channel variable may be properly
- * populated.
- */
-struct ast_cc_interface {
- /* What class of monitor is being offered here
- */
- enum ast_cc_monitor_class monitor_class;
- /*!
- * The type of monitor that should be used for this interface
- *
- * This will be something like "extension" "generic" or "SIP"
- * This should point to a static const char *, so there is
- * no reason to make a new copy.
- */
- const char *monitor_type;
- /*!
- * The configuration parameters used for this interface
- */
- struct ast_cc_config_params *config_params;
- /* The name of the interface/extension. local channels will
- * have 'exten at context' for a name. Other channel types will
- * have 'tech/device' for a name.
- */
- char name[1];
-};
-
-/* END TREE STRUCTURES AND API FOR APP_DIAL'S USE */
-
-/*!
- * It is recommended that monitors use a pointer to
- * an ast_cc_monitor_callbacks::type when creating
- * an AST_CONTROL_CC frame. Since the generic monitor
- * callbacks are opaque and channel drivers will wish
- * to use that, this string is made globally available
- * for all to use
- */
-#define AST_CC_GENERIC_MONITOR_TYPE "generic"
-
-/*!
- * \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_cc_monitor_link {
- /* The parent monitor (always an extension monitor) */
- struct ast_cc_monitor *parent;
- /* The child monitor (may be extension or device monitor) */
- struct ast_cc_monitor *child;
- /* 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
- */
- int core_id;
- /* Which service is being requested? */
- enum ast_cc_service_type service;
- /*!
- * An ID for the available timer for a corresponding child device
- * monitor.
- *
- * Really, it would seem a bit more logical to have this
- * ID reside on the monitor itself, but as far as ease-of-coding
- * is concerned, links already exist as something unique per
- * instance of a monitor. This way, multiple calls to a single
- * monitor may have independent available timers running.
- *
- * For links between two extension monitors, this field
- * never will be used.
- */
- int child_avail_id;
- /*!
- * Why are there two AST_LIST_ENTRY fields in this
- * struct? The reason is that each link is in a list
- * parent links of one monitor, and in a list of child
- * links for another.
- */
- AST_LIST_ENTRY(ast_cc_monitor_link) next_child;
- AST_LIST_ENTRY(ast_cc_monitor_link) next_parent;
};
/*!
@@ -653,6 +566,189 @@
void (*destructor)(void *monitor);
};
+/*!
+ * \since 1.6.4
+ * \brief Scheduler callback for available timer expiration
+ *
+ * When arming the available timer from within a device monitor, you MUST
+ * use this function as the callback for the scheduler.
+ *
+ * \param data The parent link of the monitor for which the available timer has been
+ * armed.
+ */
+int ast_cc_available_timer_expire(const void *data);
+
+/* END SECTION ON MONITORS AND MONITOR CALLBACKS */
+
+/* BEGIN API FOR IN-CALL CC HANDLING */
+
+/*!
+ * \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 Set the dialable name for an extension
+ *
+ * An extension will look like "exten at context." But when it
+ * comes time to dial the extension again, what we actually will
+ * need to dial may be "Local/exten at context" or "Local/exten at context/n"
+ * or something like that. As such, we need to store this information
+ * when we call the local channel.
+ *
+ * Currently, this function is only used by chan_local.c, and probably
+ * will never be used outside of that file, so you can safely ignore
+ * this function, most likely.
+ */
+void ast_cc_set_extension_dialable_name(struct ast_channel *chan, const char * const dialable_name);
+
+/*!
+ * \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 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);
+
+/*!
+ * \since 1.6.4
+ *
+ * \brief Start the CC process on a call.
+ *
+ * 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_call_init(struct ast_channel *chan, int *ignore_cc);
+
+/*!
+ * \since 1.6.4
+ * \brief Check if the incoming CC request is within the bounds
+ * set by the cc_max_requests configuration option
+ *
+ * It is recommended that an entity which receives an incoming
+ * CC request calls this function before changing state to
+ * CC_CALLER_REQUESTED. This way, immediate feedback can be
+ * given to the caller about why his request was rejected.
+ *
+ * If this is not called and a state change to CC_CALLER_REQUESTED
+ * is made, then the core will still not allow for the request
+ * to succeed. However, if done this way, it may not be obvious
+ * to the requestor why the request failed.
+ *
+ * \retval 0 Not within the limits. Fail.
+ * \retval non-zero Within the limits. Success.
+ */
+int ast_cc_request_within_limits(void);
+
+/*!
+ * \since 1.6.4
+ * \brief Get the core id for the current call
+ *
+ * The main use of this function is for channel drivers
+ * who queue an AST_CONTROL_CC frame. A channel driver may
+ * call this function in order to get the core_id for what
+ * may become a CC request. This way, when monitor functions
+ * are called which use a core_id as a means of identification,
+ * the channel driver will have saved this information.
+ *
+ * The channel given to this function may be an inbound or outbound
+ * channel. Both will have the necessary info on it.
+ *
+ * \param chan The channel from which to get the core_id.
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_cc_get_current_core_id(struct ast_channel *chan);
+
+/* END API FOR IN-CALL CC HANDLING */
+
+/*!
+ * \brief Structure with information about an outbound interface
+ *
+ * This structure is first created when an outbound interface indicates that
+ * it is capable of accepting a CC request. It is stored in a "tree" on a datastore on
+ * the caller's channel. Once an agent structure is created, the agent gains
+ * a reference to the tree of interfaces. If CC is requested, then the
+ * interface tree on the agent is converted into a tree of monitors. Each
+ * monitor will contain a pointer to an individual ast_cc_interface. Finally,
+ * the tree of interfaces is also present on a second datastore during a
+ * CC recall so thta the CC_INTERFACES channel variable may be properly
+ * populated.
+ */
+struct ast_cc_interface {
+ /* What class of monitor is being offered here
+ */
+ enum ast_cc_monitor_class monitor_class;
+ /*!
+ * The type of monitor that should be used for this interface
+ *
+ * This will be something like "extension" "generic" or "SIP"
+ * This should point to a static const char *, so there is
+ * no reason to make a new copy.
+ */
+ const char *monitor_type;
+ /*!
+ * The configuration parameters used for this interface
+ */
+ struct ast_cc_config_params *config_params;
+ /* The name of the interface/extension. local channels will
+ * have 'exten at context' for a name. Other channel types will
+ * have 'tech/device' for a name.
+ */
+ char name[1];
+};
+
+/* BEGIN STRUCTURES FOR AGENTS */
+
struct ast_cc_agent {
/*!
* Which instance of the core state machine does this
@@ -799,6 +895,10 @@
*/
void (*destructor)(struct ast_cc_agent *agent);
};
+
+/* END STRUCTURES FOR AGENTS */
+
+/* BEGIN STATE CHANGE API */
/*!
* \since 1.6.4
@@ -833,6 +933,7 @@
* \retval 0 Success
*/
int ast_cc_offer(struct ast_channel *caller_chan);
+
/*!
* \since 1.6.4
* \brief Request that the core change states
@@ -844,6 +945,20 @@
*/
int ast_cc_request_state_change(enum ast_cc_state state, const int core_id, const char *debug);
+/* END STATE CHANGE API */
+
+/* BEGIN API FOR USE WITH/BY MONITORS */
+
+/*!
+ * \since 1.6.4
+ * \brief Return the number of outstanding CC requests to a specific device
+ *
+ * \param name The name of the monitored device
+ * \param type The type of the monitored device (e.g. "generic")
+ * \return The number of CC requests for the monitor
+ */
+int ast_cc_monitor_count(const char * const name, const char * const type);
+
/*!
* \since 1.6.4
* \brief Alert the core that a device being monitored has become available.
@@ -857,43 +972,9 @@
*/
int ast_cc_monitor_announce_availability(struct ast_cc_monitor *monitor);
-/*!
- * \since 1.6.4
- * \brief Return the number of outstanding CC requests to a specific device
- *
- * \param name The name of the monitored device
- * \param type The type of the monitored device (e.g. "generic")
- * \return The number of CC requests for the monitor
- */
-int ast_cc_monitor_count(const char * const name, const char * const type);
-
-/*!
- * \since 1.6.4
- * \brief Register a set of monitor callbacks with the core
- *
- * This is made so that at monitor creation time, the proper callbacks
- * may be installed and the proper .init callback may be called for the
- * monitor to establish private data.
- *
- * \param callbacks The callbacks used by the monitor implementation
- * \retval 0 Successfully registered
- * \retval -1 Failure to register
- */
-int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks);
-
-/*!
- * \since 1.6.4
- * \brief Register a set of agent callbacks with the core
- *
- * This is made so that at agent creation time, the proper callbacks
- * may be installed and the proper .init callback may be called for the
- * monitor to establish private data.
- *
- * \param callbacks The callbacks used by the agent implementation
- * \retval 0 Successfully registered
- * \retval -1 Failure to register
- */
-int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks);
+/* END API FOR USE WITH/BY MONITORS */
+
+/* BEGIN API TO BE USED ON CC RECALL */
/*!
* \since 1.6.4
@@ -923,26 +1004,6 @@
/*!
* \since 1.6.4
- * \brief Get the core id for the current call
- *
- * The main use of this function is for channel drivers
- * who queue an AST_CONTROL_CC frame. A channel driver may
- * call this function in order to get the core_id for what
- * may become a CC request. This way, when monitor functions
- * are called which use a core_id as a means of identification,
- * the channel driver will have saved this information.
- *
- * The channel given to this function may be an inbound or outbound
- * channel. Both will have the necessary info on it.
- *
- * \param chan The channel from which to get the core_id.
- * \retval 0 Success
- * \retval -1 Failure
- */
-int ast_cc_get_current_core_id(struct ast_channel *chan);
-
-/*!
- * \since 1.6.4
* \brief Set the CC_INTERFACES channel variable for a channel
*
* Implementors of protocol-specific CC agents should call this function after
@@ -955,38 +1016,6 @@
/*!
* \since 1.6.4
- * \brief Scheduler callback for available timer expiration
- *
- * When arming the available timer from within a device monitor, you MUST
- * use this function as the callback for the scheduler.
- *
- * \param data The parent link of the monitor for which the available timer has been
- * armed.
- */
-int ast_cc_available_timer_expire(const void *data);
-
-/*!
- * \since 1.6.4
- * \brief Check if the incoming CC request is within the bounds
- * set by the cc_max_requests configuration option
- *
- * It is recommended that an entity which receives an incoming
- * CC request calls this function before changing state to
- * CC_CALLER_REQUESTED. This way, immediate feedback can be
- * given to the caller about why his request was rejected.
- *
- * If this is not called and a state change to CC_CALLER_REQUESTED
- * is made, then the core will still not allow for the request
- * to succeed. However, if done this way, it may not be obvious
- * to the requestor why the request failed.
- *
- * \retval 0 Not within the limits. Fail.
- * \retval non-zero Within the limits. Success.
- */
-int ast_cc_request_within_limits(void);
-
-/*!
- * \since 1.6.4
* \brief Initialize CCSS
*
* XXX This needs to be updated as more functionality is added.
Modified: team/group/CCSS/main/ccss.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/main/ccss.c?view=diff&rev=224564&r1=224563&r2=224564
==============================================================================
--- team/group/CCSS/main/ccss.c (original)
+++ team/group/CCSS/main/ccss.c Mon Oct 19 14:43:26 2009
@@ -2128,12 +2128,6 @@
return 0;
}
-struct cc_state_change_args {
- enum ast_cc_state state;
- int core_id;
- char debug[1];
-};
-
/*!
* \brief pass a state change up the monitor tree
*
@@ -2248,6 +2242,12 @@
cc_unref(monitor, "Kill reference from ast_cc_monitor_announce_availabilty");
return 0;
}
+
+struct cc_state_change_args {
+ enum ast_cc_state state;
+ int core_id;
+ char debug[1];
+};
static int cc_do_state_change(void *datap)
{
More information about the svn-commits
mailing list