Wed Jan 8 2020 09:49:48

Asterisk developer's documentation


manager.h
Go to the documentation of this file.
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 "asterisk/network.h"
23 #include "asterisk/lock.h"
24 #include "asterisk/datastore.h"
25 #include "asterisk/xmldoc.h"
26 
27 /*!
28  \file
29  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
30  manage Asterisk with third-party software.
31 
32  Manager protocol packages are text fields of the form a: b. There is
33  always exactly one space after the colon.
34 
35 \verbatim
36 
37  For Actions replies, the first line of the reply is a "Response:" header with
38  values "success", "error" or "follows". "Follows" implies that the
39  response is coming as separate events with the same ActionID. If the
40  Action request has no ActionID, it will be hard matching events
41  to the Action request in the manager client.
42 
43  The first header type is the "Event" header. Other headers vary from
44  event to event. Headers end with standard \\r\\n termination.
45  The last line of the manager response or event is an empty line.
46  (\\r\\n)
47 
48 \endverbatim
49 
50  \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients.
51  Don't re-use an existing header with a new meaning, please.
52  You can find a reference of standard headers in http://wiki.asterisk.org
53 
54 - \ref manager.c Main manager code file
55  */
56 
57 #define AMI_VERSION "1.1"
58 #define DEFAULT_MANAGER_PORT 5038 /* Default port for Asterisk management via TCP */
59 #define DEFAULT_MANAGER_TLS_PORT 5039 /* Default port for Asterisk management via TCP */
60 
61 /*! \name Constant return values
62  *\note Currently, returning anything other than zero causes the session to terminate.
63  */
64 /*@{ */
65 #define AMI_SUCCESS (0)
66 #define AMI_DESTROY (-1)
67 /*@} */
68 
69 /*! \name Manager event classes */
70 /*@{ */
71 #define EVENT_FLAG_SYSTEM (1 << 0) /* System events such as module load/unload */
72 #define EVENT_FLAG_CALL (1 << 1) /* Call event, such as state change, etc */
73 #define EVENT_FLAG_LOG (1 << 2) /* Log events */
74 #define EVENT_FLAG_VERBOSE (1 << 3) /* Verbose messages */
75 #define EVENT_FLAG_COMMAND (1 << 4) /* Ability to read/set commands */
76 #define EVENT_FLAG_AGENT (1 << 5) /* Ability to read/set agent info */
77 #define EVENT_FLAG_USER (1 << 6) /* Ability to read/set user info */
78 #define EVENT_FLAG_CONFIG (1 << 7) /* Ability to modify configurations */
79 #define EVENT_FLAG_DTMF (1 << 8) /* Ability to read DTMF events */
80 #define EVENT_FLAG_REPORTING (1 << 9) /* Reporting events such as rtcp sent */
81 #define EVENT_FLAG_CDR (1 << 10) /* CDR events */
82 #define EVENT_FLAG_DIALPLAN (1 << 11) /* Dialplan events (VarSet, NewExten) */
83 #define EVENT_FLAG_ORIGINATE (1 << 12) /* Originate a call to an extension */
84 #define EVENT_FLAG_AGI (1 << 13) /* AGI events */
85 #define EVENT_FLAG_HOOKRESPONSE (1 << 14) /* Hook Response */
86 #define EVENT_FLAG_CC (1 << 15) /* Call Completion events */
87 #define EVENT_FLAG_AOC (1 << 16) /* Advice Of Charge events */
88 #define EVENT_FLAG_TEST (1 << 17) /* Test event used to signal the Asterisk Test Suite */
89 /*@} */
90 
91 /*! \brief Export manager structures */
92 #define AST_MAX_MANHEADERS 128
93 
94 /*! \brief Manager Helper Function */
95 typedef int (*manager_hook_t)(int, const char *, char *);
96 
98  /*! Identifier */
99  char *file;
100  /*! helper function */
102  /*! Linked list information */
104 };
105 
106 /*! \brief Check if AMI is enabled */
107 int check_manager_enabled(void);
108 
109 /*! \brief Check if AMI/HTTP is enabled */
110 int check_webmanager_enabled(void);
111 
112 /*! Add a custom hook to be called when an event is fired
113  \param hook struct manager_custom_hook object to add
114 */
116 
117 /*! Delete a custom hook to be called when an event is fired
118  \param hook struct manager_custom_hook object to delete
119 */
121 
122 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback
123  * \param hook the file identifier specified in manager_custom_hook struct when registering a hook
124  * \param msg ami action mesage string e.g. "Action: SipPeers\r\n"
125 
126  * \retval 0 on Success
127  * \retval non-zero on Failure
128 */
129 int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg);
130 
131 struct mansession;
132 
133 struct message {
134  unsigned int hdrcount;
135  const char *headers[AST_MAX_MANHEADERS];
136 };
137 
139  /*! Name of the action */
140  const char *action;
142  AST_STRING_FIELD(synopsis); /*!< Synopsis text (short description). */
143  AST_STRING_FIELD(description); /*!< Description (help text) */
144  AST_STRING_FIELD(syntax); /*!< Syntax text */
145  AST_STRING_FIELD(arguments); /*!< Description of each argument. */
146  AST_STRING_FIELD(seealso); /*!< See also */
147  );
148  /*! Permission required for action. EVENT_FLAG_* */
150  /*! Function to be called */
151  int (*func)(struct mansession *s, const struct message *m);
152  /*! Where the documentation come from. */
153  enum ast_doc_src docsrc;
154  /*! For easy linking */
156  /*!
157  * \brief TRUE if the AMI action is registered and the callback can be called.
158  *
159  * \note Needed to prevent a race between calling the callback
160  * function and unregestring the AMI action object.
161  */
162  unsigned int registered:1;
163  /*! Number of active func() calls in progress. */
164  unsigned int active_count;
165 };
166 
167 /*! \brief External routines may register/unregister manager callbacks this way
168  * \note Use ast_manager_register2() to register with help text for new manager commands */
169 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
170 
171 /*! \brief Register a manager callback using XML documentation to describe the manager. */
172 #define ast_manager_register_xml(a, b, c) ast_manager_register2(a, b, c, NULL, NULL)
173 
174 /*! \brief Register a manager command with the manager interface
175  \param action Name of the requested Action:
176  \param authority Required authority for this command
177  \param func Function to call for this command
178  \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
179  \param description Help text, several lines
180 */
182  const char *action,
183  int authority,
184  int (*func)(struct mansession *s, const struct message *m),
185  const char *synopsis,
186  const char *description);
187 
188 /*! \brief Unregister a registered manager command
189  \param action Name of registered Action:
190 */
191 int ast_manager_unregister( char *action );
192 
193 /*!
194  * \brief Verify a session's read permissions against a permission mask.
195  * \param ident session identity
196  * \param perm permission mask to verify
197  * \retval 1 if the session has the permission mask capabilities
198  * \retval 0 otherwise
199  */
200 int astman_verify_session_readpermissions(uint32_t ident, int perm);
201 
202 /*!
203  * \brief Verify a session's write permissions against a permission mask.
204  * \param ident session identity
205  * \param perm permission mask to verify
206  * \retval 1 if the session has the permission mask capabilities, otherwise 0
207  * \retval 0 otherwise
208  */
209 int astman_verify_session_writepermissions(uint32_t ident, int perm);
210 
211 /*! \brief External routines may send asterisk manager events this way
212  * \param category Event category, matches manager authorization
213  \param event Event name
214  \param contents Contents of event
215 */
216 
217 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
218  * between the last arg before VA_ARGS and the comma */
219 #define manager_event(category, event, contents , ...) \
220  __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
221 #define ast_manager_event(chan, category, event, contents , ...) \
222  do { \
223  struct ast_channel *_chans[] = { chan, }; \
224  __ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \
225  } while (0)
226 #define ast_manager_event_multichan(category, event, nchans, chans, contents , ...) \
227  __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
228 
229 /*! External routines may send asterisk manager events this way
230  * \param category Event category, matches manager authorization
231  * \param event Event name
232  * \param chancount Number of channels in chans parameter
233  * \param chans A pointer to an array of channels involved in the event
234  * \param contents Format string describing event
235  * \since 1.8
236 */
237 int __ast_manager_event_multichan(int category, const char *event, int chancount,
238  struct ast_channel **chans, const char *file, int line, const char *func,
239  const char *contents, ...) __attribute__((format(printf, 8, 9)));
240 
241 /*! \brief Get header from mananger transaction */
242 const char *astman_get_header(const struct message *m, char *var);
243 
244 /*! \brief Get a linked list of the Variable: headers
245  *
246  * \note Order of variables is reversed from the order they are specified in
247  * the manager message
248  */
249 struct ast_variable *astman_get_variables(const struct message *m);
250 
254 };
255 
256 /*! \brief Get a linked list of the Variable: headers with order specified */
257 struct ast_variable *astman_get_variables_order(const struct message *m, enum variable_orders order);
258 
259 /*! \brief Send error in manager transaction */
260 void astman_send_error(struct mansession *s, const struct message *m, char *error);
261 
262 /*! \brief Send response in manager transaction */
263 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
264 
265 /*! \brief Send ack in manager transaction */
266 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
267 
268 /*! \brief Send ack in manager list transaction */
269 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
270 
271 void __attribute__((format(printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
272 
273 /*! \brief Determinie if a manager session ident is authenticated */
274 int astman_is_authed(uint32_t ident);
275 
276 /*! \brief Called by Asterisk initialization */
277 int init_manager(void);
278 
279 /*! \brief Called by Asterisk module functions and the CLI command */
280 int reload_manager(void);
281 
282 /*!
283  * \brief Add a datastore to a session
284  *
285  * \retval 0 success
286  * \retval non-zero failure
287  * \since 1.6.1
288  */
289 
290 int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
291 
292 /*!
293  * \brief Remove a datastore from a session
294  *
295  * \retval 0 success
296  * \retval non-zero failure
297  * \since 1.6.1
298  */
299 int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
300 
301 /*!
302  * \brief Find a datastore on a session
303  *
304  * \retval pointer to the datastore if found
305  * \retval NULL if not found
306  * \since 1.6.1
307  */
308 struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
309 
310 #endif /* _ASTERISK_MANAGER_H */
struct ast_datastore * astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid)
Find a datastore on a session.
Definition: manager.c:7284
Main Channel structure associated with a channel.
Definition: channel.h:742
Asterisk locking-related definitions:
#define AST_MAX_MANHEADERS
Export manager structures.
Definition: manager.h:92
void astman_append(struct mansession *s, const char *fmt,...)
Definition: manager.c:2068
void ast_manager_unregister_hook(struct manager_custom_hook *hook)
Delete a custom hook to be called when an event is fired.
Definition: manager.c:1100
int astman_verify_session_readpermissions(uint32_t ident, int perm)
Verify a session&#39;s read permissions against a permission mask.
Definition: manager.c:5633
int ast_hook_send_action(struct manager_custom_hook *hook, const char *msg)
Registered hooks can call this function to invoke actions and they will receive responses through reg...
Definition: manager.c:1950
void ast_manager_register_hook(struct manager_custom_hook *hook)
Add a custom hook to be called when an event is fired.
Definition: manager.c:1092
int reload_manager(void)
Called by Asterisk module functions and the CLI command.
Definition: manager.c:7267
int(* manager_hook_t)(int, const char *, char *)
Manager Helper Function.
Definition: manager.h:95
const char * action
Definition: manager.h:140
Structure for variables, used for configurations and for channel variables.
Definition: config.h:75
#define var
Definition: ast_expr2f.c:606
Structure for a data store type.
Definition: datastore.h:31
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:235
void astman_send_ack(struct mansession *s, const struct message *m, char *msg)
Send ack in manager transaction.
Definition: manager.c:2135
Structure for a data store object.
Definition: datastore.h:54
int check_manager_enabled(void)
Check if AMI is enabled.
Definition: manager.c:1107
int __ast_manager_event_multichan(int category, const char *event, int chancount, struct ast_channel **chans, const char *file, int line, const char *func, const char *contents,...)
Definition: manager.c:5268
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:28
const char * astman_get_header(const struct message *m, char *var)
Get header from mananger transaction.
Definition: manager.c:1860
Asterisk datastore objects.
int astman_is_authed(uint32_t ident)
Determinie if a manager session ident is authenticated.
Definition: manager.c:5617
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:220
int ast_manager_register2(const char *action, int authority, int(*func)(struct mansession *s, const struct message *m), const char *synopsis, const char *description)
Register a manager command with the manager interface.
Definition: manager.c:5469
void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg)
Send response in manager transaction.
Definition: manager.c:2125
Wrapper for network related headers, masking differences between various operating systems...
struct ast_variable * astman_get_variables(const struct message *m)
Get a linked list of the Variable: headers.
Definition: manager.c:1918
variable_orders
Definition: manager.h:251
static char * synopsis
Definition: func_enum.c:156
int astman_verify_session_writepermissions(uint32_t ident, int perm)
Verify a session&#39;s write permissions against a permission mask.
Definition: manager.c:5659
Asterisk XML Documentation API.
int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore)
Add a datastore to a session.
Definition: manager.c:7272
int check_webmanager_enabled(void)
Check if AMI/HTTP is enabled.
Definition: manager.c:1112
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore)
Remove a datastore from a session.
Definition: manager.c:7279
struct ast_variable * astman_get_variables_order(const struct message *m, enum variable_orders order)
Get a linked list of the Variable: headers with order specified.
Definition: manager.c:1923
static int chancount
Definition: channel.c:102
manager_hook_t helper
Definition: manager.h:101
int init_manager(void)
Called by Asterisk initialization.
Definition: manager.c:7262
void astman_send_error(struct mansession *s, const struct message *m, char *error)
Send error in manager transaction.
Definition: manager.c:2130
unsigned int hdrcount
Definition: manager.h:134
static snd_pcm_format_t format
Definition: chan_alsa.c:93
int ast_manager_unregister(char *action)
Unregister a registered manager command.
Definition: manager.c:5355
void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag)
Send ack in manager list transaction.
Definition: manager.c:2145