make datastore creation and destruction a generic API since it is not really channel...
[asterisk/asterisk.git] / include / asterisk / manager.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _ASTERISK_MANAGER_H
20 #define _ASTERISK_MANAGER_H
21
22 #include "asterisk/network.h"
23 #include "asterisk/lock.h"
24 #include "asterisk/datastore.h"
25
26 /*!
27  \file
28  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
29  manage Asterisk with third-party software.
30
31  Manager protocol packages are text fields of the form a: b.  There is
32  always exactly one space after the colon.
33
34 \verbatim
35
36  For Actions replies, the first line of the reply is a "Response:" header with
37  values "success", "error" or "follows". "Follows" implies that the
38  response is coming as separate events with the same ActionID. If the
39  Action request has no ActionID, it will be hard matching events
40  to the Action request in the manager client.
41
42  The first header type is the "Event" header.  Other headers vary from
43  event to event.  Headers end with standard \\r\\n termination.
44  The last line of the manager response or event is an empty line.
45  (\\r\\n)
46
47 \endverbatim
48
49  \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients.
50     Don't re-use an existing header with a new meaning, please.
51     You can find a reference of standard headers in doc/manager.txt
52
53 - \ref manager.c Main manager code file
54  */
55
56 #define AMI_VERSION                     "1.1"
57 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
58
59 /*! \name Manager event classes */
60 /*@{ */
61 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
62 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
63 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
64 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
65 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
66 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
67 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
68 #define EVENT_FLAG_CONFIG               (1 << 7) /* Ability to modify configurations */
69 #define EVENT_FLAG_DTMF                 (1 << 8) /* Ability to read DTMF events */
70 #define EVENT_FLAG_REPORTING            (1 << 9) /* Reporting events such as rtcp sent */
71 #define EVENT_FLAG_CDR                  (1 << 10) /* CDR events */
72 #define EVENT_FLAG_DIALPLAN             (1 << 11) /* Dialplan events (VarSet, NewExten) */
73 #define EVENT_FLAG_ORIGINATE    (1 << 12) /* Originate a call to an extension */
74 /*@} */
75
76 /*! \brief Export manager structures */
77 #define AST_MAX_MANHEADERS 128
78
79 /*! \brief Manager Helper Function */
80 typedef int (*manager_hook_t)(int, const char *, char *); 
81
82
83 struct manager_custom_hook {
84         /*! Identifier */
85         char *file;
86         /*! helper function */
87         manager_hook_t helper;
88         /*! Linked list information */
89         AST_RWLIST_ENTRY(manager_custom_hook) list;
90 };
91
92 /*! \brief Check if AMI is enabled */
93 int check_manager_enabled(void);
94
95 /*! \brief Check if AMI/HTTP is enabled */
96 int check_webmanager_enabled(void);
97
98 /*! Add a custom hook to be called when an event is fired 
99  \param hook struct manager_custom_hook object to add
100 */
101 void ast_manager_register_hook(struct manager_custom_hook *hook);
102
103 /*! Delete a custom hook to be called when an event is fired
104     \param hook struct manager_custom_hook object to delete
105 */
106 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
107
108 struct mansession;
109
110 struct message {
111         unsigned int hdrcount;
112         const char *headers[AST_MAX_MANHEADERS];
113 };
114
115 struct manager_action {
116         /*! Name of the action */
117         const char *action;
118         /*! Short description of the action */
119         const char *synopsis;
120         /*! Detailed description of the action */
121         const char *description;
122         /*! Permission required for action.  EVENT_FLAG_* */
123         int authority;
124         /*! Function to be called */
125         int (*func)(struct mansession *s, const struct message *m);
126         /*! For easy linking */
127         AST_RWLIST_ENTRY(manager_action) list;
128 };
129
130 /*! \brief External routines may register/unregister manager callbacks this way 
131  * \note  Use ast_manager_register2() to register with help text for new manager commands */
132 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
133
134
135 /*! \brief Register a manager command with the manager interface 
136         \param action Name of the requested Action:
137         \param authority Required authority for this command
138         \param func Function to call for this command
139         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
140         \param description Help text, several lines
141 */
142 int ast_manager_register2(
143         const char *action,
144         int authority,
145         int (*func)(struct mansession *s, const struct message *m),
146         const char *synopsis,
147         const char *description);
148
149 /*! \brief Unregister a registred manager command 
150         \param action Name of registred Action:
151 */
152 int ast_manager_unregister( char *action );
153
154 /*! 
155  * \brief Verify a session's read permissions against a permission mask.  
156  * \param ident session identity
157  * \param perm permission mask to verify
158  * \retval 1 if the session has the permission mask capabilities
159  * \retval 0 otherwise
160  */
161 int astman_verify_session_readpermissions(uint32_t ident, int perm);
162
163 /*!
164  * \brief Verify a session's write permissions against a permission mask.  
165  * \param ident session identity
166  * \param perm permission mask to verify
167  * \retval 1 if the session has the permission mask capabilities, otherwise 0
168  * \retval 0 otherwise
169  */
170 int astman_verify_session_writepermissions(uint32_t ident, int perm);
171
172 /*! \brief External routines may send asterisk manager events this way 
173  *      \param category Event category, matches manager authorization
174         \param event    Event name
175         \param contents Contents of event
176 */
177
178 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
179  * between the last arg before VA_ARGS and the comma */
180 #define manager_event(category, event, contents , ...)  \
181         __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
182
183 int __attribute__ ((format(printf, 6, 7))) __manager_event(int category, const char *event,
184                                                            const char *file, int line, const char *func,
185                                                            const char *contents, ...);
186
187 /*! \brief Get header from mananger transaction */
188 const char *astman_get_header(const struct message *m, char *var);
189
190 /*! \brief Get a linked list of the Variable: headers */
191 struct ast_variable *astman_get_variables(const struct message *m);
192
193 /*! \brief Send error in manager transaction */
194 void astman_send_error(struct mansession *s, const struct message *m, char *error);
195
196 /*! \brief Send response in manager transaction */
197 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
198
199 /*! \brief Send ack in manager transaction */
200 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
201
202 /*! \brief Send ack in manager list transaction */
203 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
204
205 void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
206
207 /*! \brief Determinie if a manager session ident is authenticated */
208 int astman_is_authed(uint32_t ident);
209
210 /*! \brief Called by Asterisk initialization */
211 int init_manager(void);
212
213 /*! \brief Called by Asterisk module functions and the CLI command */
214 int reload_manager(void);
215
216 /*! 
217  * \brief Add a datastore to a session
218  *
219  * \retval 0 success
220  * \retval non-zero failure
221  */
222
223 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
224
225 /*! 
226  * \brief Remove a datastore from a session
227  *
228  * \retval 0 success
229  * \retval non-zero failure
230  */
231 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
232
233 /*! 
234  * \brief Find a datastore on a session
235  *
236  * \retval pointer to the datastore if found
237  * \retval NULL if not found
238  */
239 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
240
241 #endif /* _ASTERISK_MANAGER_H */