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