Add manager doxygen docs (bug #3691)

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@5117 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 55 insertions, 16 deletions

diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h
index d25e150d8..6629e72c9 100755
--- a/include/asterisk/manager.h
+++ b/include/asterisk/manager.h
@@ -25,18 +25,22 @@
 
 #include <asterisk/lock.h>
 
-/* 
- * Call management packages are text fields of the form a: b.  There is
- * always exactly one space after the colon.
- *
- * The first header type is the "Event" header.  Other headers vary from
- * event to event.  Headers end with standard \r\n termination.
- *
- * Some standard headers:
- *
- * Action: <action>			-- request or notification of a particular action
- * Response: <response>		-- response code, like "200 OK"
- *
+/*!
+  \file manager.h
+  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to 
+	 manage Asterisk with third-party software.
+
+ Manager protocol packages are text fields of the form a: b.  There is
+ always exactly one space after the colon.
+ 
+ The first header type is the "Event" header.  Other headers vary from
+ event to event.  Headers end with standard \r\n termination.
+ 
+ Some standard headers:
+
+ Action: <action>		-- request or notification of a particular action
+ Response: <response>		-- response code, like "200 OK"
+ 
  */
  
 #define DEFAULT_MANAGER_PORT 5038	/* Default port for Asterisk management via TCP */
@@ -54,16 +58,26 @@
 #define MAX_LEN 256
 
 struct mansession {
+	/*! Execution thread */
 	pthread_t t;
+	/*! Thread lock */
 	ast_mutex_t lock;
+	/*! socket address */
 	struct sockaddr_in sin;
+	/*! TCP socket */
 	int fd;
 	int blocking;
+	/*! Logged in username */
 	char username[80];
+	/*! Authentication challenge */
 	char challenge[10];
+	/*! Authentication status */
 	int authenticated;
+	/*! Authorization for reading */
 	int readperm;
+	/*! Authorization for writing */
 	int writeperm;
+	/*! Buffer */
 	char inbuf[MAX_LEN];
 	int inlen;
 	int send_events;
@@ -95,20 +109,45 @@ int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
 
 /* External routines may register/unregister manager callbacks this way */
 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
-int ast_manager_register2( char *action, int authority, 
-					 int (*func)(struct mansession *s, struct message *m), char *synopsis, char *description);
+
+/* Use ast_manager_register2 to register with help text for new manager commands */
+
+/*! Register a manager command with the manager interface */
+/*! 	\param action Name of the requested Action:
+	\param authority Required authority for this command
+	\param func Function to call for this command
+	\param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
+	\param description Help text, several lines
+*/
+int ast_manager_register2( 
+	char *action, 
+	int authority, 
+	int (*func)(struct mansession *s, struct message *m), 
+	char *synopsis,
+	char *description);
+
+/*! Unregister a registred manager command */
+/*!	\param action Name of registred Action:
+*/
 int ast_manager_unregister( char *action );
 
-/* External routines may send asterisk manager events this way */
+/*! External routines may send asterisk manager events this way */
+/*! 	\param category	Event category, matches manager authorization
+	\param event	Event name
+	\param contents	Contents of event
+*/ 
 extern int manager_event(int category, char *event, char *contents, ...)
 	__attribute__ ((format (printf, 3,4)));
 
+/*! Get header from mananger transaction */
 extern char *astman_get_header(struct message *m, char *var);
+/*! Send error in manager transaction */
 extern void astman_send_error(struct mansession *s, struct message *m, char *error);
 extern void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
 extern void astman_send_ack(struct mansession *s, struct message *m, char *msg);
 
-/* Called by Asterisk initialization */
+/*! Called by Asterisk initialization */
 extern int init_manager(void);
+/*! Called by Asterisk initialization */
 extern int reload_manager(void);
 #endif