5240 update
[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 #define AST_MAX_MANHEADER_LEN 256
62
63 struct mansession;
64
65 struct message {
66         int hdrcount;
67         char headers[AST_MAX_MANHEADERS][AST_MAX_MANHEADER_LEN];
68 };
69
70 struct manager_action {
71         /*! Name of the action */
72         const char *action;
73         /*! Short description of the action */
74         const char *synopsis;
75         /*! Detailed description of the action */
76         const char *description;
77         /*! Permission required for action.  EVENT_FLAG_* */
78         int authority;
79         /*! Function to be called */
80         int (*func)(struct mansession *s, struct message *m);
81         /*! For easy linking */
82         struct manager_action *next;
83 };
84
85 /* External routines may register/unregister manager callbacks this way */
86 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
87
88 /* Use ast_manager_register2 to register with help text for new manager commands */
89
90 /*! Register a manager command with the manager interface */
91 /*!     \param action Name of the requested Action:
92         \param authority Required authority for this command
93         \param func Function to call for this command
94         \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
95         \param description Help text, several lines
96 */
97 int ast_manager_register2(
98         const char *action,
99         int authority,
100         int (*func)(struct mansession *s, struct message *m),
101         const char *synopsis,
102         const char *description);
103
104 /*! Unregister a registred manager command */
105 /*!     \param action Name of registred Action:
106 */
107 int ast_manager_unregister( char *action );
108
109 /*! Add a manager_user to current list of manager */
110 int *ast_manager_add(struct ast_manager_user *amu);
111
112 /*! Get an manager by his name */
113 struct ast_manager_user *ast_get_manager_by_name_locked(const char *name);
114
115 /*! External routines may send asterisk manager events this way */
116 /*!     \param category Event category, matches manager authorization
117         \param event    Event name
118         \param contents Contents of event
119 */
120 int manager_event(int category, const char *event, const char *contents, ...)
121         __attribute__ ((format (printf, 3,4)));
122
123 /*! Get header from mananger transaction */
124 char *astman_get_header(struct message *m, char *var);
125
126 /*! Get a linked list of the Variable: headers */
127 struct ast_variable *astman_get_variables(struct message *m);
128
129 /*! Send error in manager transaction */
130 void astman_send_error(struct mansession *s, struct message *m, char *error);
131 void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
132 void astman_send_ack(struct mansession *s, struct message *m, char *msg);
133
134 void astman_append(struct mansession *s, const char *fmt, ...)
135         __attribute__ ((format (printf, 2, 3)));
136
137
138 /*! Called by Asterisk initialization */
139 int init_manager(void);
140 /*! Called by Asterisk initialization */
141 int reload_manager(void);
142 /*! Add a manager_user to current list of manager */
143 int *ast_manager_add(struct ast_manager_user *amu);
144 int *ast_manager_user_add(struct ast_manager_user *amu);
145 /*! Get an manager by his name */
146 struct ast_manager_user *ast_get_manager_by_name_locked(const char *name);
147
148
149 #endif /* _ASTERISK_MANAGER_H */