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