Fix sip show peers port output, align columns, and fix ami port output.
[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 #include "asterisk/xmldoc.h"
26
27 /*!
28  \file
29  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
30  manage Asterisk with third-party software.
31
32  Manager protocol packages are text fields of the form a: b.  There is
33  always exactly one space after the colon.
34
35 \verbatim
36
37  For Actions replies, the first line of the reply is a "Response:" header with
38  values "success", "error" or "follows". "Follows" implies that the
39  response is coming as separate events with the same ActionID. If the
40  Action request has no ActionID, it will be hard matching events
41  to the Action request in the manager client.
42
43  The first header type is the "Event" header.  Other headers vary from
44  event to event.  Headers end with standard \\r\\n termination.
45  The last line of the manager response or event is an empty line.
46  (\\r\\n)
47
48 \endverbatim
49
50  \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients.
51     Don't re-use an existing header with a new meaning, please.
52     You can find a reference of standard headers in doc/manager.txt
53
54 - \ref manager.c Main manager code file
55  */
56
57 #define AMI_VERSION                     "1.2"
58 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
59
60 /*! \name Constant return values
61  *\note Currently, returning anything other than zero causes the session to terminate.
62  */
63 /*@{ */
64 #define AMI_SUCCESS     (0)
65 #define AMI_DESTROY     (-1)
66 /*@} */
67
68 /*! \name Manager event classes */
69 /*@{ */
70 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
71 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
72 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
73 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
74 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
75 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
76 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
77 #define EVENT_FLAG_CONFIG               (1 << 7) /* Ability to modify configurations */
78 #define EVENT_FLAG_DTMF                 (1 << 8) /* Ability to read DTMF events */
79 #define EVENT_FLAG_REPORTING            (1 << 9) /* Reporting events such as rtcp sent */
80 #define EVENT_FLAG_CDR                  (1 << 10) /* CDR events */
81 #define EVENT_FLAG_DIALPLAN             (1 << 11) /* Dialplan events (VarSet, NewExten) */
82 #define EVENT_FLAG_ORIGINATE    (1 << 12) /* Originate a call to an extension */
83 #define EVENT_FLAG_AGI                  (1 << 13) /* AGI events */
84 #define EVENT_FLAG_HOOKRESPONSE         (1 << 14) /* Hook Response */
85 #define EVENT_FLAG_CC                   (1 << 15) /* Call Completion events */
86 #define EVENT_FLAG_AOC                  (1 << 16) /* Advice Of Charge events */
87 #define EVENT_FLAG_TEST                 (1 << 17) /* Test event used to signal the Asterisk Test Suite */
88 /*@} */
89
90 /*! \brief Export manager structures */
91 #define AST_MAX_MANHEADERS 128
92
93 /*! \brief Manager Helper Function */
94 typedef int (*manager_hook_t)(int, const char *, char *);
95
96 struct manager_custom_hook {
97         /*! Identifier */
98         char *file;
99         /*! helper function */
100         manager_hook_t helper;
101         /*! Linked list information */
102         AST_RWLIST_ENTRY(manager_custom_hook) list;
103 };
104
105 /*! \brief Check if AMI is enabled */
106 int check_manager_enabled(void);
107
108 /*! \brief Check if AMI/HTTP is enabled */
109 int check_webmanager_enabled(void);
110
111 /*! Add a custom hook to be called when an event is fired 
112  \param hook struct manager_custom_hook object to add
113 */
114 void ast_manager_register_hook(struct manager_custom_hook *hook);
115
116 /*! Delete a custom hook to be called when an event is fired
117     \param hook struct manager_custom_hook object to delete
118 */
119 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
120
121 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback
122  * \param hook the file identifier specified in manager_custom_hook struct when registering a hook
123  * \param msg ami action mesage string e.g. "Action: SipPeers\r\n"
124
125  * \retval 0 on Success
126  * \retval non-zero on Failure
127 */
128 int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg);
129
130 struct mansession;
131
132 struct message {
133         unsigned int hdrcount;
134         const char *headers[AST_MAX_MANHEADERS];
135 };
136
137 struct manager_action {
138         /*! Name of the action */
139         const char *action;
140         AST_DECLARE_STRING_FIELDS(
141                 AST_STRING_FIELD(synopsis);     /*!< Synopsis text (short description). */
142                 AST_STRING_FIELD(description);  /*!< Description (help text) */
143                 AST_STRING_FIELD(syntax);       /*!< Syntax text */
144                 AST_STRING_FIELD(arguments);    /*!< Description of each argument. */
145                 AST_STRING_FIELD(seealso);      /*!< See also */
146         );
147         /*! Permission required for action.  EVENT_FLAG_* */
148         int authority;
149         /*! Function to be called */
150         int (*func)(struct mansession *s, const struct message *m);
151         /*! Where the documentation come from. */
152         enum ast_doc_src docsrc;
153         /*! For easy linking */
154         AST_RWLIST_ENTRY(manager_action) list;
155         /*!
156          * \brief TRUE if the AMI action is registered and the callback can be called.
157          *
158          * \note Needed to prevent a race between calling the callback
159          * function and unregestring the AMI action object.
160          */
161         unsigned int registered:1;
162 };
163
164 /*! \brief External routines may register/unregister manager callbacks this way 
165  * \note  Use ast_manager_register2() to register with help text for new manager commands */
166 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
167
168 /*! \brief Register a manager callback using XML documentation to describe the manager. */
169 #define ast_manager_register_xml(a, b, c) ast_manager_register2(a, b, c, NULL, NULL)
170
171 /*! \brief Register a manager command with the manager interface 
172         \param action Name of the requested Action:
173         \param authority Required authority for this command
174         \param func Function to call for this command
175         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
176         \param description Help text, several lines
177 */
178 int ast_manager_register2(
179         const char *action,
180         int authority,
181         int (*func)(struct mansession *s, const struct message *m),
182         const char *synopsis,
183         const char *description);
184
185 /*! \brief Unregister a registered manager command 
186         \param action Name of registered Action:
187 */
188 int ast_manager_unregister( char *action );
189
190 /*! 
191  * \brief Verify a session's read permissions against a permission mask.  
192  * \param ident session identity
193  * \param perm permission mask to verify
194  * \retval 1 if the session has the permission mask capabilities
195  * \retval 0 otherwise
196  */
197 int astman_verify_session_readpermissions(uint32_t ident, int perm);
198
199 /*!
200  * \brief Verify a session's write permissions against a permission mask.  
201  * \param ident session identity
202  * \param perm permission mask to verify
203  * \retval 1 if the session has the permission mask capabilities, otherwise 0
204  * \retval 0 otherwise
205  */
206 int astman_verify_session_writepermissions(uint32_t ident, int perm);
207
208 /*! \brief External routines may send asterisk manager events this way 
209  *      \param category Event category, matches manager authorization
210         \param event    Event name
211         \param contents Contents of event
212 */
213
214 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
215  * between the last arg before VA_ARGS and the comma */
216 #define manager_event(category, event, contents , ...)  \
217         __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
218 #define ast_manager_event(chan, category, event, contents , ...) \
219         do { \
220                 struct ast_channel *_chans[] = { chan, }; \
221                 __ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \
222         } while (0)
223 #define ast_manager_event_multichan(category, event, nchans, chans, contents , ...) \
224         __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
225
226 /*! External routines may send asterisk manager events this way
227  * \param category Event category, matches manager authorization
228  * \param event Event name
229  * \param chancount Number of channels in chans parameter
230  * \param chans A pointer to an array of channels involved in the event
231  * \param contents Format string describing event
232  * \since 1.8
233 */
234 int __ast_manager_event_multichan(int category, const char *event, int chancount,
235                 struct ast_channel **chans, const char *file, int line, const char *func,
236                 const char *contents, ...) __attribute__((format(printf, 8, 9)));
237
238 /*! \brief Get header from mananger transaction */
239 const char *astman_get_header(const struct message *m, char *var);
240
241 /*! \brief Get a linked list of the Variable: headers */
242 struct ast_variable *astman_get_variables(const struct message *m);
243
244 /*! \brief Send error in manager transaction */
245 void astman_send_error(struct mansession *s, const struct message *m, char *error);
246
247 /*! \brief Send response in manager transaction */
248 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
249
250 /*! \brief Send ack in manager transaction */
251 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
252
253 /*! \brief Send ack in manager list transaction */
254 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
255
256 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
257
258 /*! \brief Determinie if a manager session ident is authenticated */
259 int astman_is_authed(uint32_t ident);
260
261 /*! \brief Called by Asterisk initialization */
262 int init_manager(void);
263
264 /*! \brief Called by Asterisk module functions and the CLI command */
265 int reload_manager(void);
266
267 /*! 
268  * \brief Add a datastore to a session
269  *
270  * \retval 0 success
271  * \retval non-zero failure
272  * \since 1.6.1
273  */
274
275 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
276
277 /*! 
278  * \brief Remove a datastore from a session
279  *
280  * \retval 0 success
281  * \retval non-zero failure
282  * \since 1.6.1
283  */
284 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
285
286 /*! 
287  * \brief Find a datastore on a session
288  *
289  * \retval pointer to the datastore if found
290  * \retval NULL if not found
291  * \since 1.6.1
292  */
293 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
294
295 #endif /* _ASTERISK_MANAGER_H */