Mon Oct 8 12:39:03 2012

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

Generated on Mon Oct 8 12:39:03 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7