[svn-commits] rmudgett: branch group/CCSS r238133 - in /team/group/CCSS: channels/ include/...

SVN commits to the Digium repositories svn-commits at lists.digium.com
Wed Jan 6 12:33:14 CST 2010


Author: rmudgett
Date: Wed Jan  6 12:33:09 2010
New Revision: 238133

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=238133
Log:
More doxygen comment updates for ccss.h.

*  Fixed cut and paste error for cc_party_b_free() and
ast_cc_monitor_party_b_free().
*  Changed the ast_cc_monitor_callbacks.destructor() signature from
void * to struct ast_cc_monitor *.
*  Fixed chan_dahdi.c snprintf sizeof useage for CCSS.

Modified:
    team/group/CCSS/channels/chan_dahdi.c
    team/group/CCSS/channels/chan_sip.c
    team/group/CCSS/include/asterisk/ccss.h
    team/group/CCSS/main/ccss.c

Modified: team/group/CCSS/channels/chan_dahdi.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/channels/chan_dahdi.c?view=diff&rev=238133&r1=238132&r2=238133
==============================================================================
--- team/group/CCSS/channels/chan_dahdi.c (original)
+++ team/group/CCSS/channels/chan_dahdi.c Wed Jan  6 12:33:09 2010
@@ -12262,7 +12262,8 @@
 			p->outgoing = 1;
 			if (analog_lib_handles(p->sig, p->radio, p->oprmode)) {
 				char dialstring[AST_CHANNEL_NAME];
-				snprintf(dialstring, sizeof(dialstring) - 1, "DAHDI/%s", (char *) data);
+
+				snprintf(dialstring, sizeof(dialstring), "DAHDI/%s", (char *) data);
 				tmp = analog_request(p->sig_pvt, &callwait, requestor, dialstring);
 #ifdef HAVE_PRI
 			} else if (dahdi_sig_pri_lib_handles(p->sig)) {
@@ -12347,8 +12348,8 @@
 #else
 			interface_name = create_channel_name(p);
 #endif	/* defined(HAVE_PRI) */
-			snprintf(full_interface_name, sizeof(full_interface_name) - 1, "DAHDI/%s", ast_str_buffer(interface_name));
-			snprintf(dialstring, sizeof(dialstring) - 1, "DAHDI/%s", dest);
+			snprintf(full_interface_name, sizeof(full_interface_name), "DAHDI/%s", ast_str_buffer(interface_name));
+			snprintf(dialstring, sizeof(dialstring), "DAHDI/%s", dest);
 			callback(inbound, p->cc_params, full_interface_name, dialstring);
 			ast_free(interface_name);
 		}

Modified: team/group/CCSS/channels/chan_sip.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/channels/chan_sip.c?view=diff&rev=238133&r1=238132&r2=238133
==============================================================================
--- team/group/CCSS/channels/chan_sip.c (original)
+++ team/group/CCSS/channels/chan_sip.c Wed Jan  6 12:33:09 2010
@@ -3662,7 +3662,7 @@
 static int sip_cc_monitor_status_response(struct ast_cc_monitor *monitor, const int core_id, enum ast_device_state devstate);
 static int sip_cc_monitor_unsuspend(struct ast_cc_monitor *monitor, const int core_id);
 static int sip_cc_monitor_cancel_available_timer(struct ast_cc_monitor *monitor, const int core_id, int *sched_id);
-static void sip_cc_monitor_destructor(void *monitor);
+static void sip_cc_monitor_destructor(struct ast_cc_monitor *monitor);
 static void sip_cc_monitor_instance_destructor(const int core_id);
 
 static struct ast_cc_monitor_callbacks sip_cc_monitor_callbacks = {
@@ -3796,7 +3796,7 @@
 	return 0;
 }
 
