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 /*
  20  * AMI - Asterisk Management Interface
  21  * External call management support
  22  */
  23
  24 #ifndef _ASTERISK_MANAGER_H
  25 #define _ASTERISK_MANAGER_H
  26
  27 #include <stdarg.h>
  28 #include <sys/types.h>
  29 #include <sys/socket.h>
  30 #include <netinet/in.h>
  31 #include <arpa/inet.h>
  32
  33 #include "asterisk/lock.h"
  34
  35 /*!
  36   \file manager.h
  37   \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
  38          manage Asterisk with third-party software.
  39
  40  Manager protocol packages are text fields of the form a: b.  There is
  41  always exactly one space after the colon.
  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  ** Please try to re-use existing 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
  51     doc/manager.txt
  52
  53  */
  54
  55 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
  56
  57 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
  58 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
  59 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
  60 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
  61 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
  62 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
  63 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
  64
  65 /* Export manager structures */
  66 #define MAX_HEADERS 80
  67 #define MAX_LEN 256
  68
  69 struct eventqent {
  70         struct eventqent *next;
  71         char eventdata[1];
  72 };
  73
  74 struct mansession {
  75         /*! Execution thread */
  76         pthread_t t;
  77         /*! Thread lock -- don't use in action callbacks, it's already taken care of  */
  78         ast_mutex_t __lock;
  79         /*! socket address */
  80         struct sockaddr_in sin;
  81         /*! TCP socket */
  82         int fd;
  83         /*! Whether or not we're busy doing an action */
  84         int busy;
  85         /*! Whether or not we're "dead" */
  86         int dead;
  87         /*! Logged in username */
  88         char username[80];
  89         /*! Authentication challenge */
  90         char challenge[10];
  91         /*! Authentication status */
  92         int authenticated;
  93         /*! Authorization for reading */
  94         int readperm;
  95         /*! Authorization for writing */
  96         int writeperm;
  97         /*! Buffer */
  98         char inbuf[MAX_LEN];
  99         int inlen;
 100         int send_events;
 101         /* Queued events that we've not had the ability to send yet */
 102         struct eventqent *eventq;
 103         /* Timeout for ast_carefulwrite() */
 104         int writetimeout;
 105         struct mansession *next;
 106 };
 107
 108
 109 struct message {
 110         int hdrcount;
 111         char headers[MAX_HEADERS][MAX_LEN];
 112 };
 113
 114 struct manager_action {
 115         /*! Name of the action */
 116         const char *action;
 117         /*! Short description of the action */
 118         const char *synopsis;
 119         /*! Detailed description of the action */
 120         const char *description;
 121         /*! Permission required for action.  EVENT_FLAG_* */
 122         int authority;
 123         /*! Function to be called */
 124         int (*func)(struct mansession *s, struct message *m);
 125         /*! For easy linking */
 126         struct manager_action *next;
 127 };
 128
 129 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
 130
 131 /* External routines may register/unregister manager callbacks this way */
 132 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
 133
 134 /* Use ast_manager_register2 to register with help text for new manager commands */
 135
 136 /*! Register a manager command with the manager interface */
 137 /*!     \param action Name of the requested Action:
 138         \param authority Required authority for this command
 139         \param func Function to call for this command
 140         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
 141         \param description Help text, several lines
 142 */
 143 int ast_manager_register2(
 144         const char *action,
 145         int authority,
 146         int (*func)(struct mansession *s, struct message *m),
 147         const char *synopsis,
 148         const char *description);
 149
 150 /*! Unregister a registred manager command */
 151 /*!     \param action Name of registred Action:
 152 */
 153 int ast_manager_unregister( char *action );
 154
 155 /*! External routines may send asterisk manager events this way */
 156 /*!     \param category Event category, matches manager authorization
 157         \param event    Event name
 158         \param contents Contents of event
 159 */
 160 extern int manager_event(int category, char *event, char *contents, ...)
 161         __attribute__ ((format (printf, 3,4)));
 162
 163 /*! Get header from mananger transaction */
 164 extern char *astman_get_header(struct message *m, char *var);
 165
 166 /*! Get a linked list of the Variable: headers */
 167 struct ast_variable *astman_get_variables(struct message *m);
 168
 169 /*! Send error in manager transaction */
 170 extern void astman_send_error(struct mansession *s, struct message *m, char *error);
 171 extern void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
 172 extern void astman_send_ack(struct mansession *s, struct message *m, char *msg);
 173
 174 /*! Called by Asterisk initialization */
 175 extern int init_manager(void);
 176 /*! Called by Asterisk initialization */
 177 extern int reload_manager(void);
 178
 179 #endif /* _ASTERISK_MANAGER_H */