Wed Oct 28 11:51:05 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 #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 */

Generated on Wed Oct 28 11:51:05 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6