include/asterisk/manager.h

   1 /*
   2  * Asterisk -- A telephony toolkit for Linux.
   3  *
   4  * External call management support
   5  *
   6  * Copyright (C) 1999, Mark Spencer
   7  *
   8  * Mark Spencer <markster@linux-support.net>
   9  *
  10  * This program is free software, distributed under the terms of
  11  * the GNU General Public License.
  12  *
  13  * Includes code and algorithms from the Zapata library.
  14  *
  15  */
  16
  17 #ifndef _ASTERISK_MANAGER_H
  18 #define _ASTERISK_MANAGER_H
  19
  20 #include <stdarg.h>
  21 #include <sys/types.h>
  22 #include <sys/socket.h>
  23 #include <netinet/in.h>
  24 #include <arpa/inet.h>
  25
  26 #include <asterisk/lock.h>
  27
  28 /*!
  29   \file manager.h
  30   \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
  31          manage Asterisk with third-party software.
  32
  33  Manager protocol packages are text fields of the form a: b.  There is
  34  always exactly one space after the colon.
  35
  36  The first header type is the "Event" header.  Other headers vary from
  37  event to event.  Headers end with standard \r\n termination.
  38
  39  Some standard headers:
  40
  41  Action: <action>               -- request or notification of a particular action
  42  Response: <response>           -- response code, like "200 OK"
  43
  44  */
  45
  46 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
  47
  48 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
  49 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
  50 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
  51 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
  52 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
  53 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
  54 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
  55
  56 /* Export manager structures */
  57 #define MAX_HEADERS 80
  58 #define MAX_LEN 256
  59
  60 struct mansession {
  61         /*! Execution thread */
  62         pthread_t t;
  63         /*! Thread lock */
  64         ast_mutex_t lock;
  65         /*! socket address */
  66         struct sockaddr_in sin;
  67         /*! TCP socket */
  68         int fd;
  69         int blocking;
  70         /*! Logged in username */
  71         char username[80];
  72         /*! Authentication challenge */
  73         char challenge[10];
  74         /*! Authentication status */
  75         int authenticated;
  76         /*! Authorization for reading */
  77         int readperm;
  78         /*! Authorization for writing */
  79         int writeperm;
  80         /*! Buffer */
  81         char inbuf[MAX_LEN];
  82         int inlen;
  83         int send_events;
  84         struct mansession *next;
  85 };
  86
  87
  88 struct message {
  89         int hdrcount;
  90         char headers[MAX_HEADERS][MAX_LEN];
  91 };
  92
  93 struct manager_action {
  94         /*! Name of the action */
  95         const char *action;
  96         /*! Short description of the action */
  97         const char *synopsis;
  98         /*! Detailed description of the action */
  99         const char *description;
 100         /*! Permission required for action.  EVENT_FLAG_* */
 101         int authority;
 102         /*! Function to be called */
 103         int (*func)(struct mansession *s, struct message *m);
 104         /*! For easy linking */
 105         struct manager_action *next;
 106 };
 107
 108 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
 109
 110 /* External routines may register/unregister manager callbacks this way */
 111 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
 112
 113 /* Use ast_manager_register2 to register with help text for new manager commands */
 114
 115 /*! Register a manager command with the manager interface */
 116 /*!     \param action Name of the requested Action:
 117         \param authority Required authority for this command
 118         \param func Function to call for this command
 119         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
 120         \param description Help text, several lines
 121 */
 122 int ast_manager_register2(
 123         const char *action,
 124         int authority,
 125         int (*func)(struct mansession *s, struct message *m),
 126         const char *synopsis,
 127         const char *description);
 128
 129 /*! Unregister a registred manager command */
 130 /*!     \param action Name of registred Action:
 131 */
 132 int ast_manager_unregister( char *action );
 133
 134 /*! External routines may send asterisk manager events this way */
 135 /*!     \param category Event category, matches manager authorization
 136         \param event    Event name
 137         \param contents Contents of event
 138 */
 139 extern int manager_event(int category, char *event, char *contents, ...)
 140         __attribute__ ((format (printf, 3,4)));
 141
 142 /*! Get header from mananger transaction */
 143 extern char *astman_get_header(struct message *m, char *var);
 144 /*! Send error in manager transaction */
 145 extern void astman_send_error(struct mansession *s, struct message *m, char *error);
 146 extern void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
 147 extern void astman_send_ack(struct mansession *s, struct message *m, char *msg);
 148
 149 /*! Called by Asterisk initialization */
 150 extern int init_manager(void);
 151 /*! Called by Asterisk initialization */
 152 extern int reload_manager(void);
 153 #endif