CLI: Create ast_cli_completion_vector.
[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                     "4.0.0"
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 #define EVENT_FLAG_SECURITY         (1 << 18) /* Security Message as AMI Event */
90 /*XXX Why shifted by 30? XXX */
91 #define EVENT_FLAG_MESSAGE          (1 << 30) /* MESSAGE events. */
92 /*@} */
93
94 /*! \brief Export manager structures */
95 #define AST_MAX_MANHEADERS 128
96
97 /*! \brief Manager Helper Function
98  *
99  * \param category The class authorization category of the event
100  * \param event The name of the event being raised
101  * \param body The body of the event
102  *
103  * \retval 0 Success
104  * \retval non-zero Error
105  */
106 typedef int (*manager_hook_t)(int category, const char *event, char *body);
107
108 struct manager_custom_hook {
109         /*! Identifier */
110         char *file;
111         /*! helper function */
112         manager_hook_t helper;
113         /*! Linked list information */
114         AST_RWLIST_ENTRY(manager_custom_hook) list;
115 };
116
117 /*! \brief Check if AMI is enabled */
118 int check_manager_enabled(void);
119
120 /*! \brief Check if AMI/HTTP is enabled */
121 int check_webmanager_enabled(void);
122
123 /*! Add a custom hook to be called when an event is fired 
124  \param hook struct manager_custom_hook object to add
125 */
126 void ast_manager_register_hook(struct manager_custom_hook *hook);
127
128 /*! Delete a custom hook to be called when an event is fired
129     \param hook struct manager_custom_hook object to delete
130 */
131 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
132
133 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback
134  * \param hook the file identifier specified in manager_custom_hook struct when registering a hook
135  * \param msg ami action mesage string e.g. "Action: SipPeers\r\n"
136
137  * \retval 0 on Success
138  * \retval non-zero on Failure
139 */
140 int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg);
141
142 struct mansession;
143
144 struct message {
145         unsigned int hdrcount;
146         const char *headers[AST_MAX_MANHEADERS];
147 };
148
149 struct manager_action {
150         /*! Name of the action */
151         const char *action;
152         AST_DECLARE_STRING_FIELDS(
153                 AST_STRING_FIELD(synopsis);     /*!< Synopsis text (short description). */
154                 AST_STRING_FIELD(description);  /*!< Description (help text) */
155                 AST_STRING_FIELD(syntax);       /*!< Syntax text */
156                 AST_STRING_FIELD(arguments);    /*!< Description of each argument. */
157                 AST_STRING_FIELD(seealso);      /*!< See also */
158         );
159         /*! Possible list element response events. */
160         struct ast_xml_doc_item *list_responses;
161         /*! Final response event. */
162         struct ast_xml_doc_item *final_response;
163         /*! Permission required for action.  EVENT_FLAG_* */
164         int authority;
165         /*! Function to be called */
166         int (*func)(struct mansession *s, const struct message *m);
167         struct ast_module *module;              /*!< Module this action belongs to */
168         /*! Where the documentation come from. */
169         enum ast_doc_src docsrc;
170         /*! For easy linking */
171         AST_RWLIST_ENTRY(manager_action) list;
172         /*!
173          * \brief TRUE if the AMI action is registered and the callback can be called.
174          *
175          * \note Needed to prevent a race between calling the callback
176          * function and unregestring the AMI action object.
177          */
178         unsigned int registered:1;
179 };
180
181 /*! \brief External routines may register/unregister manager callbacks this way 
182  * \note  Use ast_manager_register2() to register with help text for new manager commands */
183 #define ast_manager_register(action, authority, func, synopsis) ast_manager_register2(action, authority, func, AST_MODULE_SELF, synopsis, NULL)
184
185 /*! \brief Register a manager callback using XML documentation to describe the manager. */
186 #define ast_manager_register_xml(action, authority, func) ast_manager_register2(action, authority, func, AST_MODULE_SELF, NULL, NULL)
187
188 /*!
189  * \brief Register a manager callback using XML documentation to describe the manager.
190  *
191  * \note For Asterisk core modules that are not independently
192  * loadable.
193  *
194  * \warning If you use ast_manager_register_xml() instead when
195  * you need to use this function, Asterisk will crash on load.
196  */
197 #define ast_manager_register_xml_core(action, authority, func) ast_manager_register2(action, authority, func, NULL, NULL, NULL)
198
199 /*!
200  * \brief Register a manager command with the manager interface
201  * \param action Name of the requested Action:
202  * \param authority Required authority for this command
203  * \param func Function to call for this command
204  * \param module The module containing func.  (NULL if module is part of core and not loadable)
205  * \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
206  * \param description Help text, several lines
207  */
208 int ast_manager_register2(
209         const char *action,
210         int authority,
211         int (*func)(struct mansession *s, const struct message *m),
212         struct ast_module *module,
213         const char *synopsis,
214         const char *description);
215
216 /*!
217  * \brief Unregister a registered manager command
218  * \param action Name of registered Action:
219  */
220 int ast_manager_unregister(const char *action);
221
222 /*! 
223  * \brief Verify a session's read permissions against a permission mask.  
224  * \param ident session identity
225  * \param perm permission mask to verify
226  * \retval 1 if the session has the permission mask capabilities
227  * \retval 0 otherwise
228  */
229 int astman_verify_session_readpermissions(uint32_t ident, int perm);
230
231 /*!
232  * \brief Verify a session's write permissions against a permission mask.  
233  * \param ident session identity
234  * \param perm permission mask to verify
235  * \retval 1 if the session has the permission mask capabilities, otherwise 0
236  * \retval 0 otherwise
237  */
238 int astman_verify_session_writepermissions(uint32_t ident, int perm);
239
240 /*! \brief External routines may send asterisk manager events this way 
241  *      \param category Event category, matches manager authorization
242         \param event    Event name
243         \param contents Contents of event
244 */
245
246 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
247  * between the last arg before VA_ARGS and the comma */
248 #define manager_event(category, event, contents , ...)  \
249         __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
250 #define ast_manager_event(chan, category, event, contents , ...) \
251         do { \
252                 struct ast_channel *_chans[] = { chan, }; \
253                 __ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \
254         } while (0)
255 #define ast_manager_event_multichan(category, event, nchans, chans, contents , ...) \
256         __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
257
258 /*! External routines may send asterisk manager events this way
259  * \param category Event category, matches manager authorization
260  * \param event Event name
261  * \param chancount Number of channels in chans parameter
262  * \param chans A pointer to an array of channels involved in the event
263  * \param file, line, func
264  * \param contents Format string describing event
265  * \param ...
266  * \since 1.8
267 */
268 int __ast_manager_event_multichan(int category, const char *event, int chancount,
269                 struct ast_channel **chans, const char *file, int line, const char *func,
270                 const char *contents, ...) __attribute__((format(printf, 8, 9)));
271
272 /*! \brief Get header from mananger transaction */
273 const char *astman_get_header(const struct message *m, char *var);
274
275 /*! \brief Get a linked list of the Variable: headers
276  *
277  *  \note Order of variables is reversed from the order they are specified in
278  *        the manager message
279  */
280 struct ast_variable *astman_get_variables(const struct message *m);
281
282 enum variable_orders {
283         ORDER_NATURAL,
284         ORDER_REVERSE
285 };
286
287 /*! \brief Get a linked list of the Variable: headers with order specified */
288 struct ast_variable *astman_get_variables_order(const struct message *m, enum variable_orders order);
289
290 /*! \brief Send error in manager transaction */
291 void astman_send_error(struct mansession *s, const struct message *m, char *error);
292
293 /*! \brief Send error in manager transaction (with va_args support) */
294 void __attribute__((format(printf, 3, 4))) astman_send_error_va(struct mansession *s, const struct message *m, const char *fmt, ...);
295
296 /*! \brief Send response in manager transaction */
297 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
298
299 /*! \brief Send ack in manager transaction */
300 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
301
302 /*!
303  * \brief Send ack in manager transaction to begin a list.
304  *
305  * \param s - AMI session control struct.
306  * \param m - AMI action request that started the list.
307  * \param msg - Message contents describing the list to follow.
308  * \param listflag - Should always be set to "start".
309  *
310  * \note You need to call astman_send_list_complete_start() and
311  * astman_send_list_complete_end() to send the AMI list completion event.
312  *
313  * \return Nothing
314  */
315 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
316
317 /*!
318  * \brief Start the list complete event.
319  * \since 13.2.0
320  *
321  * \param s - AMI session control struct.
322  * \param m - AMI action request that started the list.
323  * \param event_name - AMI list complete event name.
324  * \param count - Number of items in the list.
325  *
326  * \note You need to call astman_send_list_complete_end() to end
327  * the AMI list completion event.
328  *
329  * \note Between calling astman_send_list_complete_start() and
330  * astman_send_list_complete_end() you can add additonal headers
331  * using astman_append().
332  *
333  * \return Nothing
334  */
335 void astman_send_list_complete_start(struct mansession *s, const struct message *m, const char *event_name, int count);
336
337 /*!
338  * \brief End the list complete event.
339  * \since 13.2.0
340  *
341  * \param s - AMI session control struct.
342  *
343  * \note You need to call astman_send_list_complete_start() to start
344  * the AMI list completion event.
345  *
346  * \note Between calling astman_send_list_complete_start() and
347  * astman_send_list_complete_end() you can add additonal headers
348  * using astman_append().
349  *
350  * \return Nothing
351  */
352 void astman_send_list_complete_end(struct mansession *s);
353
354 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
355
356 /*! \brief Determinie if a manager session ident is authenticated */
357 int astman_is_authed(uint32_t ident);
358
359 /*! \brief Called by Asterisk initialization */
360 int init_manager(void);
361
362 /*! \brief Called by Asterisk module functions and the CLI command */
363 int reload_manager(void);
364
365 /*! 
366  * \brief Add a datastore to a session
367  *
368  * \retval 0 success
369  * \retval non-zero failure
370  * \since 1.6.1
371  */
372
373 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
374
375 /*! 
376  * \brief Remove a datastore from a session
377  *
378  * \retval 0 success
379  * \retval non-zero failure
380  * \since 1.6.1
381  */
382 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
383
384 /*! 
385  * \brief Find a datastore on a session
386  *
387  * \retval pointer to the datastore if found
388  * \retval NULL if not found
389  * \since 1.6.1
390  */
391 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
392
393 /*!
394  * \brief append an event header to an ast string
395  * \since 12
396  *
397  * \param fields_string pointer to an ast_string pointer. It may be a pointer to a
398  *        NULL ast_str pointer, in which case the ast_str will be initialized.
399  * \param header The header being applied
400  * \param value the value of the header
401  *
402  * \retval 0 if successful
403  * \retval non-zero on failure
404  */
405 int ast_str_append_event_header(struct ast_str **fields_string,
406         const char *header, const char *value);
407
408 /*! \brief Struct representing a snapshot of channel state */
409 struct ast_channel_snapshot;
410
411 /*!
412  * \brief Generate the AMI message body from a channel snapshot
413  * \since 12
414  *
415  * \param snapshot the channel snapshot for which to generate an AMI message
416  *                 body
417  * \param prefix What to prepend to the channel fields
418  *
419  * \retval NULL on error
420  * \retval ast_str* on success (must be ast_freed by caller)
421  */
422 struct ast_str *ast_manager_build_channel_state_string_prefix(
423                 const struct ast_channel_snapshot *snapshot,
424                 const char *prefix);
425
426 /*!
427  * \brief Generate the AMI message body from a channel snapshot
428  * \since 12
429  *
430  * \param snapshot the channel snapshot for which to generate an AMI message
431  *                 body
432  *
433  * \retval NULL on error
434  * \retval ast_str* on success (must be ast_freed by caller)
435  */
436 struct ast_str *ast_manager_build_channel_state_string(
437                 const struct ast_channel_snapshot *snapshot);
438
439 /*! \brief Struct representing a snapshot of bridge state */
440 struct ast_bridge_snapshot;
441
442 /*!
443  * \since 12
444  * \brief Callback used to determine whether a key should be skipped when converting a
445  *  JSON object to a manager blob
446  * \param key Key from JSON blob to be evaluated
447  * \retval non-zero if the key should be excluded
448  * \retval zero if the key should not be excluded
449  */
450 typedef int (*key_exclusion_cb)(const char *key);
451
452 struct ast_json;
453
454 /*!
455  * \since 12
456  * \brief Convert a JSON object into an AMI compatible string
457  *
458  * \param blob The JSON blob containing key/value pairs to convert
459  * \param exclusion_cb A \ref key_exclusion_cb pointer to a function that will exclude
460  * keys from the final AMI string
461  *
462  * \retval A malloc'd \ref ast_str object. Callers of this function should free
463  * the returned \ref ast_str object
464  * \retval NULL on error
465  */
466 struct ast_str *ast_manager_str_from_json_object(struct ast_json *blob, key_exclusion_cb exclusion_cb);
467
468 /*!
469  * \brief Generate the AMI message body from a bridge snapshot
470  * \since 12
471  *
472  * \param snapshot the bridge snapshot for which to generate an AMI message
473  *                 body
474  * \param prefix What to prepend to the bridge fields
475  *
476  * \retval NULL on error
477  * \retval ast_str* on success (must be ast_freed by caller)
478  */
479 struct ast_str *ast_manager_build_bridge_state_string_prefix(
480         const struct ast_bridge_snapshot *snapshot,
481         const char *prefix);
482
483 /*!
484  * \brief Generate the AMI message body from a bridge snapshot
485  * \since 12
486  *
487  * \param snapshot the bridge snapshot for which to generate an AMI message
488  *                 body
489  *
490  * \retval NULL on error
491  * \retval ast_str* on success (must be ast_freed by caller)
492  */
493 struct ast_str *ast_manager_build_bridge_state_string(
494         const struct ast_bridge_snapshot *snapshot);
495
496 /*! \brief Struct containing info for an AMI event to send out. */
497 struct ast_manager_event_blob {
498         int event_flags;                /*!< Flags the event should be raised with. */
499         const char *manager_event;      /*!< The event to be raised, should be a string literal. */
500         AST_DECLARE_STRING_FIELDS(
501                 AST_STRING_FIELD(extra_fields); /*!< Extra fields to include in the event. */
502         );
503 };
504
505 /*!
506  * \since 12
507  * \brief Construct a \ref ast_manager_event_blob.
508  *
509  * The returned object is AO2 managed, so clean up with ao2_cleanup().
510  *
511  * \param event_flags Flags the event should be raised with.
512  * \param manager_event The event to be raised, should be a string literal.
513  * \param extra_fields_fmt Format string for extra fields to include.
514  *                         Or NO_EXTRA_FIELDS for no extra fields.
515  *
516  * \return New \ref ast_manager_snapshot_event object.
517  * \return \c NULL on error.
518  */
519 struct ast_manager_event_blob *
520 __attribute__((format(printf, 3, 4)))
521 ast_manager_event_blob_create(
522         int event_flags,
523         const char *manager_event,
524         const char *extra_fields_fmt,
525         ...);
526
527 /*! GCC warns about blank or NULL format strings. So, shenanigans! */
528 #define NO_EXTRA_FIELDS "%s", ""
529
530 /*!
531  * \since 12
532  * \brief Initialize support for AMI system events.
533  * \retval 0 on success
534  * \retval non-zero on error
535  */
536 int manager_system_init(void);
537
538 /*!
539  * \brief Initialize support for AMI channel events.
540  * \retval 0 on success.
541  * \retval non-zero on error.
542  * \since 12
543  */
544 int manager_channels_init(void);
545
546 /*!
547  * \since 12
548  * \brief Initialize support for AMI MWI events.
549  * \retval 0 on success
550  * \retval non-zero on error
551  */
552 int manager_mwi_init(void);
553
554 /*!
555  * \brief Initialize support for AMI channel events.
556  * \return 0 on success.
557  * \return non-zero on error.
558  * \since 12
559  */
560 int manager_bridging_init(void);
561
562 /*!
563  * \brief Initialize support for AMI endpoint events.
564  * \return 0 on success.
565  * \return non-zero on error.
566  * \since 12
567  */
568 int manager_endpoints_init(void);
569
570 /*!
571  * \since 12
572  * \brief Get the \ref stasis_message_type for generic messages
573  *
574  * A generic AMI message expects a JSON only payload. The payload must have the following
575  * structure:
576  * {type: s, class_type: i, event: [ {s: s}, ...] }
577  *
578  * - type is the AMI event type
579  * - class_type is the class authorization type for the event
580  * - event is a list of key/value tuples to be sent out in the message
581  *
582  * \retval A \ref stasis_message_type for AMI messages
583  */
584 struct stasis_message_type *ast_manager_get_generic_type(void);
585
586 /*!
587  * \since 12
588  * \brief Get the \ref stasis topic for AMI
589  *
590  * \retval The \ref stasis topic for AMI
591  * \retval NULL on error
592  */
593 struct stasis_topic *ast_manager_get_topic(void);
594
595 /*!
596  * \since 12
597  * \brief Publish an event to AMI
598  *
599  * \param type The type of AMI event to publish
600  * \param class_type The class on which to publish the event
601  * \param obj The event data to be published.
602  *
603  * Publishes a message to the \ref stasis message bus solely for the consumption of AMI.
604  * The message will be of the type provided by \ref ast_manager_get_type, and will be
605  * published to the topic provided by \ref ast_manager_get_topic. As such, the JSON must
606  * be constructed as defined by the \ref ast_manager_get_type message.
607  */
608 void ast_manager_publish_event(const char *type, int class_type, struct ast_json *obj);
609
610 /*!
611  * \since 12
612  * \brief Get the \ref stasis_message_router for AMI
613  *
614  * \retval The \ref stasis_message_router for AMI
615  * \retval NULL on error
616  */
617 struct stasis_message_router *ast_manager_get_message_router(void);
618
619 #endif /* _ASTERISK_MANAGER_H */