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
  25 /*!
  26  \file
  27  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
  28  manage Asterisk with third-party software.
  29
  30  Manager protocol packages are text fields of the form a: b.  There is
  31  always exactly one space after the colon.
  32
  33 \verbatim
  34
  35  For Actions replies, the first line of the reply is a "Response:" header with
  36  values "success", "error" or "follows". "Follows" implies that the
  37  response is coming as separate events with the same ActionID. If the
  38  Action request has no ActionID, it will be hard matching events
  39  to the Action request in the manager client.
  40
  41  The first header type is the "Event" header.  Other headers vary from
  42  event to event.  Headers end with standard \\r\\n termination.
  43  The last line of the manager response or event is an empty line.
  44  (\\r\\n)
  45
  46 \endverbatim
  47
  48  \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients.
  49     Don't re-use an existing header with a new meaning, please.
  50     You can find a reference of standard headers in doc/manager.txt
  51
  52 - \ref manager.c Main manager code file
  53  */
  54
  55 #define AMI_VERSION                     "1.1"
  56 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
  57
  58 /*! \name Manager event classes */
  59 /*@{ */
  60 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
  61 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
  62 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
  63 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
  64 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
  65 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
  66 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
  67 #define EVENT_FLAG_CONFIG               (1 << 7) /* Ability to modify configurations */
  68 #define EVENT_FLAG_DTMF                 (1 << 8) /* Ability to read DTMF events */
  69 #define EVENT_FLAG_REPORTING            (1 << 9) /* Reporting events such as rtcp sent */
  70 #define EVENT_FLAG_CDR                  (1 << 10) /* CDR events */
  71 /*@} */
  72
  73 /*! \brief Export manager structures */
  74 #define AST_MAX_MANHEADERS 128
  75
  76 /*! \brief Manager Helper Function */
  77 typedef int (*manager_hook_t)(int, const char *, char *);
  78
  79
  80 struct manager_custom_hook {
  81         /*! Identifier */
  82         char *file;
  83         /*! helper function */
  84         manager_hook_t helper;
  85         /*! Linked list information */
  86         AST_RWLIST_ENTRY(manager_custom_hook) list;
  87 };
  88
  89 /*! \brief Check if AMI is enabled */
  90 int check_manager_enabled(void);
  91
  92 /*! \brief Check if AMI/HTTP is enabled */
  93 int check_webmanager_enabled(void);
  94
  95 /*! Add a custom hook to be called when an event is fired
  96  \param hook struct manager_custom_hook object to add
  97 */
  98 void ast_manager_register_hook(struct manager_custom_hook *hook);
  99
 100 /*! Delete a custom hook to be called when an event is fired
 101     \param hook struct manager_custom_hook object to delete
 102 */
 103 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
 104
 105 struct mansession;
 106
 107 struct message {
 108         unsigned int hdrcount;
 109         const char *headers[AST_MAX_MANHEADERS];
 110 };
 111
 112 struct manager_action {
 113         /*! Name of the action */
 114         const char *action;
 115         /*! Short description of the action */
 116         const char *synopsis;
 117         /*! Detailed description of the action */
 118         const char *description;
 119         /*! Permission required for action.  EVENT_FLAG_* */
 120         int authority;
 121         /*! Function to be called */
 122         int (*func)(struct mansession *s, const struct message *m);
 123         /*! For easy linking */
 124         AST_RWLIST_ENTRY(manager_action) list;
 125 };
 126
 127 /*! \brief External routines may register/unregister manager callbacks this way
 128  * \note  Use ast_manager_register2() to register with help text for new manager commands */
 129 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
 130
 131
 132 /*! \brief Register a manager command with the manager interface
 133         \param action Name of the requested Action:
 134         \param authority Required authority for this command
 135         \param func Function to call for this command
 136         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
 137         \param description Help text, several lines
 138 */
 139 int ast_manager_register2(
 140         const char *action,
 141         int authority,
 142         int (*func)(struct mansession *s, const struct message *m),
 143         const char *synopsis,
 144         const char *description);
 145
 146 /*! \brief Unregister a registred manager command
 147         \param action Name of registred Action:
 148 */
 149 int ast_manager_unregister( char *action );
 150
 151 /*!
 152  * \brief Verify a session's read permissions against a permission mask.
 153  * \param ident session identity
 154  * \param perm permission mask to verify
 155  * \retval 1 if the session has the permission mask capabilities
 156  * \retval 0 otherwise
 157  */
 158 int astman_verify_session_readpermissions(unsigned long ident, int perm);
 159
 160 /*!
 161  * \brief Verify a session's write permissions against a permission mask.
 162  * \param ident session identity
 163  * \param perm permission mask to verify
 164  * \retval 1 if the session has the permission mask capabilities, otherwise 0
 165  * \retval 0 otherwise
 166  */
 167 int astman_verify_session_writepermissions(unsigned long ident, int perm);
 168
 169 /*! \brief External routines may send asterisk manager events this way
 170  *      \param category Event category, matches manager authorization
 171         \param event    Event name
 172         \param contents Contents of event
 173 */
 174
 175 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
 176  * between the last arg before VA_ARGS and the comma */
 177 #define manager_event(category, event, contents , ...)  \
 178         __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
 179
 180 int __attribute__ ((format(printf, 6, 7))) __manager_event(int category, const char *event,
 181                                                            const char *file, int line, const char *func,
 182                                                            const char *contents, ...);
 183
 184 /*! \brief Get header from mananger transaction */
 185 const char *astman_get_header(const struct message *m, char *var);
 186
 187 /*! \brief Get a linked list of the Variable: headers */
 188 struct ast_variable *astman_get_variables(const struct message *m);
 189
 190 /*! \brief Send error in manager transaction */
 191 void astman_send_error(struct mansession *s, const struct message *m, char *error);
 192
 193 /*! \brief Send response in manager transaction */
 194 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
 195
 196 /*! \brief Send ack in manager transaction */
 197 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
 198
 199 /*! \brief Send ack in manager list transaction */
 200 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
 201
 202 void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
 203
 204 /*! \brief Called by Asterisk initialization */
 205 int init_manager(void);
 206
 207 /*! \brief Called by Asterisk module functions and the CLI command */
 208 int reload_manager(void);
 209
 210 #endif /* _ASTERISK_MANAGER_H */