62454255d8842904ec488a88db2ce17b360ead2b
[asterisk/asterisk.git] / include / asterisk / manager.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * External call management support 
5  * 
6  * Copyright (C) 1999, Mark Spencer
7  *
8  * Mark Spencer <markster@linux-support.net>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU General Public License.
12  *
13  * Includes code and algorithms from the Zapata library.
14  *
15  */
16
17 #ifndef _ASTERISK_MANAGER_H
18 #define _ASTERISK_MANAGER_H
19
20 #include <stdarg.h>
21 #include <sys/types.h>
22 #include <sys/socket.h>
23 #include <netinet/in.h>
24 #include <arpa/inet.h>
25
26 #include "asterisk/lock.h"
27
28 /*!
29   \file manager.h
30   \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to 
31          manage Asterisk with third-party software.
32
33  Manager protocol packages are text fields of the form a: b.  There is
34  always exactly one space after the colon.
35  
36  The first header type is the "Event" header.  Other headers vary from
37  event to event.  Headers end with standard \r\n termination.
38  
39  Some standard headers:
40
41  Action: <action>               -- request or notification of a particular action
42  Response: <response>           -- response code, like "200 OK"
43  
44  */
45  
46 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
47
48 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
49 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
50 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
51 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
52 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
53 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
54 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
55
56 /* Export manager structures */
57 #define MAX_HEADERS 80
58 #define MAX_LEN 256
59
60 struct mansession {
61         /*! Execution thread */
62         pthread_t t;
63         /*! Thread lock */
64         ast_mutex_t lock;
65         /*! socket address */
66         struct sockaddr_in sin;
67         /*! TCP socket */
68         int fd;
69         int blocking;
70         /*! Logged in username */
71         char username[80];
72         /*! Authentication challenge */
73         char challenge[10];
74         /*! Authentication status */
75         int authenticated;
76         /*! Authorization for reading */
77         int readperm;
78         /*! Authorization for writing */
79         int writeperm;
80         /*! Buffer */
81         char inbuf[MAX_LEN];
82         int inlen;
83         int send_events;
84         struct mansession *next;
85 };
86
87
88 struct message {
89         int hdrcount;
90         char headers[MAX_HEADERS][MAX_LEN];
91 };
92
93 struct manager_action {
94         /*! Name of the action */
95         const char *action;
96         /*! Short description of the action */
97         const char *synopsis;
98         /*! Detailed description of the action */
99         const char *description;
100         /*! Permission required for action.  EVENT_FLAG_* */
101         int authority;
102         /*! Function to be called */
103         int (*func)(struct mansession *s, struct message *m);
104         /*! For easy linking */
105         struct manager_action *next;
106 };
107
108 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
109
110 /* External routines may register/unregister manager callbacks this way */
111 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
112
113 /* Use ast_manager_register2 to register with help text for new manager commands */
114
115 /*! Register a manager command with the manager interface */
116 /*!     \param action Name of the requested Action:
117         \param authority Required authority for this command
118         \param func Function to call for this command
119         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
120         \param description Help text, several lines
121 */
122 int ast_manager_register2( 
123         const char *action, 
124         int authority, 
125         int (*func)(struct mansession *s, struct message *m), 
126         const char *synopsis,
127         const char *description);
128
129 /*! Unregister a registred manager command */
130 /*!     \param action Name of registred Action:
131 */
132 int ast_manager_unregister( char *action );
133
134 /*! External routines may send asterisk manager events this way */
135 /*!     \param category Event category, matches manager authorization
136         \param event    Event name
137         \param contents Contents of event
138 */ 
139 extern int manager_event(int category, char *event, char *contents, ...)
140         __attribute__ ((format (printf, 3,4)));
141
142 /*! Get header from mananger transaction */
143 extern char *astman_get_header(struct message *m, char *var);
144 /*! Send error in manager transaction */
145 extern void astman_send_error(struct mansession *s, struct message *m, char *error);
146 extern void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
147 extern void astman_send_ack(struct mansession *s, struct message *m, char *msg);
148
149 /*! Called by Asterisk initialization */
150 extern int init_manager(void);
151 /*! Called by Asterisk initialization */
152 extern int reload_manager(void);
153 #endif