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 #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 /*@} */
  90
  91 /*! \brief Export manager structures */
  92 #define AST_MAX_MANHEADERS 128
  93
  94 /*! \brief Manager Helper Function */
  95 typedef int (*manager_hook_t)(int, const char *, char *);
  96
  97 struct manager_custom_hook {
  98         /*! Identifier */
  99         char *file;
 100         /*! helper function */
 101         manager_hook_t helper;
 102         /*! Linked list information */
 103         AST_RWLIST_ENTRY(manager_custom_hook) list;
 104 };
 105
 106 /*! \brief Check if AMI is enabled */
 107 int check_manager_enabled(void);
 108
 109 /*! \brief Check if AMI/HTTP is enabled */
 110 int check_webmanager_enabled(void);
 111
 112 /*! Add a custom hook to be called when an event is fired
 113  \param hook struct manager_custom_hook object to add
 114 */
 115 void ast_manager_register_hook(struct manager_custom_hook *hook);
 116
 117 /*! Delete a custom hook to be called when an event is fired
 118     \param hook struct manager_custom_hook object to delete
 119 */
 120 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
 121
 122 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback
 123  * \param hook the file identifier specified in manager_custom_hook struct when registering a hook
 124  * \param msg ami action mesage string e.g. "Action: SipPeers\r\n"
 125
 126  * \retval 0 on Success
 127  * \retval non-zero on Failure
 128 */
 129 int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg);
 130
 131 struct mansession;
 132
 133 struct message {
 134         unsigned int hdrcount;
 135         const char *headers[AST_MAX_MANHEADERS];
 136 };
 137
 138 struct manager_action {
 139         /*! Name of the action */
 140         const char *action;
 141         AST_DECLARE_STRING_FIELDS(
 142                 AST_STRING_FIELD(synopsis);     /*!< Synopsis text (short description). */
 143                 AST_STRING_FIELD(description);  /*!< Description (help text) */
 144                 AST_STRING_FIELD(syntax);       /*!< Syntax text */
 145                 AST_STRING_FIELD(arguments);    /*!< Description of each argument. */
 146                 AST_STRING_FIELD(seealso);      /*!< See also */
 147         );
 148         /*! Permission required for action.  EVENT_FLAG_* */
 149         int authority;
 150         /*! Function to be called */
 151         int (*func)(struct mansession *s, const struct message *m);
 152         /*! Where the documentation come from. */
 153         enum ast_doc_src docsrc;
 154         /*! For easy linking */
 155         AST_RWLIST_ENTRY(manager_action) list;
 156         /*!
 157          * \brief TRUE if the AMI action is registered and the callback can be called.
 158          *
 159          * \note Needed to prevent a race between calling the callback
 160          * function and unregestring the AMI action object.
 161          */
 162         unsigned int registered:1;
 163 };
 164
 165 /*! \brief External routines may register/unregister manager callbacks this way
 166  * \note  Use ast_manager_register2() to register with help text for new manager commands */
 167 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
 168
 169 /*! \brief Register a manager callback using XML documentation to describe the manager. */
 170 #define ast_manager_register_xml(a, b, c) ast_manager_register2(a, b, c, NULL, NULL)
 171
 172 /*! \brief Register a manager command with the manager interface
 173         \param action Name of the requested Action:
 174         \param authority Required authority for this command
 175         \param func Function to call for this command
 176         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
 177         \param description Help text, several lines
 178 */
 179 int ast_manager_register2(
 180         const char *action,
 181         int authority,
 182         int (*func)(struct mansession *s, const struct message *m),
 183         const char *synopsis,
 184         const char *description);
 185
 186 /*! \brief Unregister a registered manager command
 187         \param action Name of registered Action:
 188 */
 189 int ast_manager_unregister( char *action );
 190
 191 /*!
 192  * \brief Verify a session's read permissions against a permission mask.
 193  * \param ident session identity
 194  * \param perm permission mask to verify
 195  * \retval 1 if the session has the permission mask capabilities
 196  * \retval 0 otherwise
 197  */
 198 int astman_verify_session_readpermissions(uint32_t ident, int perm);
 199
 200 /*!
 201  * \brief Verify a session's write permissions against a permission mask.
 202  * \param ident session identity
 203  * \param perm permission mask to verify
 204  * \retval 1 if the session has the permission mask capabilities, otherwise 0
 205  * \retval 0 otherwise
 206  */
 207 int astman_verify_session_writepermissions(uint32_t ident, int perm);
 208
 209 /*! \brief External routines may send asterisk manager events this way
 210  *      \param category Event category, matches manager authorization
 211         \param event    Event name
 212         \param contents Contents of event
 213 */
 214
 215 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
 216  * between the last arg before VA_ARGS and the comma */
 217 #define manager_event(category, event, contents , ...)  \
 218         __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
 219 #define ast_manager_event(chan, category, event, contents , ...) \
 220         do { \
 221                 struct ast_channel *_chans[] = { chan, }; \
 222                 __ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \
 223         } while (0)
 224 #define ast_manager_event_multichan(category, event, nchans, chans, contents , ...) \
 225         __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
 226
 227 /*! External routines may send asterisk manager events this way
 228  * \param category Event category, matches manager authorization
 229  * \param event Event name
 230  * \param chancount Number of channels in chans parameter
 231  * \param chans A pointer to an array of channels involved in the event
 232  * \param contents Format string describing event
 233  * \since 1.8
 234 */
 235 int __ast_manager_event_multichan(int category, const char *event, int chancount,
 236                 struct ast_channel **chans, const char *file, int line, const char *func,
 237                 const char *contents, ...) __attribute__((format(printf, 8, 9)));
 238
 239 /*! \brief Get header from mananger transaction */
 240 const char *astman_get_header(const struct message *m, char *var);
 241
 242 /*! \brief Get a linked list of the Variable: headers */
 243 struct ast_variable *astman_get_variables(const struct message *m);
 244
 245 /*! \brief Send error in manager transaction */
 246 void astman_send_error(struct mansession *s, const struct message *m, char *error);
 247
 248 /*! \brief Send response in manager transaction */
 249 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
 250
 251 /*! \brief Send ack in manager transaction */
 252 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
 253
 254 /*! \brief Send ack in manager list transaction */
 255 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
 256
 257 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
 258
 259 /*! \brief Determinie if a manager session ident is authenticated */
 260 int astman_is_authed(uint32_t ident);
 261
 262 /*! \brief Called by Asterisk initialization */
 263 int init_manager(void);
 264
 265 /*! \brief Called by Asterisk module functions and the CLI command */
 266 int reload_manager(void);
 267
 268 /*!
 269  * \brief Add a datastore to a session
 270  *
 271  * \retval 0 success
 272  * \retval non-zero failure
 273  * \since 1.6.1
 274  */
 275
 276 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
 277
 278 /*!
 279  * \brief Remove a datastore from a session
 280  *
 281  * \retval 0 success
 282  * \retval non-zero failure
 283  * \since 1.6.1
 284  */
 285 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
 286
 287 /*!
 288  * \brief Find a datastore on a session
 289  *
 290  * \retval pointer to the datastore if found
 291  * \retval NULL if not found
 292  * \since 1.6.1
 293  */
 294 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
 295
 296 #endif /* _ASTERISK_MANAGER_H */