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 "asterisk/network.h" 00023 #include "asterisk/lock.h" 00024 00025 /*! 00026 \file 00027 \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to 00028 manage Asterisk with third-party software. 00029 00030 Manager protocol packages are text fields of the form a: b. There is 00031 always exactly one space after the colon. 00032 00033 \verbatim 00034 00035 For Actions replies, the first line of the reply is a "Response:" header with 00036 values "success", "error" or "follows". "Follows" implies that the 00037 response is coming as separate events with the same ActionID. If the 00038 Action request has no ActionID, it will be hard matching events 00039 to the Action request in the manager client. 00040 00041 The first header type is the "Event" header. Other headers vary from 00042 event to event. Headers end with standard \\r\\n termination. 00043 The last line of the manager response or event is an empty line. 00044 (\\r\\n) 00045 00046 \endverbatim 00047 00048 \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients. 00049 Don't re-use an existing header with a new meaning, please. 00050 You can find a reference of standard headers in doc/manager.txt 00051 00052 - \ref manager.c Main manager code file 00053 */ 00054 00055 #define AMI_VERSION "1.1" 00056 #define DEFAULT_MANAGER_PORT 5038 /* Default port for Asterisk management via TCP */ 00057 00058 /*! \name Manager event classes */ 00059 /*@{ */ 00060 #define EVENT_FLAG_SYSTEM (1 << 0) /* System events such as module load/unload */ 00061 #define EVENT_FLAG_CALL (1 << 1) /* Call event, such as state change, etc */ 00062 #define EVENT_FLAG_LOG (1 << 2) /* Log events */ 00063 #define EVENT_FLAG_VERBOSE (1 << 3) /* Verbose messages */ 00064 #define EVENT_FLAG_COMMAND (1 << 4) /* Ability to read/set commands */ 00065 #define EVENT_FLAG_AGENT (1 << 5) /* Ability to read/set agent info */ 00066 #define EVENT_FLAG_USER (1 << 6) /* Ability to read/set user info */ 00067 #define EVENT_FLAG_CONFIG (1 << 7) /* Ability to modify configurations */ 00068 #define EVENT_FLAG_DTMF (1 << 8) /* Ability to read DTMF events */ 00069 #define EVENT_FLAG_REPORTING (1 << 9) /* Reporting events such as rtcp sent */ 00070 #define EVENT_FLAG_CDR (1 << 10) /* CDR events */ 00071 #define EVENT_FLAG_DIALPLAN (1 << 11) /* Dialplan events (VarSet, NewExten) */ 00072 #define EVENT_FLAG_ORIGINATE (1 << 12) /* Originate a call to an extension */ 00073 /*@} */ 00074 00075 /*! \brief Export manager structures */ 00076 #define AST_MAX_MANHEADERS 128 00077 00078 /*! \brief Manager Helper Function */ 00079 typedef int (*manager_hook_t)(int, const char *, char *); 00080 00081 00082 struct manager_custom_hook { 00083 /*! Identifier */ 00084 char *file; 00085 /*! helper function */ 00086 manager_hook_t helper; 00087 /*! Linked list information */ 00088 AST_RWLIST_ENTRY(manager_custom_hook) list; 00089 }; 00090 00091 /*! \brief Check if AMI is enabled */ 00092 int check_manager_enabled(void); 00093 00094 /*! \brief Check if AMI/HTTP is enabled */ 00095 int check_webmanager_enabled(void); 00096 00097 /*! Add a custom hook to be called when an event is fired 00098 \param hook struct manager_custom_hook object to add 00099 */ 00100 void ast_manager_register_hook(struct manager_custom_hook *hook); 00101 00102 /*! Delete a custom hook to be called when an event is fired 00103 \param hook struct manager_custom_hook object to delete 00104 */ 00105 void ast_manager_unregister_hook(struct manager_custom_hook *hook); 00106 00107 struct mansession; 00108 00109 struct message { 00110 unsigned int hdrcount; 00111 const char *headers[AST_MAX_MANHEADERS]; 00112 }; 00113 00114 struct manager_action { 00115 /*! Name of the action */ 00116 const char *action; 00117 /*! Short description of the action */ 00118 const char *synopsis; 00119 /*! Detailed description of the action */ 00120 const char *description; 00121 /*! Permission required for action. EVENT_FLAG_* */ 00122 int authority; 00123 /*! Function to be called */ 00124 int (*func)(struct mansession *s, const struct message *m); 00125 /*! For easy linking */ 00126 AST_RWLIST_ENTRY(manager_action) list; 00127 }; 00128 00129 /*! \brief External routines may register/unregister manager callbacks this way 00130 * \note Use ast_manager_register2() to register with help text for new manager commands */ 00131 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL) 00132 00133 00134 /*! \brief Register a manager command with the manager interface 00135 \param action Name of the requested Action: 00136 \param authority Required authority for this command 00137 \param func Function to call for this command 00138 \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands 00139 \param description Help text, several lines 00140 */ 00141 int ast_manager_register2( 00142 const char *action, 00143 int authority, 00144 int (*func)(struct mansession *s, const struct message *m), 00145 const char *synopsis, 00146 const char *description); 00147 00148 /*! \brief Unregister a registered manager command 00149 \param action Name of registered Action: 00150 */ 00151 int ast_manager_unregister( char *action ); 00152 00153 /*! 00154 * \brief Verify a session's read permissions against a permission mask. 00155 * \param ident session identity 00156 * \param perm permission mask to verify 00157 * \retval 1 if the session has the permission mask capabilities 00158 * \retval 0 otherwise 00159 */ 00160 int astman_verify_session_readpermissions(uint32_t ident, int perm); 00161 00162 /*! 00163 * \brief Verify a session's write permissions against a permission mask. 00164 * \param ident session identity 00165 * \param perm permission mask to verify 00166 * \retval 1 if the session has the permission mask capabilities, otherwise 0 00167 * \retval 0 otherwise 00168 */ 00169 int astman_verify_session_writepermissions(uint32_t ident, int perm); 00170 00171 /*! \brief External routines may send asterisk manager events this way 00172 * \param category Event category, matches manager authorization 00173 \param event Event name 00174 \param contents Contents of event 00175 */ 00176 00177 /* XXX the parser in gcc 2.95 gets confused if you don't put a space 00178 * between the last arg before VA_ARGS and the comma */ 00179 #define manager_event(category, event, contents , ...) \ 00180 __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__) 00181 00182 int __attribute__((format(printf, 6, 7))) __manager_event(int category, const char *event, 00183 const char *file, int line, const char *func, 00184 const char *contents, ...); 00185 00186 /*! \brief Get header from mananger transaction */ 00187 const char *astman_get_header(const struct message *m, char *var); 00188 00189 /*! \brief Get a linked list of the Variable: headers */ 00190 struct ast_variable *astman_get_variables(const struct message *m); 00191 00192 /*! \brief Send error in manager transaction */ 00193 void astman_send_error(struct mansession *s, const struct message *m, char *error); 00194 00195 /*! \brief Send response in manager transaction */ 00196 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg); 00197 00198 /*! \brief Send ack in manager transaction */ 00199 void astman_send_ack(struct mansession *s, const struct message *m, char *msg); 00200 00201 /*! \brief Send ack in manager list transaction */ 00202 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag); 00203 00204 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...); 00205 00206 /*! \brief Determinie if a manager session ident is authenticated */ 00207 int astman_is_authed(uint32_t ident); 00208 00209 /*! \brief Called by Asterisk initialization */ 00210 int init_manager(void); 00211 00212 /*! \brief Called by Asterisk module functions and the CLI command */ 00213 int reload_manager(void); 00214 00215 #endif /* _ASTERISK_MANAGER_H */