Wed Jan 8 2020 09:50:15

Asterisk developer's documentation


manager.h File Reference

The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party software. More...

#include "asterisk/network.h"
#include "asterisk/lock.h"
#include "asterisk/datastore.h"
#include "asterisk/xmldoc.h"

Go to the source code of this file.

Data Structures

struct  manager_action
 
struct  manager_custom_hook
 
struct  message
 

Macros

#define AMI_VERSION   "1.1"
 
#define ast_manager_event(chan, category, event, contents,...)
 
#define ast_manager_event_multichan(category, event, nchans, chans, contents,...)   __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
 
#define ast_manager_register(a, b, c, d)   ast_manager_register2(a, b, c, d, NULL)
 External routines may register/unregister manager callbacks this way. More...
 
#define ast_manager_register_xml(a, b, c)   ast_manager_register2(a, b, c, NULL, NULL)
 Register a manager callback using XML documentation to describe the manager. More...
 
#define AST_MAX_MANHEADERS   128
 Export manager structures. More...
 
#define DEFAULT_MANAGER_PORT   5038 /* Default port for Asterisk management via TCP */
 
#define DEFAULT_MANAGER_TLS_PORT   5039 /* Default port for Asterisk management via TCP */
 
#define manager_event(category, event, contents,...)   __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
 External routines may send asterisk manager events this way. More...
 
Constant return values
Note
Currently, returning anything other than zero causes the session to terminate.
#define AMI_SUCCESS   (0)
 
#define AMI_DESTROY   (-1)
 
Manager event classes
#define EVENT_FLAG_SYSTEM   (1 << 0) /* System events such as module load/unload */
 
#define EVENT_FLAG_CALL   (1 << 1) /* Call event, such as state change, etc */
 
#define EVENT_FLAG_LOG   (1 << 2) /* Log events */
 
#define EVENT_FLAG_VERBOSE   (1 << 3) /* Verbose messages */
 
#define EVENT_FLAG_COMMAND   (1 << 4) /* Ability to read/set commands */
 
#define EVENT_FLAG_AGENT   (1 << 5) /* Ability to read/set agent info */
 
#define EVENT_FLAG_USER   (1 << 6) /* Ability to read/set user info */
 
#define EVENT_FLAG_CONFIG   (1 << 7) /* Ability to modify configurations */
 
#define EVENT_FLAG_DTMF   (1 << 8) /* Ability to read DTMF events */
 
#define EVENT_FLAG_REPORTING   (1 << 9) /* Reporting events such as rtcp sent */
 
#define EVENT_FLAG_CDR   (1 << 10) /* CDR events */
 
#define EVENT_FLAG_DIALPLAN   (1 << 11) /* Dialplan events (VarSet, NewExten) */
 
#define EVENT_FLAG_ORIGINATE   (1 << 12) /* Originate a call to an extension */
 
#define EVENT_FLAG_AGI   (1 << 13) /* AGI events */
 
#define EVENT_FLAG_HOOKRESPONSE   (1 << 14) /* Hook Response */
 
#define EVENT_FLAG_CC   (1 << 15) /* Call Completion events */
 
#define EVENT_FLAG_AOC   (1 << 16) /* Advice Of Charge events */
 
#define EVENT_FLAG_TEST   (1 << 17) /* Test event used to signal the Asterisk Test Suite */
 

Typedefs

typedef int(* manager_hook_t )(int, const char *, char *)
 Manager Helper Function. More...
 

Enumerations

enum  variable_orders { ORDER_NATURAL, ORDER_REVERSE }
 

Functions

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,...)
 
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 registered callback. More...
 
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. More...
 
void ast_manager_register_hook (struct manager_custom_hook *hook)
 Add a custom hook to be called when an event is fired. More...
 
int ast_manager_unregister (char *action)
 Unregister a registered manager command. More...
 
void ast_manager_unregister_hook (struct manager_custom_hook *hook)
 Delete a custom hook to be called when an event is fired. More...
 
void astman_append (struct mansession *s, const char *fmt,...)
 
int astman_datastore_add (struct mansession *s, struct ast_datastore *datastore)
 Add a datastore to a session. More...
 
