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 80
  61 #define AST_MAX_MANHEADER_LEN 256
  62
  63 /* Manager Helper Function */
  64 typedef int (*manager_hook_t)(int, const char *, char *);
  65
  66 struct manager_custom_hook {
  67         /*! Identifier */
  68         char *file;
  69         /*! helper function */
  70         manager_hook_t helper;
  71         /*! Linked list information */
  72         AST_RWLIST_ENTRY(manager_custom_hook) list;
  73 };
  74
  75 /*! Add a custom hook to be called when an event is fired */
  76 /*! \param hook struct manager_custom_hook object to add
  77 */
  78 void ast_manager_register_hook(struct manager_custom_hook *hook);
  79
  80 /*! Delete a custom hook to be called when an event is fired */
  81 /*! \param hook struct manager_custom_hook object to delete
  82 */
  83 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
  84
  85 struct mansession;
  86
  87 struct message {
  88         int hdrcount;
  89         char headers[AST_MAX_MANHEADERS][AST_MAX_MANHEADER_LEN];
  90 };
  91
  92 struct manager_action {
  93         /*! Name of the action */
  94         const char *action;
  95         /*! Short description of the action */
  96         const char *synopsis;
  97         /*! Detailed description of the action */
  98         const char *description;
  99         /*! Permission required for action.  EVENT_FLAG_* */
 100         int authority;
 101         /*! Function to be called */
 102         int (*func)(struct mansession *s, struct message *m);
 103         /*! For easy linking */
 104         struct manager_action *next;
 105 };
 106
 107 /* External routines may register/unregister manager callbacks this way */
 108 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
 109
 110 /* Use ast_manager_register2 to register with help text for new manager commands */
 111
 112 /*! Register a manager command with the manager interface */
 113 /*!     \param action Name of the requested Action:
 114         \param authority Required authority for this command
 115         \param func Function to call for this command
 116         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
 117         \param description Help text, several lines
 118 */
 119 int ast_manager_register2(
 120         const char *action,
 121         int authority,
 122         int (*func)(struct mansession *s, struct message *m),
 123         const char *synopsis,
 124         const char *description);
 125
 126 /*! Unregister a registred manager command */
 127 /*!     \param action Name of registred Action:
 128 */
 129 int ast_manager_unregister( char *action );
 130
 131 /*! External routines may send asterisk manager events this way */
 132 /*!     \param category Event category, matches manager authorization
 133         \param event    Event name
 134         \param contents Contents of event
 135 */
 136 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
 137  * between the last arg before VA_ARGS and the comma */
 138 #define manager_event(category, event, contents , ...)  \
 139         __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
 140
 141 int __manager_event(int category, const char *event,
 142                 const char *file, int line, const char *func, const char *contents, ...)
 143         __attribute__ ((format (printf, 6,7)));
 144
 145 /*! Get header from mananger transaction */
 146 char *astman_get_header(struct message *m, char *var);
 147
 148 /*! Get a linked list of the Variable: headers */
 149 struct ast_variable *astman_get_variables(struct message *m);
 150
 151 /*! Send error in manager transaction */
 152 void astman_send_error(struct mansession *s, struct message *m, char *error);
 153 void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
 154 void astman_send_ack(struct mansession *s, struct message *m, char *msg);
 155 void astman_send_listack(struct mansession *s, struct message *m, char *msg, char *listflag);
 156
 157 void astman_append(struct mansession *s, const char *fmt, ...)
 158         __attribute__ ((format (printf, 2, 3)));
 159
 160
 161 /*! Called by Asterisk initialization */
 162 int init_manager(void);
 163 /*! Called by Asterisk initialization */
 164 int reload_manager(void);
 165
 166 #endif /* _ASTERISK_MANAGER_H */