Sat Aug 6 00:39:30 2011

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 <stdarg.h>
00023 #include <sys/types.h>
00024 #include <sys/socket.h>
00025 #include <netinet/in.h>
00026 #include <arpa/inet.h>
00027 
00028 #include "asterisk/lock.h"
00029 
00030 /*!
00031  \file
00032  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
00033  manage Asterisk with third-party software.
00034 
00035  Manager protocol packages are text fields of the form a: b.  There is
00036  always exactly one space after the colon.
00037 
00038  The first header type is the "Event" header.  Other headers vary from
00039  event to event.  Headers end with standard \r\n termination.
00040  The last line of the manager response or event is an empty line.
00041  (\r\n)
00042 
00043  ** Please try to re-use existing headers to simplify manager message parsing in clients.
00044     Don't re-use an existing header with a new meaning, please.
00045     You can find a reference of standard headers in doc/manager.txt
00046  */
00047 
00048 #define AMI_VERSION        "1.0"
00049 #define DEFAULT_MANAGER_PORT 5038   /* Default port for Asterisk management via TCP */
00050 
00051 #define EVENT_FLAG_SYSTEM     (1 << 0) /* System events such as module load/unload */
00052 #define EVENT_FLAG_CALL       (1 << 1) /* Call event, such as state change, etc */
00053 #define EVENT_FLAG_LOG        (1 << 2) /* Log events */
00054 #define EVENT_FLAG_VERBOSE    (1 << 3) /* Verbose messages */
00055 #define EVENT_FLAG_COMMAND    (1 << 4) /* Ability to read/set commands */
00056 #define EVENT_FLAG_AGENT      (1 << 5) /* Ability to read/set agent info */
00057 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
00058 #define EVENT_FLAG_CONFIG     (1 << 7) /* Ability to modify configurations */
00059 
00060 /* Export manager structures */
00061 #define AST_MAX_MANHEADERS 128
00062 
00063 struct mansession;
00064 
00065 struct message {
00066    unsigned int hdrcount;
00067    const char *headers[AST_MAX_MANHEADERS];
00068 };
00069 
00070 struct manager_action {
00071    /*! Name of the action */
00072    const char *action;
00073    /*! Short description of the action */
00074    const char *synopsis;
00075    /*! Detailed description of the action */
00076    const char *description;
00077    /*! Permission required for action.  EVENT_FLAG_* */
00078    int authority;
00079    /*! Function to be called */
00080    int (*func)(struct mansession *s, const struct message *m);
00081    /*! For easy linking */
00082    struct manager_action *next;
00083 };
00084 
00085 /*! \brief Check if AMI is enabled */
00086 int check_manager_enabled(void);
00087 
00088 /*! \brief Check if AMI/HTTP is enabled */
00089 int check_webmanager_enabled(void);
00090 
00091 /* External routines may register/unregister manager callbacks this way */
00092 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
00093 
00094 /* Use ast_manager_register2 to register with help text for new manager commands */
00095 
00096 /*! Register a manager command with the manager interface */
00097 /*!   \param action Name of the requested Action:
00098    \param authority Required authority for this command
00099    \param func Function to call for this command
00100    \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
00101    \param description Help text, several lines
00102 */
00103 int ast_manager_register2(
00104    const char *action,
00105    int authority,
00106    int (*func)(struct mansession *s, const struct message *m),
00107    const char *synopsis,
00108    const char *description);
00109 
00110 /*! Unregister a registered manager command */
00111 /*!   \param action Name of registered Action:
00112 */
00113 int ast_manager_unregister( char *action );
00114 
00115 /*! 
00116  * \brief Verify a session's read permissions against a permission mask.  
00117  * \param ident session identity
00118  * \param perm permission mask to verify
00119  * \returns 1 if the session has the permission mask capabilities, otherwise 0
00120  */
00121 int astman_verify_session_readpermissions(uint32_t ident, int perm);
00122 
00123 /*!
00124  * \brief Verify a session's write permissions against a permission mask.  
00125  * \param ident session identity
00126  * \param perm permission mask to verify
00127  * \returns 1 if the session has the permission mask capabilities, otherwise 0
00128  */
00129 int astman_verify_session_writepermissions(uint32_t ident, int perm);
00130 
00131 /*! External routines may send asterisk manager events this way */
00132 /*!   \param category   Event category, matches manager authorization
00133    \param event   Event name
00134    \param contents   Contents of event
00135 */
00136 int __attribute__((format(printf, 3,4))) manager_event(int category, const char *event, const char *contents, ...);
00137 
00138 /*! Get header from mananger transaction */
00139 const char *astman_get_header(const struct message *m, char *var);
00140 
00141 /*! Get a linked list of the Variable: headers */
00142 struct ast_variable *astman_get_variables(const struct message *m);
00143 
00144 /*! Send error in manager transaction */
00145 void astman_send_error(struct mansession *s, const struct message *m, char *error);
00146 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
00147 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
00148 
00149 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
00150 
00151 /*! Called by Asterisk initialization */
00152 int init_manager(void);
00153 int reload_manager(void);
00154 
00155 #endif /* _ASTERISK_MANAGER_H */

Generated on Sat Aug 6 00:39:30 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7