struct ast_datastoreastman_datastore_find (struct mansession *s, const struct ast_datastore_info *info, const char *uid)
 Find a datastore on a session. More...
 
int astman_datastore_remove (struct mansession *s, struct ast_datastore *datastore)
 Remove a datastore from a session. More...
 
const char * astman_get_header (const struct message *m, char *var)
 Get header from mananger transaction. More...
 
struct ast_variableastman_get_variables (const struct message *m)
 Get a linked list of the Variable: headers. More...
 
struct ast_variableastman_get_variables_order (const struct message *m, enum variable_orders order)
 Get a linked list of the Variable: headers with order specified. More...
 
int astman_is_authed (uint32_t ident)
 Determinie if a manager session ident is authenticated. More...
 
void astman_send_ack (struct mansession *s, const struct message *m, char *msg)
 Send ack in manager transaction. More...
 
void astman_send_error (struct mansession *s, const struct message *m, char *error)
 Send error in manager transaction. More...
 
void astman_send_listack (struct mansession *s, const struct message *m, char *msg, char *listflag)
 Send ack in manager list transaction. More...
 
void astman_send_response (struct mansession *s, const struct message *m, char *resp, char *msg)
 Send response in manager transaction. More...
 
int astman_verify_session_readpermissions (uint32_t ident, int perm)
 Verify a session's read permissions against a permission mask. More...
 
int astman_verify_session_writepermissions (uint32_t ident, int perm)
 Verify a session's write permissions against a permission mask. More...
 
int check_manager_enabled (void)
 Check if AMI is enabled. More...
 
int check_webmanager_enabled (void)
 Check if AMI/HTTP is enabled. More...
 
int init_manager (void)
 Called by Asterisk initialization. More...
 
int reload_manager (void)
 Called by Asterisk module functions and the CLI command. More...
 

Detailed Description

The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party software.

Manager protocol packages are text fields of the form a: b. There is always exactly one space after the colon.

 For Actions replies, the first line of the reply is a "Response:" header with
 values "success", "error" or "follows". "Follows" implies that the
 response is coming as separate events with the same ActionID. If the
 Action request has no ActionID, it will be hard matching events
 to the Action request in the manager client.

 The first header type is the "Event" header.  Other headers vary from
 event to event.  Headers end with standard \\r\\n termination.
 The last line of the manager response or event is an empty line.
 (\\r\\n)
Note
Please try to re-use existing headers to simplify manager message parsing in clients. Don't re-use an existing header with a new meaning, please. You can find a reference of standard headers in http://wiki.asterisk.org

Definition in file manager.h.

Macro Definition Documentation

#define AMI_DESTROY   (-1)

Definition at line 66 of file manager.h.

#define AMI_SUCCESS   (0)
#define AMI_VERSION   "1.1"

Definition at line 57 of file manager.h.

Referenced by action_coresettings(), and session_do().

#define ast_manager_event (   chan,
  category,
  event,
  contents,
  ... 
)
Value:
do { \
struct ast_channel *_chans[] = { chan, }; \
__ast_manager_event_multichan(category, event, 1, _chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__); \
} while (0)
Main Channel structure associated with a channel.
Definition: channel.h:742
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

Definition at line 221 of file manager.h.

Referenced by __ast_change_name_nolink(), __ast_channel_alloc_ap(), ast_aoc_manager_event(), ast_cdr_setaccount(), ast_cdr_setpeeraccount(), ast_do_masquerade(), ast_hangup(), ast_monitor_start(), ast_monitor_stop(), ast_setstate(), bridge_exec(), channel_spy(), conf_run(), dahdi_ami_channel_event(), join_queue(), leave_queue(), local_ast_moh_start(), local_ast_moh_stop(), notify_new_message(), park_call_full(), parked_call_exec(), phase_e_handler(), report_new_callerid(), send_dtmf_event(), send_talking_event(), senddialendevent(), socket_process(), and vm_execmain().

#define ast_manager_event_multichan (   category,
  event,
  nchans,
  chans,
  contents,
  ... 
)    __ast_manager_event_multichan(category, event, nchans, chans, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__);
#define ast_manager_register (   a,
  b,
  c,
 
)    ast_manager_register2(a, b, c, d, NULL)

