Thu Jul 9 13:40:37 2009

Asterisk developer's documentation


manager.h

Go to the documentation of this file.
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 */

Generated on Thu Jul 9 13:40:37 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7