-static void sip_cc_monitor_destructor(void *monitor)
+static void sip_cc_monitor_destructor(struct ast_cc_monitor *monitor)
 {
 	/* Nothing to do here. */
 }

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=238133&r1=238132&r2=238133
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Wed Jan  6 12:33:09 2010
@@ -491,14 +491,17 @@
 
 struct ast_cc_monitor_callbacks {
 	/*!
-	 * \brief Type of the monitor callbacks
+	 * \brief Type of monitor the callbacks belong to.
 	 *
 	 * \note
 	 * Examples include "generic" and "SIP"
 	 */
 	const char *type;
 	/*!
-	 * \brief Init callback
+	 * \brief CC monitor initialization.
+	 *
+	 * \param monitor CC core monitor control.
+	 * \param core_id core_id of the CC transaction.
 	 *
 	 * \details
 	 * Implementers must allocate the monitor's private_data
@@ -509,7 +512,12 @@
 	 */
 	int (*init)(struct ast_cc_monitor *monitor, const int core_id);
 	/*!
-	 * \brief Request CCSS callback
+	 * \brief Request CCSS.
+	 *
+	 * \param monitor CC core monitor control.
+	 * \param core_id core_id of the CC transaction.
+	 * \param parent_link The extention monitor of this monitor.
+	 * Will never be NULL for a device monitor.
 	 *
 	 * \details
 	 * Perform whatever steps are necessary in order to request CC.
@@ -517,52 +525,88 @@
 	 * starting the available timer in this callback. The scheduler
 	 * ID for the callback must be stored in the parent_link's child_avail_id
 	 * field.
+	 *
+	 * \retval 0 on success
+	 * \retval -1 on failure.
 	 */
 	int (*request_cc)(struct ast_cc_monitor *monitor, const int core_id, struct ast_cc_monitor_link *parent_link);
 	/*!
-	 * \brief Suspend monitoring callback
+	 * \brief Suspend monitoring.
+	 *
+	 * \param monitor CC core monitor control.
+	 * \param core_id core_id of the CC transaction.
 	 *
 	 * \details
 	 * Implementers must perform the necessary steps to suspend
 	 * monitoring.
+	 *
+	 * \retval 0 on success
+	 * \retval -1 on failure.
 	 */
 	int (*suspend)(struct ast_cc_monitor *monitor, const int core_id);
 	/*!
-	 * \brief Status response callback
+	 * \brief Status response to an ast_cc_monitor_status_request().
+	 *
+	 * \param monitor CC core monitor control.
+	 * \param core_id core_id of the CC transaction.
+	 * \param devstate Current status of a Party A device.
 	 *
 	 * \details
 	 * Alert a monitor as to the status of the agent for which
 	 * the monitor had previously requested a status request.
+	 *
+	 * \note Zero or more responses may come as a result.
+	 *
+	 * \retval 0 on success
+	 * \retval -1 on failure.
 	 */
 	int (*status_response)(struct ast_cc_monitor *monitor, const int core_id, enum ast_device_state devstate);
 	/*!
-	 * \brief Unsuspend monitoring callback
+	 * \brief Unsuspend monitoring.
+	 *
+	 * \param monitor CC core monitor control.
+	 * \param core_id core_id of the CC transaction.
 	 *
 	 * \details
 	 * Perform the necessary steps to unsuspend monitoring.
+	 *
+	 * \retval 0 on success
+	 * \retval -1 on failure.
 	 */
 	int (*unsuspend)(struct ast_cc_monitor *monitor, const int core_id);
 	/*!
 	 * \brief Cancel the running available timer.
+	 *
+	 * \param monitor CC core monitor control.
+	 * \param core_id core_id of the CC transaction.
+	 * \param sched_id Available timer scheduler id to cancel.
+	 * Will never be NULL for a device monitor.
 	 *
 	 * \details
 	 * In most cases, this function will likely consist of just a
 	 * call to AST_SCHED_DEL. It might have been possible to do this
 	 * within the core, but unfortunately the mixture of sched_thread
 	 * and sched usage in Asterisk prevents such usage.
+	 *
+	 * \retval 0 on success
+	 * \retval -1 on failure.
 	 */
 	int (*cancel_available_timer)(struct ast_cc_monitor *monitor, const int core_id, int *sched_id);
 	/*!
-	 * \brief Destroy callback
+	 * \brief Destroy private data on the monitor.
+	 *
+	 * \param monitor CC core monitor control.
 	 *
 	 * \details
 	 * Implementers of this callback are responsible for destroying
 	 * all heap-allocated data in the monitor's private_data pointer, including
 	 * the private_data itself.
 	 */
-	void (*destructor)(void *monitor);
-	/*!
-	 * \brief Instance destroy callback
+	void (*destructor)(struct ast_cc_monitor *monitor);
+	/*!
+	 * \brief Destroy private data for a specific monitor instance.
+	 *
+	 * \param core_id core_id of the CC transaction.
 	 *
 	 * \details
 	 * This callback is called when a specific call completion transaction
@@ -805,7 +849,10 @@
 	 */
 	const char *type;
 	/*!
-	 * \brief Initialization callback.
+	 * \brief CC agent initialization.
+	 *
+	 * \param agent CC core agent control.
+	 * \param chan Original channel the agent will attempt to recall.
 	 *
 	 * \details
 	 * This callback is called when the CC core
@@ -815,10 +862,16 @@
 	 * on the agent. Additionally, if any ast_cc_agent_flags
 	 * are pertinent to the specific agent type, they should
 	 * be set in this function as well.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*init)(struct ast_cc_agent *agent, struct ast_channel *chan);
 	/*!
-	 * \brief Offer CC to caller
+	 * \brief Offer CC to caller.
+	 *
+	 * \param agent CC core agent control.
+	 * \param callee_interface Callee channel name.
 	 *
 	 * \details
 	 * This is called separately as each callee announces
@@ -831,10 +884,15 @@
 	 * a flag or flags when this function is called so that
 	 * subsequent ringing or hangup messages will have the
 	 * necessary information embedded within.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*offer_cc)(struct ast_cc_agent *agent, const char * const callee_interface);
 	/*!
-	 * \brief Start the offer timer
+	 * \brief Start the offer timer.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * This is called by the core when the caller hangs up after
@@ -847,18 +905,28 @@
 	 * may already have a scheduler context they wish to use, and
 	 * amongst those, some may use the ast_sched API while others
 	 * may use the ast_sched_thread API, which are incompatible.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*start_offer_timer)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Stop the offer timer
+	 * \brief Stop the offer timer.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * This callback is called by the CC core when the caller
 	 * has requested CC.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*stop_offer_timer)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Acknowledge CC request callback.
+	 * \brief Acknowledge CC request.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * When the core receives knowledge that a called
@@ -870,17 +938,24 @@
 	 */
 	void (*ack)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Request the status of the agent's device
+	 * \brief Request the status of the agent's device.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * Asynchronous request for the status of any caller
 	 * which may be a valid caller for the CC transaction.
 	 * Status responses should be made using the
 	 * ast_cc_status_response function.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*status_request)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Request for an agent's phone to stop ringing