External routines may register/unregister manager callbacks this way.

Note
Use ast_manager_register2() to register with help text for new manager commands

Definition at line 169 of file manager.h.

#define ast_manager_register_xml (   a,
  b,
 
)    ast_manager_register2(a, b, c, NULL, NULL)

Register a manager callback using XML documentation to describe the manager.

Definition at line 172 of file manager.h.

Referenced by __init_manager(), ast_data_init(), ast_features_init(), astdb_init(), load_module(), and load_pbx().

#define AST_MAX_MANHEADERS   128

Export manager structures.

Definition at line 92 of file manager.h.

#define DEFAULT_MANAGER_PORT   5038 /* Default port for Asterisk management via TCP */

Definition at line 58 of file manager.h.

Referenced by __init_manager().

#define DEFAULT_MANAGER_TLS_PORT   5039 /* Default port for Asterisk management via TCP */

Definition at line 59 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_AGENT   (1 << 5) /* Ability to read/set agent info */
#define EVENT_FLAG_AGI   (1 << 13) /* AGI events */

Definition at line 84 of file manager.h.

Referenced by agi_handle_command(), launch_asyncagi(), and load_module().

#define EVENT_FLAG_AOC   (1 << 16) /* Advice Of Charge events */

Definition at line 87 of file manager.h.

Referenced by __init_manager(), and ast_aoc_manager_event().

#define EVENT_FLAG_CC   (1 << 15) /* Call Completion events */
#define EVENT_FLAG_CDR   (1 << 10) /* CDR events */

Definition at line 81 of file manager.h.

Referenced by manager_log().

#define EVENT_FLAG_COMMAND   (1 << 4) /* Ability to read/set commands */

Definition at line 75 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_CONFIG   (1 << 7) /* Ability to modify configurations */

Definition at line 78 of file manager.h.

Referenced by __init_manager(), http_post_callback(), and load_pbx().

#define EVENT_FLAG_DIALPLAN   (1 << 11) /* Dialplan events (VarSet, NewExten) */
#define EVENT_FLAG_DTMF   (1 << 8) /* Ability to read DTMF events */

Definition at line 79 of file manager.h.

Referenced by send_dtmf_event().

#define EVENT_FLAG_HOOKRESPONSE   (1 << 14) /* Hook Response */

Definition at line 85 of file manager.h.

Referenced by send_string().

#define EVENT_FLAG_LOG   (1 << 2) /* Log events */

Definition at line 73 of file manager.h.

#define EVENT_FLAG_ORIGINATE   (1 << 12) /* Originate a call to an extension */

Definition at line 83 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_REPORTING   (1 << 9) /* Reporting events such as rtcp sent */
#define EVENT_FLAG_TEST   (1 << 17) /* Test event used to signal the Asterisk Test Suite */

Definition at line 88 of file manager.h.

#define EVENT_FLAG_USER   (1 << 6) /* Ability to read/set user info */
#define EVENT_FLAG_VERBOSE   (1 << 3) /* Verbose messages */

Definition at line 74 of file manager.h.

#define manager_event (   category,
  event,
  contents,
  ... 
)    __ast_manager_event_multichan(category, event, 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)

External routines may send asterisk manager events this way.

Parameters
categoryEvent category, matches manager authorization
eventEvent name
contentsContents of event

Definition at line 219 of file manager.h.

