Add manager doxygen docs (bug #3691)
authorMark Spencer <markster@digium.com>
Wed, 2 Mar 2005 05:58:13 +0000 (05:58 +0000)
committerMark Spencer <markster@digium.com>
Wed, 2 Mar 2005 05:58:13 +0000 (05:58 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@5117 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/manager.h

index d25e150..6629e72 100755 (executable)
 
 #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 */
 #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