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 #include "asterisk/xmldoc.h" 00026 00027 /*! 00028 \file 00029 \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to 00030 manage Asterisk with third-party software. 00031 00032 Manager protocol packages are text fields of the form a: b. There is 00033 always exactly one space after the colon. 00034 00035 \verbatim 00036 00037 For Actions replies, the first line of the reply is a "Response:" header with 00038 values "success", "error" or "follows". "Follows" implies that the 00039 response is coming as separate events with the same ActionID. If the 00040 Action request has no ActionID, it will be hard matching events 00041 to the Action request in the manager client. 00042 00043 The first header type is the "Event" header. Other headers vary from 00044 event to event. Headers end with standard \\r\\n termination. 00045 The last line of the manager response or event is an empty line. 00046 (\\r\\n) 00047 00048 \endverbatim 00049 00050 \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients. 00051 Don't re-use an existing header with a new meaning, please. 00052 You can find a reference of standard headers in http://wiki.asterisk.org 00053 00054 - \ref manager.c Main manager code file 00055 */ 00056 00057 #define AMI_VERSION "1.1" 00058 #define DEFAULT_MANAGER_PORT 5038 /* Default port for Asterisk management via TCP */ 00059 00060 /*! \name Constant return values 00061 *\note Currently, returning anything other than zero causes the session to terminate. 00062 */ 00063 /*@{ */ 00064 #define AMI_SUCCESS (0) 00065 #define AMI_DESTROY (-1) 00066 /*@} */ 00067 00068 /*! \name Manager event classes */ 00069 /*@{ */ 00070 #define EVENT_FLAG_SYSTEM (1 << 0) /* System events such as module load/unload */ 00071 #define EVENT_FLAG_CALL (1 << 1) /* Call event, such as state change, etc */ 00072 #define EVENT_FLAG_LOG (1 << 2) /* Log events */ 00073 #define EVENT_FLAG_VERBOSE (1 << 3) /* Verbose messages */ 00074 #define EVENT_FLAG_COMMAND (1 << 4) /* Ability to read/set commands */ 00075 #define EVENT_FLAG_AGENT (1 << 5) /* Ability to read/set agent info */ 00076 #define EVENT_FLAG_USER (1 << 6) /* Ability to read/set user info */ 00077 #define EVENT_FLAG_CONFIG (1 << 7) /* Ability to modify configurations */ 00078 #define EVENT_FLAG_DTMF (1 << 8) /* Ability to read DTMF events */ 00079 #define EVENT_FLAG_REPORTING (1 << 9) /* Reporting events such as rtcp sent */ 00080 #define EVENT_FLAG_CDR (1 << 10) /* CDR events */ 00081 #define EVENT_FLAG_DIALPLAN (1 << 11) /* Dialplan events (VarSet, NewExten) */ 00082 #define EVENT_FLAG_ORIGINATE (1 << 12) /* Originate a call to an extension */ 00083 #define EVENT_FLAG_AGI (1 << 13) /* AGI events */ 00084 #define EVENT_FLAG_HOOKRESPONSE (1 << 14) /* Hook Response */ 00085 #define EVENT_FLAG_CC (1 << 15) /* Call Completion events */ 00086 #define EVENT_FLAG_AOC (1 << 16) /* Advice Of Charge events */ 00087 #define EVENT_FLAG_TEST (1 << 17) /* Test event used to signal the Asterisk Test Suite */ 00088 /*@} */ 00089 00090 /*! \brief Export manager structures */ 00091 #define AST_MAX_MANHEADERS 128 00092 00093 /*! \brief Manager Helper Function */ 00094 typedef int (*manager_hook_t)(int, const char *, char *); 00095 00096 struct manager_custom_hook { 00097 /*! Identifier */ 00098 char *file; 00099 /*! helper function */ 00100 manager_hook_t helper; 00101 /*! Linked list information */ 00102 AST_RWLIST_ENTRY(manager_custom_hook) list; 00103 }; 00104 00105 /*! \brief Check if AMI is enabled */ 00106 int check_manager_enabled(void); 00107 00108 /*! \brief Check if AMI/HTTP is enabled */ 00109 int check_webmanager_enabled(void); 00110 00111 /*! Add a custom hook to be called when an event is fired 00112 \param hook struct manager_custom_hook object to add 00113 */ 00114 void ast_manager_register_hook(struct manager_custom_hook *hook); 00115 00116 /*! Delete a custom hook to be called when an event is fired 00117 \param hook struct manager_custom_hook object to delete 00118 */ 00119 void ast_manager_unregister_hook(struct manager_custom_hook *hook); 00120 00121 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback 00122 * \param hook the file identifier specified in manager_custom_hook struct when registering a hook 00123 * \param msg ami action mesage string e.g. "Action: SipPeers\r\n" 00124 00125 * \retval 0 on Success 00126 * \retval non-zero on Failure 00127 */ 00128 int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg); 00129 00130 struct mansession; 00131 00132 struct message { 00133 unsigned int hdrcount; 00134 const char *headers[AST_MAX_MANHEADERS]; 00135 }; 00136 00137 struct manager_action { 00138 /*! Name of the action */ 00139 const char *action; 00140 AST_DECLARE_STRING_FIELDS( 00141 AST_STRING_FIELD(synopsis); /*!< Synopsis text (short description). */ 00142 AST_STRING_FIELD(description); /*!< Description (help text) */ 00143 AST_STRING_FIELD(syntax); /*!< Syntax text */ 00144 AST_STRING_FIELD(arguments); /*!< Description of each argument. */ 00145 AST_STRING_FIELD(seealso); /*!< See also */ 00146 ); 00147 /*! Permission required for action. EVENT_FLAG_* */ 00148 int authority; 00149 /*! Function to be called */ 00150 int (*func)(struct mansession *s, const struct message *m); 00151 /*! Where the documentation come from. */ 00152 enum ast_doc_src docsrc; 00153 /*! For easy linking */ 00154 AST_RWLIST_ENTRY(manager_action) list; 00155 /*! 00156 * \brief TRUE if the AMI action is registered and the callback can be called. 00157 * 00158 * \note Needed to prevent a race between calling the callback 00159 * function and unregestring the AMI action object. 00160 */ 00161 unsigned int registered:1; 00162 }; 00163 00164 /*! \brief External routines may register/unregister manager callbacks this way 00165 * \note Use ast_manager_register2() to register with help text for new manager commands */ 00166 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL) 00167 00168 /*! \brief Register a manager callback using XML documentation to describe the manager. */ 00169 #define ast_manager_register_xml(a, b, c) ast_manager_register2(a, b, c, NULL, NULL) 00170 00171 /*! \brief Register a manager command with the manager interface 00172 \param action Name of the requested Action: 00173 \param authority Required authority for this command 00174 \param func Function to call for this command 00175 \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands 00176 \param description Help text, several lines 00177 */ 00178 int ast_manager_register2( 00179 const char *action, 00180 int authority, 00181 int (*func)(struct mansession *s, const struct message *m), 00182 const char *synopsis, 00183 const char *description); 00184 00185 /*! \brief Unregister a registered manager command 00186 \param action Name of registered Action: 00187 */ 00188 int ast_manager_unregister( char *action ); 00189 00190 /*! 00191 * \brief Verify a session's read permissions against a permission mask. 00192 * \param ident session identity 00193 * \param perm permission mask to verify 00194 * \retval 1 if the session has the permission mask capabilities 00195 * \retval 0 otherwise 00196 */ 00197 int astman_verify_session_readpermissions(uint32_t ident, int perm); 00198 00199 /*! 00200 * \brief Verify a session's write permissions against a permission mask. 00201 * \param ident session identity 00202 * \param perm permission mask to verify 00203 * \retval 1 if the session has the permission mask capabilities, otherwise 0 00204 * \retval 0 otherwise 00205 */ 00206 int astman_verify_session_writepermissions(uint32_t ident, int perm); 00207 00208 /*! \brief External routines may send asterisk manager events this way 00209 * \param category Event category, matches manager authorization 00210 \param event Event name 00211 \param contents Contents of event 00212 */ 00213 00214 /* XXX the parser in gcc 2.95 gets confused if you don't put a space 00215 * between the last arg before VA_ARGS and the comma */ 00216 #define manager_event(category, event, contents , ...) \ 00217 __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__) 00218 #define ast_manager_event(chan, category, event, contents , ...) \ 00219 do { \ 00220 struct ast_channel *_chans[] = { chan, }; \ 00221 __ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \ 00222 } while (0) 00223 #define ast_manager_event_multichan(category, event, nchans, chans, contents , ...) \ 00224 __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); 00225 00226 /*! External routines may send asterisk manager events this way 00227 * \param category Event category, matches manager authorization 00228 * \param event Event name 00229 * \param chancount Number of channels in chans parameter 00230 * \param chans A pointer to an array of channels involved in the event 00231 * \param contents Format string describing event 00232 * \since 1.8 00233 */ 00234 int __ast_manager_event_multichan(int category, const char *event, int chancount, 00235 struct ast_channel **chans, const char *file, int line, const char *func, 00236 const char *contents, ...) __attribute__((format(printf, 8, 9))); 00237 00238 /*! \brief Get header from mananger transaction */ 00239 const char *astman_get_header(const struct message *m, char *var); 00240 00241 /*! \brief Get a linked list of the Variable: headers */ 00242 struct ast_variable *astman_get_variables(const struct message *m); 00243 00244 /*! \brief Send error in manager transaction */ 00245 void astman_send_error(struct mansession *s, const struct message *m, char *error); 00246 00247 /*! \brief Send response in manager transaction */ 00248 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg); 00249 00250 /*! \brief Send ack in manager transaction */ 00251 void astman_send_ack(struct mansession *s, const struct message *m, char *msg); 00252 00253 /*! \brief Send ack in manager list transaction */ 00254 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag); 00255 00256 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...); 00257 00258 /*! \brief Determinie if a manager session ident is authenticated */ 00259 int astman_is_authed(uint32_t ident); 00260 00261 /*! \brief Called by Asterisk initialization */ 00262 int init_manager(void); 00263 00264 /*! \brief Called by Asterisk module functions and the CLI command */ 00265 int reload_manager(void); 00266 00267 /*! 00268 * \brief Add a datastore to a session 00269 * 00270 * \retval 0 success 00271 * \retval non-zero failure 00272 * \since 1.6.1 00273 */ 00274 00275 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore); 00276 00277 /*! 00278 * \brief Remove a datastore from a session 00279 * 00280 * \retval 0 success 00281 * \retval non-zero failure 00282 * \since 1.6.1 00283 */ 00284 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore); 00285 00286 /*! 00287 * \brief Find a datastore on a session 00288 * 00289 * \retval pointer to the datastore if found 00290 * \retval NULL if not found 00291 * \since 1.6.1 00292 */ 00293 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid); 00294 00295 #endif /* _ASTERISK_MANAGER_H */