Referenced by __analog_handle_event(), __expire_registry(), __iax2_poke_noanswer(), __init_manager(), action_userevent(), add_to_queue(), agi_handle_command(), aji_handle_presence(), aji_log_hook(), analog_dnd(), analog_handle_init_event(), ast_handle_cc_control_frame(), ast_rtcp_read(), ast_rtcp_write_sr(), builtin_automonitor(), cc_active(), cc_caller_busy(), cc_caller_offered(), cc_complete(), cc_failed(), cc_monitor_failed(), cc_recalling(), change_hold_state(), conf_free(), dahdi_dnd(), do_reload(), expire_register(), frame_set_var(), gtalk_answer(), gtalk_new(), handle_alarms(), handle_clear_alarms(), handle_response_invite(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), iax2_ami_channelupdate(), launch_asyncagi(), load_modules(), log_jitterstats(), logger_print_normal(), login_exec(), main(), manager_log(), manager_state_cb(), parse_register_contact(), pbx_builtin_setvar_helper(), pbx_extension_helper(), post_manager_event(), private_enum_init(), really_quit(), realtime_exec(), receivefax_exec(), record_abandoned(), register_verify(), reload_config(), reload_logger(), remove_from_queue(), report_fax_status(), request_cc(), ring_entry(), rna(), send_agent_complete(), sendfax_exec(), set_member_paused(), set_member_penalty(), shared_write(), sip_new(), sip_poke_noanswer(), sip_reg_timeout(), sip_request_call(), skinny_register(), skinny_unregister(), socket_process(), try_calling(), unload_module(), update_registry(), update_status(), and userevent_exec().

Typedef Documentation

typedef int(* manager_hook_t)(int, const char *, char *)

Manager Helper Function.

Definition at line 95 of file manager.h.

Enumeration Type Documentation

Enumerator
ORDER_NATURAL 
ORDER_REVERSE 

Definition at line 251 of file manager.h.

251  {
254 };

Function Documentation

int astman_datastore_add ( struct mansession s,
struct ast_datastore datastore 
)

Add a datastore to a session.

Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 7272 of file manager.c.

References AST_LIST_INSERT_HEAD, mansession_session::datastores, and mansession::session.