+	 * \brief Request for an agent's phone to stop ringing.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * The usefulness of this is quite limited. The only specific
@@ -894,12 +969,17 @@
 	 * placed the call so that it will stop ringing. Since the
 	 * phone may be of any type, it is necessary to have a callback
 	 * that the core can know about.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*stop_ringing)(struct ast_cc_agent *agent);
 	/*!
 	 * \brief Let the caller know that the callee has become free
 	 * but that the caller cannot attempt to call back because
 	 * he is either busy or there is congestion on his line.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * This is something that really only affects a scenario where
@@ -910,10 +990,15 @@
 	 * this situation. If you're having trouble understanding what
 	 * the purpose of this callback is, then you can be safe simply
 	 * not implementing it.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*party_b_free)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Begin monitoring a busy device
+	 * \brief Begin monitoring a busy device.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * The core will call this callback if the callee becomes
@@ -921,10 +1006,15 @@
 	 * The agent should begin monitoring the caller's device.
 	 * When the caller becomes available again, the agent should
 	 * call ast_cc_agent_caller_available.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*start_monitoring)(struct ast_cc_agent *agent);
 	/*!
 	 * \brief Alert the caller that it is time to try recalling.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * The core will call this function when it receives notice
@@ -935,10 +1025,15 @@
 	 * discern that the caller is currently unavailable, then
 	 * the agent should react by calling the ast_cc_caller_unavailable
 	 * function.
+	 *
+	 * \retval 0 on success.
+	 * \retval -1 on error.
 	 */
 	int (*callee_available)(struct ast_cc_agent *agent);
 	/*!
-	 * \brief Destroy private data on the agent
+	 * \brief Destroy private data on the agent.
+	 *
+	 * \param agent CC core agent control.
 	 *
 	 * \details
 	 * The core will call this function upon completion
@@ -1145,7 +1240,11 @@
  * in order to determine the appropriate response to send to
  * the caller. In order to do this, the monitor calls this function.
  * Responses will arrive asynchronously.
+ *
+ * \note Zero or more responses may come as a result.
+ *
  * \param core_id The core ID of the CC transaction
+ *
  * \retval 0 Successfully requested status
  * \retval -1 Failed to request status
  */

