Migrate a large number of AMI events over to Stasis-Core
[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.4"
58 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
59 #define DEFAULT_MANAGER_TLS_PORT 5039   /* Default port for Asterisk management via TCP */
60
61 /*! \name Constant return values
62  *\note Currently, returning anything other than zero causes the session to terminate.
63  */
64 /*@{ */
65 #define AMI_SUCCESS     (0)
66 #define AMI_DESTROY     (-1)
67 /*@} */
68
69 /*! \name Manager event classes */
70 /*@{ */
71 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
72 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
73 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
74 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
75 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
76 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
77 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
78 #define EVENT_FLAG_CONFIG               (1 << 7) /* Ability to modify configurations */
79 #define EVENT_FLAG_DTMF                 (1 << 8) /* Ability to read DTMF events */
80 #define EVENT_FLAG_REPORTING            (1 << 9) /* Reporting events such as rtcp sent */
81 #define EVENT_FLAG_CDR                  (1 << 10) /* CDR events */
82 #define EVENT_FLAG_DIALPLAN             (1 << 11) /* Dialplan events (VarSet, NewExten) */
83 #define EVENT_FLAG_ORIGINATE    (1 << 12) /* Originate a call to an extension */
84 #define EVENT_FLAG_AGI                  (1 << 13) /* AGI events */
85 #define EVENT_FLAG_HOOKRESPONSE         (1 << 14) /* Hook Response */
86 #define EVENT_FLAG_CC                   (1 << 15) /* Call Completion events */
87 #define EVENT_FLAG_AOC                  (1 << 16) /* Advice Of Charge events */
88 #define EVENT_FLAG_TEST                 (1 << 17) /* Test event used to signal the Asterisk Test Suite */
89 /*XXX Why shifted by 30? XXX */
90 #define EVENT_FLAG_MESSAGE              (1 << 30) /* MESSAGE events. */
91 /*@} */
92
93 /*! \brief Export manager structures */
94 #define AST_MAX_MANHEADERS 128
95
96 /*! \brief Manager Helper Function */
97 typedef int (*manager_hook_t)(int, const char *, char *);
98
99 struct manager_custom_hook {
100         /*! Identifier */
101         char *file;
102         /*! helper function */
103         manager_hook_t helper;
104         /*! Linked list information */
105         AST_RWLIST_ENTRY(manager_custom_hook) list;
106 };
107
108 /*! \brief Check if AMI is enabled */
109 int check_manager_enabled(void);
110
111 /*! \brief Check if AMI/HTTP is enabled */
112 int check_webmanager_enabled(void);
113
114 /*! Add a custom hook to be called when an event is fired 
115  \param hook struct manager_custom_hook object to add
116 */
117 void ast_manager_register_hook(struct manager_custom_hook *hook);
118
119 /*! Delete a custom hook to be called when an event is fired
120     \param hook struct manager_custom_hook object to delete
121 */
122 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
123
124 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback
125  * \param hook the file identifier specified in manager_custom_hook struct when registering a hook
126  * \param msg ami action mesage string e.g. "Action: SipPeers\r\n"
127
128  * \retval 0 on Success
129  * \retval non-zero on Failure
130 */
131 int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg);
132
133 struct mansession;
134
135 struct message {
136         unsigned int hdrcount;
137         const char *headers[AST_MAX_MANHEADERS];
138 };
139
140 struct manager_action {
141         /*! Name of the action */
142         const char *action;
143         AST_DECLARE_STRING_FIELDS(
144                 AST_STRING_FIELD(synopsis);     /*!< Synopsis text (short description). */
145                 AST_STRING_FIELD(description);  /*!< Description (help text) */
146                 AST_STRING_FIELD(syntax);       /*!< Syntax text */
147                 AST_STRING_FIELD(arguments);    /*!< Description of each argument. */
148                 AST_STRING_FIELD(seealso);      /*!< See also */
149         );
150         /*! Permission required for action.  EVENT_FLAG_* */
151         int authority;
152         /*! Function to be called */
153         int (*func)(struct mansession *s, const struct message *m);
154         struct ast_module *module;              /*!< Module this action belongs to */
155         /*! Where the documentation come from. */
156         enum ast_doc_src docsrc;
157         /*! For easy linking */
158         AST_RWLIST_ENTRY(manager_action) list;
159         /*!
160          * \brief TRUE if the AMI action is registered and the callback can be called.
161          *
162          * \note Needed to prevent a race between calling the callback
163          * function and unregestring the AMI action object.
164          */
165         unsigned int registered:1;
166 };
167
168 /*! \brief External routines may register/unregister manager callbacks this way 
169  * \note  Use ast_manager_register2() to register with help text for new manager commands */
170 #define ast_manager_register(action, authority, func, synopsis) ast_manager_register2(action, authority, func, ast_module_info->self, synopsis, NULL)
171
172 /*! \brief Register a manager callback using XML documentation to describe the manager. */
173 #define ast_manager_register_xml(action, authority, func) ast_manager_register2(action, authority, func, ast_module_info->self, NULL, NULL)
174
175 /*!
176  * \brief Register a manager callback using XML documentation to describe the manager.
177  *
178  * \note For Asterisk core modules that are not independently
179  * loadable.
180  *
181  * \warning If you use ast_manager_register_xml() instead when
182  * you need to use this function, Asterisk will crash on load.
183  */
184 #define ast_manager_register_xml_core(action, authority, func) ast_manager_register2(action, authority, func, NULL, NULL, NULL)
185
186 /*!
187  * \brief Register a manager command with the manager interface
188  * \param action Name of the requested Action:
189  * \param authority Required authority for this command
190  * \param func Function to call for this command
191  * \param module The module containing func.  (NULL if module is part of core and not loadable)
192  * \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
193  * \param description Help text, several lines
194  */
195 int ast_manager_register2(
196         const char *action,
197         int authority,
198         int (*func)(struct mansession *s, const struct message *m),
199         struct ast_module *module,
200         const char *synopsis,
201         const char *description);
202
203 /*!
204  * \brief Unregister a registered manager command
205  * \param action Name of registered Action:
206  */
207 int ast_manager_unregister(const char *action);
208
209 /*! 
210  * \brief Verify a session's read permissions against a permission mask.  
211  * \param ident session identity
212  * \param perm permission mask to verify
213  * \retval 1 if the session has the permission mask capabilities
214  * \retval 0 otherwise
215  */
216 int astman_verify_session_readpermissions(uint32_t ident, int perm);
217
218 /*!
219  * \brief Verify a session's write permissions against a permission mask.  
220  * \param ident session identity
221  * \param perm permission mask to verify
222  * \retval 1 if the session has the permission mask capabilities, otherwise 0
223  * \retval 0 otherwise
224  */
225 int astman_verify_session_writepermissions(uint32_t ident, int perm);
226
227 /*! \brief External routines may send asterisk manager events this way 
228  *      \param category Event category, matches manager authorization
229         \param event    Event name
230         \param contents Contents of event
231 */
232
233 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
234  * between the last arg before VA_ARGS and the comma */
235 #define manager_event(category, event, contents , ...)  \
236         __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
237 #define ast_manager_event(chan, category, event, contents , ...) \
238         do { \
239                 struct ast_channel *_chans[] = { chan, }; \
240                 __ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \
241         } while (0)
242 #define ast_manager_event_multichan(category, event, nchans, chans, contents , ...) \
243         __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
244
245 /*! External routines may send asterisk manager events this way
246  * \param category Event category, matches manager authorization
247  * \param event Event name
248  * \param chancount Number of channels in chans parameter
249  * \param chans A pointer to an array of channels involved in the event
250  * \param file, line, func
251  * \param contents Format string describing event
252  * \param ...
253  * \since 1.8
254 */
255 int __ast_manager_event_multichan(int category, const char *event, int chancount,
256                 struct ast_channel **chans, const char *file, int line, const char *func,
257                 const char *contents, ...) __attribute__((format(printf, 8, 9)));
258
259 /*! \brief Get header from mananger transaction */
260 const char *astman_get_header(const struct message *m, char *var);
261
262 /*! \brief Get a linked list of the Variable: headers */
263 struct ast_variable *astman_get_variables(const struct message *m);
264
265 /*! \brief Send error in manager transaction */
266 void astman_send_error(struct mansession *s, const struct message *m, char *error);
267
268 /*! \brief Send error in manager transaction (with va_args support) */
269 void __attribute__((format(printf, 3, 4))) astman_send_error_va(struct mansession *s, const struct message *m, const char *fmt, ...);
270
271 /*! \brief Send response in manager transaction */
272 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
273
274 /*! \brief Send ack in manager transaction */
275 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
276
277 /*! \brief Send ack in manager list transaction */
278 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
279
280 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
281
282 /*! \brief Determinie if a manager session ident is authenticated */
283 int astman_is_authed(uint32_t ident);
284
285 /*! \brief Called by Asterisk initialization */
286 int init_manager(void);
287
288 /*! \brief Called by Asterisk module functions and the CLI command */
289 int reload_manager(void);
290
291 /*! 
292  * \brief Add a datastore to a session
293  *
294  * \retval 0 success
295  * \retval non-zero failure
296  * \since 1.6.1
297  */
298
299 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
300
301 /*! 
302  * \brief Remove a datastore from a session
303  *
304  * \retval 0 success
305  * \retval non-zero failure
306  * \since 1.6.1
307  */
308 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
309
310 /*! 
311  * \brief Find a datastore on a session
312  *
313  * \retval pointer to the datastore if found
314  * \retval NULL if not found
315  * \since 1.6.1
316  */
317 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
318
319 /*! \brief Struct representing a snapshot of channel state */
320 struct ast_channel_snapshot;
321
322 /*!
323  * \brief Generate the AMI message body from a channel snapshot
324  * \since 12
325  *
326  * \param snapshot the channel snapshot for which to generate an AMI message
327  *                 body
328  * \param suffix the suffix to append to the channel fields
329  *
330  * \retval NULL on error
331  * \retval ast_str* on success (must be ast_freed by caller)
332  */
333 struct ast_str *ast_manager_build_channel_state_string_prefix(
334                 const struct ast_channel_snapshot *snapshot,
335                 const char *suffix);
336
337 /*!
338  * \brief Generate the AMI message body from a channel snapshot
339  * \since 12
340  *
341  * \param snapshot the channel snapshot for which to generate an AMI message
342  *                 body
343  *
344  * \retval NULL on error
345  * \retval ast_str* on success (must be ast_freed by caller)
346  */
347 struct ast_str *ast_manager_build_channel_state_string(
348                 const struct ast_channel_snapshot *snapshot);
349
350 /*! \brief Struct representing a snapshot of bridge state */
351 struct ast_bridge_snapshot;
352
353 /*!
354  * \since 12
355  * \brief Callback used to determine whether a key should be skipped when converting a
356  *  JSON object to a manager blob
357  * \param key Key from JSON blob to be evaluated
358  * \retval non-zero if the key should be excluded
359  * \retval zero if the key should not be excluded
360  */
361 typedef int (*key_exclusion_cb)(const char *key);
362
363 struct ast_json;
364
365 /*!
366  * \since 12
367  * \brief Convert a JSON object into an AMI compatible string
368  *
369  * \param blob The JSON blob containing key/value pairs to convert
370  * \param exclusion_cb A \ref key_exclusion_cb pointer to a function that will exclude
371  * keys from the final AMI string
372  *
373  * \retval A malloc'd \ref ast_str object. Callers of this function should free
374  * the returned \ref ast_str object
375  * \retval NULL on error
376  */
377 struct ast_str *ast_manager_str_from_json_object(struct ast_json *blob, key_exclusion_cb exclusion_cb);
378
379 /*!
380  * \brief Generate the AMI message body from a bridge snapshot
381  * \since 12
382  *
383  * \param snapshot the bridge snapshot for which to generate an AMI message
384  *                 body
385  *
386  * \retval NULL on error
387  * \retval ast_str* on success (must be ast_freed by caller)
388  */
389 struct ast_str *ast_manager_build_bridge_state_string(
390         const struct ast_bridge_snapshot *snapshot,
391         const char *suffix);
392
393 /*! \brief Struct containing info for an AMI event to send out. */
394 struct ast_manager_event_blob {
395         int event_flags;                /*!< Flags the event should be raised with. */
396         const char *manager_event;      /*!< The event to be raised, should be a string literal. */
397         AST_DECLARE_STRING_FIELDS(
398                 AST_STRING_FIELD(extra_fields); /*!< Extra fields to include in the event. */
399         );
400 };
401
402 /*!
403  * \since 12
404  * \brief Construct a \ref snapshot_manager_event.
405  *
406  * \param event_flags Flags the event should be raised with.
407  * \param manager_event The event to be raised, should be a string literal.
408  * \param extra_fields_fmt Format string for extra fields to include.
409  *                         Or NO_EXTRA_FIELDS for no extra fields.
410  *
411  * \return New \ref ast_manager_snapshot_event object.
412  * \return \c NULL on error.
413  */
414 struct ast_manager_event_blob *
415 __attribute__((format(printf, 3, 4)))
416 ast_manager_event_blob_create(
417         int event_flags,
418         const char *manager_event,
419         const char *extra_fields_fmt,
420         ...);
421
422 /*! GCC warns about blank or NULL format strings. So, shenanigans! */
423 #define NO_EXTRA_FIELDS "%s", ""
424
425 /*!
426  * \brief Initialize support for AMI channel events.
427  * \retval 0 on success.
428  * \retval non-zero on error.
429  * \since 12
430  */
431 int manager_channels_init(void);
432
433 /*!
434  * \since 12
435  * \brief Initialize support for AMI MWI events.
436  * \retval 0 on success
437  * \retval non-zero on error
438  */
439 int manager_mwi_init(void);
440
441 /*!
442  * \brief Initialize support for AMI channel events.
443  * \return 0 on success.
444  * \return non-zero on error.
445  * \since 12
446  */
447 int manager_bridging_init(void);
448
449 /*!
450  * \since 12
451  * \brief Get the \ref stasis_message_type for generic messages
452  *
453  * A generic AMI message expects a JSON only payload. The payload must have the following
454  * structure:
455  * {type: s, class_type: i, event: [ {s: s}, ...] }
456  *
457  * - type is the AMI event type
458  * - class_type is the class authorization type for the event
459  * - event is a list of key/value tuples to be sent out in the message
460  *
461  * \retval A \ref stasis_message_type for AMI messages
462  */
463 struct stasis_message_type *ast_manager_get_generic_type(void);
464
465 /*!
466  * \since 12
467  * \brief Get the \ref stasis topic for AMI
468  *
469  * \retval The \ref stasis topic for AMI
470  * \retval NULL on error
471  */
472 struct stasis_topic *ast_manager_get_topic(void);
473
474 struct ast_json;
475
476 /*!
477  * \since 12
478  * \brief Publish a generic \ref stasis_message_type to the \ref stasis_topic for AMI
479  *
480  * Publishes a message to the \ref stasis message bus solely for the consumption of AMI.
481  * The message will be of the type provided by \ref ast_manager_get_type, and will be
482  * published to the topic provided by \ref ast_manager_get_topic. As such, the JSON must
483  * be constructed as defined by the \ref ast_manager_get_type message.
484  *
485  * \retval 0 on success
486  * \retval -1 on failure
487  */
488 int ast_manager_publish_message(struct ast_json *json);
489
490 /*!
491  * \since 12
492  * \brief Get the \ref stasis_message_router for AMI
493  *
494  * \retval The \ref stasis_message_router for AMI
495  * \retval NULL on error
496  */
497 struct stasis_message_router *ast_manager_get_message_router(void);
498
499 #endif /* _ASTERISK_MANAGER_H */