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