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