[asterisk-commits] mmichelson: branch group/CCSS r224564 - in /team/group/CCSS: include/asterisk...

SVN commits to the Asterisk project asterisk-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 asterisk-commits mailing list