[Asterisk-cvs] asterisk/channels chan_agent.c,1.151,1.152

[kpfleming]

Update of /usr/cvsroot/asterisk/channels
In directory mongoose.digium.com:/tmp/cvs-serv31331/channels

Modified Files:
	chan_agent.c 
Log Message:
more documentation (issue #5174)


Index: chan_agent.c
===================================================================
RCS file: /usr/cvsroot/asterisk/channels/chan_agent.c,v
retrieving revision 1.151
retrieving revision 1.152
diff -u -d -r1.151 -r1.152
--- chan_agent.c	14 Sep 2005 00:59:51 -0000	1.151
+++ chan_agent.c	14 Sep 2005 02:12:37 -0000	1.152
@@ -10,8 +10,10 @@
  * This program is free software, distributed under the terms of
  * the GNU General Public License
  */
-/** @file chan_agent.c
- * Agents module.
+/**
+ * @file chan_agent.c
+ * @brief This file is the implementation of Agents modules.
+ * It is a dynamic module that is loaded by Asterisk. At load time, load_module is run.
  */
 
 #include <stdio.h>
@@ -190,7 +192,7 @@
 	struct agent_pvt *next;        /**< Next Agent in the linked list. */
 };
 
-struct agent_pvt *agents = NULL;  /**< Holds the list of agents (loaded form agents.conf). */
+static struct agent_pvt *agents = NULL;  /**< Holds the list of agents (loaded form agents.conf). */
 
 #define CHECK_FORMATS(ast, p) do { \
 	if (p->chan) {\
@@ -378,6 +380,12 @@
 	return p;
 }
 
+/**
+ * Deletes an agent after doing some clean up.
+ * Further documentation: How safe is this function ? What state should the agent be to be cleaned.
+ * @param p Agent to be deleted.
+ * @returns Always 0.
+ */
 static int agent_cleanup(struct agent_pvt *p)
 {
 	struct ast_channel *chan = p->owner;
@@ -1340,7 +1348,14 @@
 	return 0;
 }
 
-/*--- action_agents: Manager routine for listing channels */
+/**
+ * Lists agents and their status to the Manager API.
+ * It is registered on load_module() and it gets called by the manager backend.
+ * @param s
+ * @param m
+ * @returns 
+ * @sa action_agent_logoff(), action_agent_callback_login(), load_module().
+ */
 static int action_agents(struct mansession *s, struct message *m)
 {
 	char *id = astman_get_header(m,"ActionID");
@@ -1476,6 +1491,14 @@
 	return RESULT_SUCCESS;
 }
 
+/**
+ * Sets an agent as no longer logged in in the Manager API.
+ * It is registered on load_module() and it gets called by the manager backend.
+ * @param s
+ * @param m
+ * @returns 
+ * @sa action_agents(), action_agent_callback_login(), load_module().
+ */
 static int action_agent_logoff(struct mansession *s, struct message *m)
 {
 	char *agent = astman_get_header(m, "Agent");
@@ -1611,7 +1634,14 @@
 STANDARD_LOCAL_USER;
 LOCAL_USER_DECL;
 
-/*--- __login_exec: Log in agent application ---*/
+/**
+ * Log in agent application.
+ *
+ * @param chan
+ * @param data
+ * @param callbackmode
+ * @returns 
+ */
 static int __login_exec(struct ast_channel *chan, void *data, int callbackmode)
 {
 	int res=0;
@@ -2070,16 +2100,40 @@
  	return -1;
 }
 
+/**
+ * Called by the AgentLogin application (from the dial plan).
+ * 
+ * @param chan
+ * @param data
+ * @returns
+ * @sa callback_login_exec(), agentmonitoroutgoing_exec(), load_module().
+ */
 static int login_exec(struct ast_channel *chan, void *data)
 {
 	return __login_exec(chan, data, 0);
 }
 
+/**
+ *  Called by the AgentCallbackLogin application (from the dial plan).
+ * 
+ * @param chan
+ * @param data
+ * @returns
+ * @sa login_exec(), agentmonitoroutgoing_exec(), load_module().
+ */
 static int callback_exec(struct ast_channel *chan, void *data)
 {
 	return __login_exec(chan, data, 1);
 }
 
+/**
+ * Sets an agent as logged in by callback in the Manager API.
+ * It is registered on load_module() and it gets called by the manager backend.
+ * @param s
+ * @param m
+ * @returns 
+ * @sa action_agents(), action_agent_logoff(), load_module().
+ */
 static int action_agent_callback_login(struct mansession *s, struct message *m)
 {
 	char *agent = astman_get_header(m, "Agent");
@@ -2155,6 +2209,15 @@
 
 	return 0;
 }
+
+/**
+ *  Called by the AgentMonitorOutgoing application (from the dial plan).
+ *
+ * @param chan
+ * @param data
+ * @returns
+ * @sa login_exec(), callback_login_exec(), load_module().
+ */
 static int agentmonitoroutgoing_exec(struct ast_channel *chan, void *data)
 {
 	int exitifnoagentid = 0;
@@ -2211,9 +2274,9 @@
 	return 0;
 }
 
-/* Dump AgentCallbackLogin agents to the database for persistence
+/**
+ * Dump AgentCallbackLogin agents to the database for persistence
  */
-
 static void dump_agents(void)
 {
 	struct agent_pvt *cur_agent = NULL;