Modified: team/group/CCSS/main/ccss.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/main/ccss.c?view=diff&rev=238133&r1=238132&r2=238133
==============================================================================
--- team/group/CCSS/main/ccss.c (original)
+++ team/group/CCSS/main/ccss.c Wed Jan  6 12:33:09 2010
@@ -848,7 +848,7 @@
 static int cc_extension_monitor_status_response(struct ast_cc_monitor *monitor, const int core_id, enum ast_device_state devstate);
 static int cc_extension_monitor_unsuspend(struct ast_cc_monitor *monitor, const int core_id);
 static int cc_extension_monitor_cancel_available_timer(struct ast_cc_monitor *monitor, const int core_id, int *sched_id);
-static void cc_extension_monitor_destructor(void *monitor);
+static void cc_extension_monitor_destructor(struct ast_cc_monitor *monitor);
 static void cc_extension_monitor_instance_destructor(const int core_id);
 
 static struct ast_cc_monitor_callbacks extension_monitor_cbs = {
@@ -966,17 +966,15 @@
 	return 0;
 }
 
-static void cc_extension_monitor_destructor(void *monitor)
-{
-	struct ast_cc_monitor *mon = monitor;
-	ast_log_dynamic_level(cc_logger_level, "Destructor called for monitor %s\n", mon->interface->name);
-	return;
+static void cc_extension_monitor_destructor(struct ast_cc_monitor *monitor)
+{
+	ast_log_dynamic_level(cc_logger_level, "Destructor called for monitor %s\n",
+		monitor->interface->name);
 }
 
 static void cc_extension_monitor_instance_destructor(const int core_id)
 {
 	/* Nothing special to do in this case */
-	return;
 }
 
 static int cc_generic_monitor_init(struct ast_cc_monitor *monitor, const int core_id);
@@ -985,7 +983,7 @@
 static int cc_generic_monitor_status_response(struct ast_cc_monitor *monitor, const int core_id, enum ast_device_state devstate);
 static int cc_generic_monitor_unsuspend(struct ast_cc_monitor *monitor, const int core_id);
 static int cc_generic_monitor_cancel_available_timer(struct ast_cc_monitor *monitor, const int core_id, int *sched_id);
-static void cc_generic_monitor_destructor(void *monitor);
+static void cc_generic_monitor_destructor(struct ast_cc_monitor *monitor);
 static void cc_generic_monitor_instance_destructor(const int core_id);
 
 static struct ast_cc_monitor_callbacks generic_monitor_cbs = {
@@ -1180,22 +1178,20 @@
 	return 0;
 }
 
-static void cc_generic_monitor_destructor(void *monitor)
-{
-	struct ast_cc_monitor *mon = monitor;
-	struct generic_monitor_pvt *gen_mon_pvt = mon->private_data;
+static void cc_generic_monitor_destructor(struct ast_cc_monitor *monitor)
+{
+	struct generic_monitor_pvt *gen_mon_pvt = monitor->private_data;
 
 	ast_log_dynamic_level(cc_logger_level, "Destroying generic monitor private\n");
 	if (gen_mon_pvt->sub) {
 		gen_mon_pvt->sub = ast_event_unsubscribe(gen_mon_pvt->sub);
 	}
 	ast_free(gen_mon_pvt);
-	return;
 }
 
 static void cc_generic_monitor_instance_destructor(const int core_id)
 {
-	return;
+	/* Move along.  Move along.  Nothing to do here. */
 }
 
 /*!
@@ -3167,10 +3163,10 @@
 	struct cc_core_instance *core_instance = data;
 	int res = 0;
 
-	if (core_instance->agent->callbacks->stop_ringing) {
-		res = core_instance->agent->callbacks->stop_ringing(core_instance->agent);
-	}
-	cc_unref(core_instance, "Stop ringing finished. Unref core_instance");
+	if (core_instance->agent->callbacks->party_b_free) {
+		res = core_instance->agent->callbacks->party_b_free(core_instance->agent);
+	}
+	cc_unref(core_instance, "Party B free finished. Unref core_instance");
 	return res;
 }
 
@@ -3183,7 +3179,7 @@
 	}
 
 	return ast_taskprocessor_push(cc_core_taskprocessor, cc_party_b_free,
-			cc_ref(core_instance, "Ref core instance for stop ringing callback"));
+		cc_ref(core_instance, "Ref core instance for party B free callback"));
 }
 
 struct cc_status_response_args {




More information about the svn-commits mailing list