00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 #ifndef _ASTERISK_MANAGER_H 00020 #define _ASTERISK_MANAGER_H 00021 00022 #include <stdarg.h> 00023 #include <sys/types.h> 00024 #include <sys/socket.h> 00025 #include <netinet/in.h> 00026 #include <arpa/inet.h> 00027 00028 #include "asterisk/lock.h" 00029 00030 /*! 00031 \file 00032 \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to 00033 manage Asterisk with third-party software. 00034 00035 Manager protocol packages are text fields of the form a: b. There is 00036 always exactly one space after the colon. 00037 00038 The first header type is the "Event" header. Other headers vary from 00039 event to event. Headers end with standard \r\n termination. 00040 The last line of the manager response or event is an empty line. 00041 (\r\n) 00042 00043 ** Please try to re-use existing headers to simplify manager message parsing in clients. 00044 Don't re-use an existing header with a new meaning, please. 00045 You can find a reference of standard headers in doc/manager.txt 00046 */ 00047 00048 #define DEFAULT_MANAGER_PORT 5038 /* Default port for Asterisk management via TCP */ 00049 00050 #define EVENT_FLAG_SYSTEM (1 << 0) /* System events such as module load/unload */ 00051 #define EVENT_FLAG_CALL (1 << 1) /* Call event, such as state change, etc */ 00052 #define EVENT_FLAG_LOG (1 << 2) /* Log events */ 00053 #define EVENT_FLAG_VERBOSE (1 << 3) /* Verbose messages */ 00054 #define EVENT_FLAG_COMMAND (1 << 4) /* Ability to read/set commands */ 00055 #define EVENT_FLAG_AGENT (1 << 5) /* Ability to read/set agent info */ 00056 #define EVENT_FLAG_USER (1 << 6) /* Ability to read/set user info */ 00057 #define EVENT_FLAG_CONFIG (1 << 7) /* Ability to modify configurations */ 00058 #define EVENT_FLAG_EXTENSIONSTATUS (1 << 8) /* ExtensionStatus events */ 00059 00060 /* Export manager structures */ 00061 #define AST_MAX_MANHEADERS 128 00062 00063 struct mansession; 00064 00065 struct message { 00066 unsigned int hdrcount; 00067 const char *headers[AST_MAX_MANHEADERS]; 00068 }; 00069 00070 struct manager_action { 00071 /*! Name of the action */ 00072 const char *action; 00073 /*! Short description of the action */ 00074 const char *synopsis; 00075 /*! Detailed description of the action */ 00076 const char *description; 00077 /*! Permission required for action. EVENT_FLAG_* */ 00078 int authority; 00079 /*! Function to be called */ 00080 int (*func)(struct mansession *s, const struct message *m); 00081 /*! For easy linking */ 00082 struct manager_action *next; 00083 }; 00084 00085 /* External routines may register/unregister manager callbacks this way */ 00086 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL) 00087 00088 /* Use ast_manager_register2 to register with help text for new manager commands */ 00089 00090 /*! Register a manager command with the manager interface */ 00091 /*! \param action Name of the requested Action: 00092 \param authority Required authority for this command 00093 \param func Function to call for this command 00094 \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands 00095 \param description Help text, several lines 00096 */ 00097 int ast_manager_register2( 00098 const char *action, 00099 int authority, 00100 int (*func)(struct mansession *s, const struct message *m), 00101 const char *synopsis, 00102 const char *description); 00103 00104 /*! Unregister a registred manager command */ 00105 /*! \param action Name of registred Action: 00106 */ 00107 int ast_manager_unregister( char *action ); 00108 00109 /*! 00110 * \brief Verify a session's read permissions against a permission mask. 00111 * \param ident session identity 00112 * \param perm permission mask to verify 00113 * \returns 1 if the session has the permission mask capabilities, otherwise 0 00114 */ 00115 int astman_verify_session_readpermissions(uint32_t ident, int perm); 00116 00117 /*! 00118 * \brief Verify a session's write permissions against a permission mask. 00119 * \param ident session identity 00120 * \param perm permission mask to verify 00121 * \returns 1 if the session has the permission mask capabilities, otherwise 0 00122 */ 00123 int astman_verify_session_writepermissions(uint32_t ident, int perm); 00124 00125 /*! External routines may send asterisk manager events this way */ 00126 /*! \param category Event category, matches manager authorization 00127 \param event Event name 00128 \param contents Contents of event 00129 */ 00130 int __attribute__ ((format (printf, 3,4))) manager_event(int category, const char *event, const char *contents, ...); 00131 00132 /*! Get header from mananger transaction */ 00133 const char *astman_get_header(const struct message *m, char *var); 00134 00135 /*! Get a linked list of the Variable: headers */ 00136 struct ast_variable *astman_get_variables(const struct message *m); 00137 00138 /*! Send error in manager transaction */ 00139 void astman_send_error(struct mansession *s, const struct message *m, char *error); 00140 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg); 00141 void astman_send_ack(struct mansession *s, const struct message *m, char *msg); 00142 00143 void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...); 00144 00145 /*! Called by Asterisk initialization */ 00146 int init_manager(void); 00147 int reload_manager(void); 00148 00149 #endif /* _ASTERISK_MANAGER_H */