Asterisk - The Open Source Telephony Project
21.4.1
|
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 | ast_manager_event_blob |
Struct containing info for an AMI event to send out. More... | |
struct | manager_action |
struct | manager_custom_hook |
struct | message |
Macros | |
#define | AMI_VERSION "10.0.0" |
#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(action, authority, func, synopsis) ast_manager_register2(action, authority, func, AST_MODULE_SELF, synopsis, NULL) |
External routines may register/unregister manager callbacks this way. More... | |
#define | ast_manager_register_xml(action, authority, func) ast_manager_register2(action, authority, func, AST_MODULE_SELF, NULL, NULL) |
Register a manager callback using XML documentation to describe the manager. | |
#define | ast_manager_register_xml_core(action, authority, func) ast_manager_register2(action, authority, func, NULL, NULL, NULL) |
Register a manager callback using XML documentation to describe the manager. More... | |
#define | AST_MAX_MANHEADERS 128 |
Export manager structures. | |
#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... | |
#define | NO_EXTRA_FIELDS "%s", "" |
Constant return values | |
| |
#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 */ |
#define | EVENT_FLAG_SECURITY (1 << 18) /* Security Message as AMI Event */ |
#define | EVENT_FLAG_MESSAGE (1 << 30) /* MESSAGE events. */ |
Typedefs | |
typedef int(* | key_exclusion_cb) (const char *key) |
Callback used to determine whether a key should be skipped when converting a JSON object to a manager blob. More... | |
typedef int(* | manager_hangup_cause_validator_t) (const char *channel_name, const char *cause) |
Callback used by ast_manager_hangup_helper that will validate the cause code. More... | |
typedef void(* | manager_hangup_handler_t) (struct ast_channel *chan, int causecode) |
Callback used by ast_manager_hangup_helper that will actually hangup a channel. More... | |
typedef int(* | manager_hook_t) (int category, const char *event, char *body) |
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... | |
struct ast_str * | ast_manager_build_bridge_state_string (const struct ast_bridge_snapshot *snapshot) |
Generate the AMI message body from a bridge snapshot. More... | |
struct ast_str * | ast_manager_build_bridge_state_string_prefix (const struct ast_bridge_snapshot *snapshot, const char *prefix) |
Generate the AMI message body from a bridge snapshot. More... | |
struct ast_str * | ast_manager_build_channel_state_string (const struct ast_channel_snapshot *snapshot) |
Generate the AMI message body from a channel snapshot. More... | |
struct ast_str * | ast_manager_build_channel_state_string_prefix (const struct ast_channel_snapshot *snapshot, const char *prefix) |
Generate the AMI message body from a channel snapshot. More... | |
int | ast_manager_check_enabled (void) |
Check if AMI is enabled. | |
struct ast_manager_event_blob * | ast_manager_event_blob_create (int event_flags, const char *manager_event, const char *extra_fields_fmt,...) |
Construct a ast_manager_event_blob. More... | |
struct stasis_message_type * | ast_manager_get_generic_type (void) |
Get the stasis_message_type for generic messages. More... | |
struct stasis_message_router * | ast_manager_get_message_router (void) |
Get the stasis_message_router for AMI. More... | |
struct stasis_topic * | ast_manager_get_topic (void) |
Get the Stasis Message Bus API topic for AMI. More... | |
int | ast_manager_hangup_helper (struct mansession *s, const struct message *m, manager_hangup_handler_t handler, manager_hangup_cause_validator_t cause_validator) |
A manager helper function that hangs up a channel using a supplied channel type specific hangup function and cause code validator. More... | |
void | ast_manager_publish_event (const char *type, int class_type, struct ast_json *obj) |
Publish an event to AMI. More... | |
int | ast_manager_register2 (const char *action, int authority, int(*func)(struct mansession *s, const struct message *m), struct ast_module *module, 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... | |
struct ast_str * | ast_manager_str_from_json_object (struct ast_json *blob, key_exclusion_cb exclusion_cb) |
Convert a JSON object into an AMI compatible string. More... | |
int | ast_manager_unregister (const 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... | |
int | ast_str_append_event_header (struct ast_str **fields_string, const char *header, const char *value) |
append an event header to an ast string More... | |
int | ast_webmanager_check_enabled (void) |
Check if AMI/HTTP is enabled. | |
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_datastore * | astman_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 manager transaction. More... | |
struct ast_variable * | astman_get_variables (const struct message *m) |
Get a linked list of the Variable: headers. More... | |
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. | |
int | astman_is_authed (uint32_t ident) |
Determine if a manager session ident is authenticated. | |
void | astman_live_dangerously (int new_live_dangerously) |
Enable/disable the inclusion of 'dangerous' configurations outside of the ast_config_AST_CONFIG_DIR. More... | |
void | astman_send_ack (struct mansession *s, const struct message *m, char *msg) |
Send ack in manager transaction. | |
void | astman_send_error (struct mansession *s, const struct message *m, char *error) |
Send error in manager transaction. | |
void | astman_send_error_va (struct mansession *s, const struct message *m, const char *fmt,...) |
Send error in manager transaction (with va_args support) | |
void | astman_send_list_complete_end (struct mansession *s) |
End the list complete event. More... | |
void | astman_send_list_complete_start (struct mansession *s, const struct message *m, const char *event_name, int count) |
Start the list complete event. More... | |
void | astman_send_listack (struct mansession *s, const struct message *m, char *msg, char *listflag) |
Send ack in manager transaction to begin a list. More... | |
void | astman_send_response (struct mansession *s, const struct message *m, char *resp, char *msg) |
Send response in manager transaction. | |
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 | manager_bridging_init (void) |
Initialize support for AMI channel events. More... | |
int | manager_channels_init (void) |
Initialize support for AMI channel events. More... | |
int | manager_endpoints_init (void) |
Initialize support for AMI endpoint events. More... | |
int | manager_mwi_init (void) |
Initialize support for AMI MWI events. More... | |
int | manager_system_init (void) |
Initialize support for AMI system events. More... | |
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)
Definition in file manager.h.
#define ast_manager_event | ( | chan, | |
category, | |||
event, | |||
contents, | |||
... | |||
) |
#define ast_manager_register | ( | action, | |
authority, | |||
func, | |||
synopsis | |||
) | ast_manager_register2(action, authority, func, AST_MODULE_SELF, synopsis, NULL) |
External routines may register/unregister manager callbacks this way.
#define ast_manager_register_xml_core | ( | action, | |
authority, | |||
func | |||
) | ast_manager_register2(action, authority, func, NULL, NULL, NULL) |
Register a manager callback using XML documentation to describe the manager.
Definition at line 202 of file manager.h.
Referenced by ast_bridging_init(), ast_local_init(), ast_msg_init(), astdb_init(), load_pbx(), and manager_bridging_init().
#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.
category | Event category, matches manager authorization |
event | Event name |
contents | Contents of event |
Definition at line 253 of file manager.h.
Referenced by ast_logger_rotate_channel(), ast_manager_event_blob_create(), channel_dial_cb(), logger_print_normal(), mwi_app_event_cb(), and xmpp_pak_presence().
#define NO_EXTRA_FIELDS "%s", "" |
GCC warns about blank or NULL format strings. So, shenanigans!
Definition at line 533 of file manager.h.
Referenced by bridge_create(), bridge_destroy(), and channel_state_change().
typedef int(* key_exclusion_cb) (const char *key) |
typedef int(* manager_hangup_cause_validator_t) (const char *channel_name, const char *cause) |
typedef void(* manager_hangup_handler_t) (struct ast_channel *chan, int causecode) |
typedef int(* manager_hook_t) (int category, const char *event, char *body) |
struct ast_str* ast_manager_build_bridge_state_string | ( | const struct ast_bridge_snapshot * | snapshot | ) |
Generate the AMI message body from a bridge snapshot.
snapshot | the bridge snapshot for which to generate an AMI message body |
NULL | on error |
Definition at line 267 of file manager_bridges.c.
References ast_manager_build_bridge_state_string_prefix().
struct ast_str* ast_manager_build_bridge_state_string_prefix | ( | const struct ast_bridge_snapshot * | snapshot, |
const char * | prefix | ||
) |
Generate the AMI message body from a bridge snapshot.
snapshot | the bridge snapshot for which to generate an AMI message body |
prefix | What to prepend to the bridge fields |
NULL | on error |
Definition at line 223 of file manager_bridges.c.
References AST_BRIDGE_VIDEO_MODE_NONE, ast_bridge_video_mode_to_string(), ast_str_append(), ast_str_create, ast_str_set(), ast_bridge_snapshot::creator, ast_bridge_snapshot::name, ast_bridge_snapshot::num_channels, ast_bridge_snapshot::subclass, ast_bridge_snapshot::technology, ast_bridge_snapshot::uniqueid, ast_bridge_snapshot::video_mode, and ast_bridge_snapshot::video_source_id.
Referenced by ast_manager_build_bridge_state_string().
struct ast_str* ast_manager_build_channel_state_string | ( | const struct ast_channel_snapshot * | snapshot | ) |
Generate the AMI message body from a channel snapshot.
snapshot | the channel snapshot for which to generate an AMI message body |
NULL | on error |
Definition at line 535 of file manager_channels.c.
References ast_manager_build_channel_state_string_prefix().
Referenced by channel_dial_cb(), and mwi_app_event_cb().
struct ast_str* ast_manager_build_channel_state_string_prefix | ( | const struct ast_channel_snapshot * | snapshot, |
const char * | prefix | ||
) |
Generate the AMI message body from a channel snapshot.
snapshot | the channel snapshot for which to generate an AMI message body |
prefix | What to prepend to the channel fields |
NULL | on error |
Definition at line 461 of file manager_channels.c.
References ast_channel_snapshot_base::accountcode, AST_CHAN_TP_INTERNAL, ast_escape_c_alloc(), AST_LIST_TRAVERSE, ast_state2str(), ast_str_append(), ast_str_create, ast_str_set(), ast_channel_snapshot::base, ast_channel_snapshot::caller, ast_channel_snapshot::connected, ast_channel_snapshot_dialplan::context, ast_channel_snapshot::dialplan, ast_channel_snapshot_dialplan::exten, ast_channel_snapshot_base::language, ast_channel_snapshot_peer::linkedid, ast_channel_snapshot::manager_vars, ast_channel_snapshot_caller::name, ast_channel_snapshot_connected::name, ast_channel_snapshot_base::name, ast_channel_snapshot_caller::number, ast_channel_snapshot_connected::number, ast_channel_snapshot::peer, ast_channel_snapshot_dialplan::priority, S_OR, ast_channel_snapshot::state, ast_channel_snapshot_base::tech_properties, and ast_channel_snapshot_base::uniqueid.
Referenced by action_coreshowchannels(), ast_manager_build_channel_state_string(), channel_dial_cb(), and manager_build_parked_call_string().
struct ast_manager_event_blob* ast_manager_event_blob_create | ( | int | event_flags, |
const char * | manager_event, | ||
const char * | extra_fields_fmt, | ||
... | |||
) |
Construct a ast_manager_event_blob.
event_flags | Flags the event should be raised with. |
manager_event | The event to be raised, should be a string literal. |
extra_fields_fmt | Format string for extra fields to include. Or NO_EXTRA_FIELDS for no extra fields. |
NULL | on error. |
Definition at line 10563 of file manager.c.
References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_ref, ast_string_field_init, ast_string_field_ptr_build_va, ast_manager_event_blob::event_flags, ast_manager_event_blob::extra_fields, manager_event, and ast_manager_event_blob::manager_event.
Referenced by bridge_create(), bridge_destroy(), bridge_video_update(), and channel_state_change().
struct stasis_message_type* ast_manager_get_generic_type | ( | void | ) |
Get the stasis_message_type for generic messages.
Referenced by ast_manager_publish_event(), manager_subscriptions_init(), and publish_load_message_type().
int ast_str_append_event_header | ( | struct ast_str ** | fields_string, |
const char * | header, | ||
const char * | value | ||
) |
append an event header to an ast string
fields_string | pointer to an ast_string pointer. It may be a pointer to a NULL ast_str pointer, in which case the ast_str will be initialized. |
header | The header being applied |
value | the value of the header |
0 | if successful |
non-zero | on failure |
Definition at line 10541 of file manager.c.
References ast_str_append(), and ast_str_create.
int astman_datastore_add | ( | struct mansession * | s, |
struct ast_datastore * | datastore | ||
) |
Add a datastore to a session.
0 | success |
non-zero | failure |
Definition at line 10502 of file manager.c.
References AST_LIST_INSERT_HEAD, and mansession_session::datastores.
struct ast_datastore* astman_datastore_find | ( | struct mansession * | s, |
const struct ast_datastore_info * | info, | ||
const char * | uid | ||
) |
Find a datastore on a session.
NULL | if not found |
Definition at line 10514 of file manager.c.
References AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, mansession_session::datastores, ast_datastore::info, and ast_datastore::uid.
int astman_datastore_remove | ( | struct mansession * | s, |
struct ast_datastore * | datastore | ||
) |
Remove a datastore from a session.
0 | success |
non-zero | failure |
Definition at line 10509 of file manager.c.
References AST_LIST_REMOVE, and mansession_session::datastores.
int astman_verify_session_readpermissions | ( | uint32_t | ident, |
int | perm | ||
) |
Verify a session's read permissions against a permission mask.
ident | session identity |
perm | permission mask to verify |
1 | if the session has the permission mask capabilities |
0 | otherwise |
Definition at line 8364 of file manager.c.
References ao2_global_obj_ref, ao2_iterator_destroy(), ao2_iterator_init(), ao2_ref, mansession_session::managerid, mansession_session::readperm, and unref_mansession().
int astman_verify_session_writepermissions | ( | uint32_t | ident, |
int | perm | ||
) |
Verify a session's write permissions against a permission mask.
ident | session identity |
perm | permission mask to verify |
1 | if the session has the permission mask capabilities, otherwise 0 |
0 | otherwise |
Definition at line 8397 of file manager.c.
References ao2_global_obj_ref, ao2_iterator_destroy(), ao2_iterator_init(), ao2_ref, mansession_session::managerid, unref_mansession(), and mansession_session::writeperm.
int manager_bridging_init | ( | void | ) |
Initialize support for AMI channel events.
0 | on success. |
non-zero | on error. |
Definition at line 683 of file manager_bridges.c.
References ast_bridge_topic_all(), ast_manager_get_message_router(), ast_manager_get_topic(), ast_manager_register_xml_core, ast_register_cleanup(), manager_topic, stasis_forward_all(), and stasis_message_router_add().
int manager_channels_init | ( | void | ) |
Initialize support for AMI channel events.
0 | on success. |
non-zero | on error. |
Definition at line 1308 of file manager_channels.c.
References ast_channel_chanspy_start_type(), ast_channel_chanspy_stop_type(), ast_channel_dial_type(), ast_channel_dtmf_begin_type(), ast_channel_dtmf_end_type(), ast_channel_fax_type(), ast_channel_flash_type(), ast_channel_hangup_handler_type(), ast_channel_hangup_request_type(), ast_channel_hold_type(), ast_channel_mixmonitor_mute_type(), ast_channel_mixmonitor_start_type(), ast_channel_mixmonitor_stop_type(), ast_channel_moh_start_type(), ast_channel_moh_stop_type(), ast_channel_snapshot_type(), ast_channel_topic_all(), ast_channel_unhold_type(), ast_channel_wink_type(), ast_manager_get_message_router(), ast_manager_get_topic(), ast_register_cleanup(), channel_dial_cb(), manager_topic, stasis_forward_all(), and stasis_message_router_add().
int manager_endpoints_init | ( | void | ) |
Initialize support for AMI endpoint events.
0 | on success. |
non-zero | on error. |
Definition at line 52 of file manager_endpoints.c.
References ast_endpoint_contact_state_type(), ast_endpoint_state_type(), ast_endpoint_topic_all_cached(), ast_register_cleanup(), and stasis_message_router_add().
int manager_mwi_init | ( | void | ) |
Initialize support for AMI MWI events.
0 | on success |
non-zero | on error |
Definition at line 155 of file manager_mwi.c.
References ast_manager_get_message_router(), ast_manager_get_topic(), ast_mwi_state_type(), ast_mwi_topic_all(), ast_mwi_vm_app_type(), ast_register_cleanup(), manager_topic, mwi_app_event_cb(), stasis_forward_all(), and stasis_message_router_add().
int manager_system_init | ( | void | ) |
Initialize support for AMI system events.
0 | on success |
non-zero | on error |
Definition at line 43 of file manager_system.c.
References ast_manager_get_message_router(), ast_manager_get_topic(), ast_register_cleanup(), ast_system_topic(), manager_topic, stasis_forward_all(), and system_topic.