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  The first header type is the "Event" header.  Other headers vary from
  39  event to event.  Headers end with standard \r\n termination.
  40  The last line of the manager response or event is an empty line.
  41  (\r\n)
  42
  43  ** Please try to re-use existing headers to simplify manager message parsing in clients.
  44     Don't re-use an existing header with a new meaning, please.
  45     You can find a reference of standard headers in doc/manager.txt
  46  */
  47
  48 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
  49
  50 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
  51 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
  52 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
  53 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
  54 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
  55 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
  56 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
  57 #define EVENT_FLAG_CONFIG               (1 << 7) /* Ability to modify configurations */
  58
  59 /* Export manager structures */
  60 #define AST_MAX_MANHEADERS 128
  61
  62 struct mansession;
  63
  64 struct message {
  65         unsigned int hdrcount;
  66         const char *headers[AST_MAX_MANHEADERS];
  67 };
  68
  69 struct manager_action {
  70         /*! Name of the action */
  71         const char *action;
  72         /*! Short description of the action */
  73         const char *synopsis;
  74         /*! Detailed description of the action */
  75         const char *description;
  76         /*! Permission required for action.  EVENT_FLAG_* */
  77         int authority;
  78         /*! Function to be called */
  79         int (*func)(struct mansession *s, const struct message *m);
  80         /*! For easy linking */
  81         struct manager_action *next;
  82 };
  83
  84 /* External routines may register/unregister manager callbacks this way */
  85 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
  86
  87 /* Use ast_manager_register2 to register with help text for new manager commands */
  88
  89 /*! Register a manager command with the manager interface */
  90 /*!     \param action Name of the requested Action:
  91         \param authority Required authority for this command
  92         \param func Function to call for this command
  93         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
  94         \param description Help text, several lines
  95 */
  96 int ast_manager_register2(
  97         const char *action,
  98         int authority,
  99         int (*func)(struct mansession *s, const struct message *m),
 100         const char *synopsis,
 101         const char *description);
 102
 103 /*! Unregister a registred manager command */
 104 /*!     \param action Name of registred Action:
 105 */
 106 int ast_manager_unregister( char *action );
 107
 108 /*!
 109  * \brief Verify a session's read permissions against a permission mask.
 110  * \param ident session identity
 111  * \param perm permission mask to verify
 112  * \returns 1 if the session has the permission mask capabilities, otherwise 0
 113  */
 114 int astman_verify_session_readpermissions(uint32_t ident, int perm);
 115
 116 /*!
 117  * \brief Verify a session's write permissions against a permission mask.
 118  * \param ident session identity
 119  * \param perm permission mask to verify
 120  * \returns 1 if the session has the permission mask capabilities, otherwise 0
 121  */
 122 int astman_verify_session_writepermissions(uint32_t ident, int perm);
 123
 124 /*! External routines may send asterisk manager events this way */
 125 /*!     \param category Event category, matches manager authorization
 126         \param event    Event name
 127         \param contents Contents of event
 128 */
 129 int __attribute__ ((format (printf, 3,4))) manager_event(int category, const char *event, const char *contents, ...);
 130
 131 /*! Get header from mananger transaction */
 132 const char *astman_get_header(const struct message *m, char *var);
 133
 134 /*! Get a linked list of the Variable: headers */
 135 struct ast_variable *astman_get_variables(const struct message *m);
 136
 137 /*! Send error in manager transaction */
 138 void astman_send_error(struct mansession *s, const struct message *m, char *error);
 139 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
 140 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
 141
 142 void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
 143
 144 /*! Called by Asterisk initialization */
 145 int init_manager(void);
 146 int reload_manager(void);
 147
 148 #endif /* _ASTERISK_MANAGER_H */