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 */