New CLI command "Core show settings" to list some core settings
[asterisk/asterisk.git] / include / asterisk / manager.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _ASTERISK_MANAGER_H
20 #define _ASTERISK_MANAGER_H
21
22 #include <stdarg.h>
23 #include <sys/types.h>
24 #include <sys/socket.h>
25 #include <netinet/in.h>
26 #include <arpa/inet.h>
27
28 #include "asterisk/lock.h"
29
30 /*!
31  \file
32  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
33  manage Asterisk with third-party software.
34
35  Manager protocol packages are text fields of the form a: b.  There is
36  always exactly one space after the colon.
37
38  The first header type is the "Event" header.  Other headers vary from
39  event to event.  Headers end with standard \r\n termination.
40  The last line of the manager response or event is an empty line.
41  (\r\n)
42
43  ** Please try to re-use existing headers to simplify manager message parsing in clients.
44     Don't re-use an existing header with a new meaning, please.
45     You can find a reference of standard headers in doc/manager.txt
46  */
47
48 #define DEFAULT_MANAGER_PORT 5038       /* Default port for Asterisk management via TCP */
49
50 #define EVENT_FLAG_SYSTEM               (1 << 0) /* System events such as module load/unload */
51 #define EVENT_FLAG_CALL                 (1 << 1) /* Call event, such as state change, etc */
52 #define EVENT_FLAG_LOG                  (1 << 2) /* Log events */
53 #define EVENT_FLAG_VERBOSE              (1 << 3) /* Verbose messages */
54 #define EVENT_FLAG_COMMAND              (1 << 4) /* Ability to read/set commands */
55 #define EVENT_FLAG_AGENT                (1 << 5) /* Ability to read/set agent info */
56 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
57 #define EVENT_FLAG_CONFIG               (1 << 7) /* Ability to modify configurations */
58
59 /* Export manager structures */
60 #define AST_MAX_MANHEADERS 80
61
62 /* Manager Helper Function */
63 typedef int (*manager_hook_t)(int, const char *, char *); 
64
65
66 struct manager_custom_hook {
67         /*! Identifier */
68         char *file;
69         /*! helper function */
70         manager_hook_t helper;
71         /*! Linked list information */
72         AST_RWLIST_ENTRY(manager_custom_hook) list;
73 };
74
75 /*! \brief Check if AMI is enabled */
76 int check_manager_enabled(void);
77
78 /*! \brief Check if AMI/HTTP is enabled */
79 int check_webmanager_enabled(void);
80
81 /*! Add a custom hook to be called when an event is fired */
82 /*! \param hook struct manager_custom_hook object to add
83 */
84 void ast_manager_register_hook(struct manager_custom_hook *hook);
85
86 /*! Delete a custom hook to be called when an event is fired */
87 /*! \param hook struct manager_custom_hook object to delete
88 */
89 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
90
91 struct mansession;
92
93 struct message {
94         unsigned int hdrcount;
95         const char *headers[AST_MAX_MANHEADERS];
96 };
97
98 struct manager_action {
99         /*! Name of the action */
100         const char *action;
101         /*! Short description of the action */
102         const char *synopsis;
103         /*! Detailed description of the action */
104         const char *description;
105         /*! Permission required for action.  EVENT_FLAG_* */
106         int authority;
107         /*! Function to be called */
108         int (*func)(struct mansession *s, const struct message *m);
109         /*! For easy linking */
110         struct manager_action *next;
111 };
112
113 /* External routines may register/unregister manager callbacks this way */
114 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
115
116 /* Use ast_manager_register2 to register with help text for new manager commands */
117
118 /*! Register a manager command with the manager interface */
119 /*!     \param action Name of the requested Action:
120         \param authority Required authority for this command
121         \param func Function to call for this command
122         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
123         \param description Help text, several lines
124 */
125 int ast_manager_register2(
126         const char *action,
127         int authority,
128         int (*func)(struct mansession *s, const struct message *m),
129         const char *synopsis,
130         const char *description);
131
132 /*! Unregister a registred manager command */
133 /*!     \param action Name of registred Action:
134 */
135 int ast_manager_unregister( char *action );
136
137 /*! External routines may send asterisk manager events this way */
138 /*!     \param category Event category, matches manager authorization
139         \param event    Event name
140         \param contents Contents of event
141 */
142
143 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
144  * between the last arg before VA_ARGS and the comma */
145 #define manager_event(category, event, contents , ...)  \
146         __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
147
148 int __attribute__ ((format(printf, 6, 7))) __manager_event(int category, const char *event,
149                                                            const char *file, int line, const char *func,
150                                                            const char *contents, ...);
151
152 /*! Get header from mananger transaction */
153 const char *astman_get_header(const struct message *m, char *var);
154
155 /*! Get a linked list of the Variable: headers */
156 struct ast_variable *astman_get_variables(const struct message *m);
157
158 /*! Send error in manager transaction */
159 void astman_send_error(struct mansession *s, const struct message *m, char *error);
160 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
161 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
162 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
163
164 void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
165
166 /*! Called by Asterisk initialization */
167 int init_manager(void);
168 int reload_manager(void);
169
170 #endif /* _ASTERISK_MANAGER_H */