7274 {
7275  AST_LIST_INSERT_HEAD(&s->session->datastores, datastore, entry);
7276 
7277  return 0;
struct mansession_session::mansession_datastores datastores
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:696
struct mansession_session * session
Definition: manager.c:1013
struct ast_datastore* astman_datastore_find ( struct mansession s,
const struct ast_datastore_info info,
const char *  uid 
)

Find a datastore on a session.

Return values
pointerto the datastore if found
NULLif not found
Since
1.6.1

Definition at line 7284 of file manager.c.

References AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, mansession_session::datastores, ast_datastore::info, mansession::session, and ast_datastore::uid.

7286 {
7287  struct ast_datastore *datastore = NULL;
7288 
7289  if (info == NULL)
7290  return NULL;
7291 
7293  if (datastore->info != info) {
7294  continue;
7295  }
7296 
7297  if (uid == NULL) {
7298  /* matched by type only */
7299  break;
7300  }
7301 
7302  if ((datastore->uid != NULL) && !strcasecmp(uid, datastore->uid)) {
7303  /* Matched by type AND uid */
7304  break;
7305  }
7306  }
7308 
7309  return datastore;
struct ast_datastore::@163 entry
struct mansession_session::mansession_datastores datastores
struct ast_datastore_info * info
Definition: datastore.h:57
Structure for a data store object.
Definition: datastore.h:54
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:600
const char * uid
Definition: datastore.h:55
struct mansession_session * session
Definition: manager.c:1013
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:528
int astman_datastore_remove ( struct mansession s,
struct ast_datastore datastore 
)

Remove a datastore from a session.

Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 7279 of file manager.c.

References AST_LIST_REMOVE, mansession_session::datastores, and mansession::session.

7281 {
7282  return AST_LIST_REMOVE(&s->session->datastores, datastore, entry) ? 0 : -1;
struct ast_datastore::@163 entry
struct mansession_session::mansession_datastores datastores
#define AST_LIST_REMOVE(head, elm, field)
Removes a specific entry from a list.
Definition: linkedlists.h:841
struct mansession_session * session
Definition: manager.c:1013
int astman_is_authed ( uint32_t  ident)

Determinie if a manager session ident is authenticated.

Definition at line 5617 of file manager.c.

References ao2_unlock, mansession_session::authenticated, find_session(), and unref_mansession().

Referenced by http_post_callback(), and static_callback().

5619 {
5620  int authed;
5621  struct mansession_session *session;
5622 
5623  if (!(session = find_session(ident, 0)))
5624  return 0;
5625 
5626  authed = (session->authenticated != 0);
5627 
5628  ao2_unlock(session);
5629  unref_mansession(session);
5630 
5631  return authed;
#define ao2_unlock(a)
Definition: astobj2.h:497
static struct mansession_session * unref_mansession(struct mansession_session *s)
Unreference manager session object. If no more references, then go ahead and delete it...
Definition: manager.c:1330
static struct mansession_session * find_session(uint32_t ident, int incinuse)
Definition: manager.c:5558
int astman_verify_session_readpermissions ( uint32_t  ident,
int  perm 
)

Verify a session's read permissions against a permission mask.

Parameters
identsession identity
permpermission mask to verify
Return values
1if the session has the permission mask capabilities
0otherwise

Definition at line 5633 of file manager.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_lock, ao2_unlock, mansession_session::managerid, mansession_session::readperm, and unref_mansession().

5635 {
5636  int result = 0;
5637  struct mansession_session *session;
5638  struct ao2_iterator i;
5639 
5640  if (ident == 0) {
5641  return 0;
5642  }
5643 
5644  i = ao2_iterator_init(sessions, 0);
5645  while ((session = ao2_iterator_next(&i))) {
5646  ao2_lock(session);
5647  if ((session->managerid == ident) && (session->readperm & perm)) {
5648  result = 1;
5649  ao2_unlock(session);
5650  unref_mansession(session);
5651  break;
5652  }
5653  ao2_unlock(session);
5654  unref_mansession(session);
5655  }
5657  return result;
#define ao2_iterator_next(arg1)
Definition: astobj2.h:1126
#define ao2_unlock(a)
Definition: astobj2.h:497
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags)
Create an iterator for a container.
Definition: astobj2.c:818
static struct mansession_session * unref_mansession(struct mansession_session *s)
Unreference manager session object. If no more references, then go ahead and delete it...
Definition: manager.c:1330
#define ao2_lock(a)
Definition: astobj2.h:488
uint32_t managerid
Definition: manager.c:976
void ao2_iterator_destroy(struct ao2_iterator *i)
Destroy a container iterator.
Definition: astobj2.c:833
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1053
int astman_verify_session_writepermissions ( uint32_t  ident,
int  perm 
)

Verify a session's write permissions against a permission mask.

Parameters
identsession identity
permpermission mask to verify
Return values
1if the session has the permission mask capabilities, otherwise 0
0otherwise

Definition at line 5659 of file manager.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_lock, ao2_unlock, mansession_session::managerid, unref_mansession(), and mansession_session::writeperm.

Referenced by http_post_callback().

5661 {
5662  int result = 0;
5663  struct mansession_session *session;
5664  struct ao2_iterator i;
5665 
5666  if (ident == 0) {
5667  return 0;
5668  }
5669 
5670  i = ao2_iterator_init(sessions, 0);
5671  while ((session = ao2_iterator_next(&i))) {
5672  ao2_lock(session);
5673  if ((session->managerid == ident) && (session->writeperm & perm)) {
5674  result = 1;
5675  ao2_unlock(session);
5676  unref_mansession(session);
5677  break;
5678  }
5679  ao2_unlock(session);
5680  unref_mansession(session);
5681  }
5683  return result;
#define ao2_iterator_next(arg1)
Definition: astobj2.h:1126
#define ao2_unlock(a)
Definition: astobj2.h:497
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags)
Create an iterator for a container.
Definition: astobj2.c:818
static struct mansession_session * unref_mansession(struct mansession_session *s)
Unreference manager session object. If no more references, then go ahead and delete it...
Definition: manager.c:1330
#define ao2_lock(a)
Definition: astobj2.h:488
uint32_t managerid
Definition: manager.c:976
void ao2_iterator_destroy(struct ao2_iterator *i)
Destroy a container iterator.
Definition: astobj2.c:833
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1053
int init_manager ( void  )

Called by Asterisk initialization.

Definition at line 7262 of file manager.c.

References __init_manager().

Referenced by main().

7264 {
7265  return __init_manager(0);
static int __init_manager(int reload)
Definition: manager.c:6839
int reload_manager ( void  )

Called by Asterisk module functions and the CLI command.

Definition at line 7267 of file manager.c.

References __init_manager().

Referenced by handle_manager_reload().

7269 {
7270  return __init_manager(1);
static int __init_manager(int reload)
Definition: manager.c:6839