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"

Include dependency graph for manager.h:

Go to the source code of this file.

Data Structures
struct	manager_action
struct	manager_custom_hook
struct	message
Defines
#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.
#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.
#define	AST_MAX_MANHEADERS   128
	Export manager structures.
#define	DEFAULT_MANAGER_PORT   5038
#define	DEFAULT_MANAGER_TLS_PORT   5039
#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.
Constant return values
Note: Currently, returning anything other than zero causes the session to terminate.
#define	AMI_DESTROY   (-1)
#define	AMI_SUCCESS   (0)
Manager event classes
#define	EVENT_FLAG_AGENT   (1 << 5)
#define	EVENT_FLAG_AGI   (1 << 13)
#define	EVENT_FLAG_AOC   (1 << 16)
#define	EVENT_FLAG_CALL   (1 << 1)
#define	EVENT_FLAG_CC   (1 << 15)
#define	EVENT_FLAG_CDR   (1 << 10)
#define	EVENT_FLAG_COMMAND   (1 << 4)
#define	EVENT_FLAG_CONFIG   (1 << 7)
#define	EVENT_FLAG_DIALPLAN   (1 << 11)
#define	EVENT_FLAG_DTMF   (1 << 8)
#define	EVENT_FLAG_HOOKRESPONSE   (1 << 14)
#define	EVENT_FLAG_LOG   (1 << 2)
#define	EVENT_FLAG_ORIGINATE   (1 << 12)
#define	EVENT_FLAG_REPORTING   (1 << 9)
#define	EVENT_FLAG_SYSTEM   (1 << 0)
#define	EVENT_FLAG_TEST   (1 << 17)
#define	EVENT_FLAG_USER   (1 << 6)
#define	EVENT_FLAG_VERBOSE   (1 << 3)
Typedefs
typedef int(*	manager_hook_t )(int, const char *, char *)
	Manager Helper Function.
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.
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.
void	ast_manager_register_hook (struct manager_custom_hook *hook)
	Add a custom hook to be called when an event is fired.
int	ast_manager_unregister (char *action)
	Unregister a registered manager command.
void	ast_manager_unregister_hook (struct manager_custom_hook *hook)
	Delete a custom hook to be called when an event is fired.
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.
struct ast_datastore *	astman_datastore_find (struct mansession *s, const struct ast_datastore_info *info, const char *uid)
	Find a datastore on a session.
int	astman_datastore_remove (struct mansession *s, struct ast_datastore *datastore)
	Remove a datastore from a session.
const char *	astman_get_header (const struct message *m, char *var)
	Get header from mananger transaction.
struct ast_variable *	astman_get_variables (const struct message *m)
	Get a linked list of the Variable: headers.
int	astman_is_authed (uint32_t ident)
	Determinie if a manager session ident is authenticated.
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_listack (struct mansession *s, const struct message *m, char *msg, char *listflag)
	Send ack in manager list transaction.
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.
int	astman_verify_session_writepermissions (uint32_t ident, int perm)
	Verify a session's write permissions against a permission mask.
int	check_manager_enabled (void)
	Check if AMI is enabled.
int	check_webmanager_enabled (void)
	Check if AMI/HTTP is enabled.
int	init_manager (void)
	Called by Asterisk initialization.
int	reload_manager (void)
	Called by Asterisk module functions and the CLI command.

---

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

• manager.c Main manager code file

Definition in file manager.h.

---

Define Documentation

#define AMI_DESTROY   (-1)

Definition at line 66 of file manager.h.

#define AMI_SUCCESS   (0)

Definition at line 65 of file manager.h.

Referenced by change_monitor_action(), do_pause_or_unpause(), manager_mute_mixmonitor(), start_monitor_action(), and stop_monitor_action().

#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)

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__);

Definition at line 226 of file manager.h.

Referenced by action_bridge(), ast_aoc_manager_event(), ast_channel_bridge(), ast_do_masquerade(), ast_do_pickup(), bridge_exec(), channel_spy(), fast_originate(), handle_request_refer(), local_attended_transfer(), manager_bridge_event(), and senddialevent().

#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.

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,
		c		)	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

Definition at line 58 of file manager.h.

Referenced by __init_manager().

#define DEFAULT_MANAGER_TLS_PORT   5039

Definition at line 59 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_AGENT   (1 << 5)

Definition at line 76 of file manager.h.

Referenced by add_to_queue(), load_module(), login_exec(), record_abandoned(), remove_from_queue(), ring_entry(), rna(), send_agent_complete(), set_member_paused(), set_member_penalty(), try_calling(), and update_status().

#define EVENT_FLAG_AGI   (1 << 13)

Definition at line 84 of file manager.h.

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

#define EVENT_FLAG_AOC   (1 << 16)

Definition at line 87 of file manager.h.

Referenced by __init_manager(), and ast_aoc_manager_event().

#define EVENT_FLAG_CALL   (1 << 1)

Definition at line 72 of file manager.h.

Referenced by __ast_change_name_nolink(), __ast_channel_alloc_ap(), __init_manager(), action_bridge(), ast_cdr_setaccount(), ast_cdr_setpeeraccount(), ast_channel_bridge(), ast_do_masquerade(), ast_do_pickup(), ast_features_init(), ast_hangup(), ast_monitor_start(), ast_monitor_stop(), ast_setstate(), bridge_exec(), change_hold_state(), channel_spy(), conf_free(), conf_run(), dahdi_ami_channel_event(), fast_originate(), handle_request_refer(), join_queue(), leave_queue(), load_module(), local_ast_moh_start(), local_ast_moh_stop(), local_attended_transfer(), manager_bridge_event(), manager_state_cb(), notify_new_message(), park_call_full(), parked_call_exec(), phase_e_handler(), post_manager_event(), receivefax_exec(), report_fax_status(), report_new_callerid(), send_talking_event(), senddialendevent(), senddialevent(), sendfax_exec(), socket_process(), and vm_execmain().

#define EVENT_FLAG_CC   (1 << 15)

Definition at line 86 of file manager.h.

Referenced by ast_handle_cc_control_frame(), cc_active(), cc_caller_busy(), cc_caller_offered(), cc_complete(), cc_failed(), cc_monitor_failed(), cc_recalling(), and request_cc().

#define EVENT_FLAG_CDR   (1 << 10)

Definition at line 81 of file manager.h.

Referenced by manager_log().

#define EVENT_FLAG_COMMAND   (1 << 4)

Definition at line 75 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_CONFIG   (1 << 7)

Definition at line 78 of file manager.h.

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

#define EVENT_FLAG_DIALPLAN   (1 << 11)

Definition at line 82 of file manager.h.

Referenced by frame_set_var(), pbx_builtin_setvar_helper(), pbx_extension_helper(), realtime_exec(), and shared_write().

#define EVENT_FLAG_DTMF   (1 << 8)

Definition at line 79 of file manager.h.

Referenced by send_dtmf_event().

#define EVENT_FLAG_HOOKRESPONSE   (1 << 14)

Definition at line 85 of file manager.h.

Referenced by send_string().

#define EVENT_FLAG_LOG   (1 << 2)

Definition at line 73 of file manager.h.

#define EVENT_FLAG_ORIGINATE   (1 << 12)

Definition at line 83 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_REPORTING   (1 << 9)

Definition at line 80 of file manager.h.

Referenced by __init_manager(), ast_rtcp_read(), ast_rtcp_write_sr(), astdb_init(), load_module(), load_pbx(), and log_jitterstats().

#define EVENT_FLAG_SYSTEM   (1 << 0)

Definition at line 71 of file manager.h.

Referenced by __analog_handle_event(), __expire_registry(), __iax2_poke_noanswer(), __init_manager(), action_login(), action_originate(), analog_dnd(), analog_handle_init_event(), astdb_init(), dahdi_dnd(), do_reload(), expire_register(), function_capable_string_allowed_with_auths(), gtalk_answer(), gtalk_new(), handle_alarms(), handle_clear_alarms(), handle_response_invite(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), iax2_ami_channelupdate(), load_module(), load_modules(), logger_print_normal(), main(), parse_register_contact(), private_enum_init(), really_quit(), register_verify(), reload_config(), reload_logger(), sip_new(), sip_poke_noanswer(), sip_reg_timeout(), sip_request_call(), skinny_register(), skinny_unregister(), socket_process(), unload_module(), and update_registry().

#define EVENT_FLAG_TEST   (1 << 17)

Definition at line 88 of file manager.h.

#define EVENT_FLAG_USER   (1 << 6)

Definition at line 77 of file manager.h.

Referenced by __init_manager(), action_userevent(), aji_handle_presence(), aji_log_hook(), and userevent_exec().

#define EVENT_FLAG_VERBOSE   (1 << 3)

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:

	category	Event category, matches manager authorization
	event	Event name
	contents	Contents 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(), 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.

---

Function Documentation

int astman_datastore_add	(	struct mansession *	s,
		struct ast_datastore *	datastore
	)

Add a datastore to a session.

Return values:

	0	success
	non-zero	failure

Since:

1.6.1

Definition at line 7247 of file manager.c.

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

{
   AST_LIST_INSERT_HEAD(&s->session->datastores, datastore, entry);

   return 0;
}

struct ast_datastore* astman_datastore_find	(	struct mansession *	s,
		const struct ast_datastore_info *	info,
		const char *	uid
	)			[read]

Find a datastore on a session.

Return values:

	pointer	to the datastore if found
	NULL	if not found

Since:

1.6.1

Definition at line 7259 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.

{
   struct ast_datastore *datastore = NULL;

   if (info == NULL)
      return NULL;

   AST_LIST_TRAVERSE_SAFE_BEGIN(&s->session->datastores, datastore, entry) {
      if (datastore->info != info) {
         continue;
      }

      if (uid == NULL) {
         /* matched by type only */
         break;
      }

      if ((datastore->uid != NULL) && !strcasecmp(uid, datastore->uid)) {
         /* Matched by type AND uid */
         break;
      }
   }
   AST_LIST_TRAVERSE_SAFE_END;

   return datastore;
}

int astman_datastore_remove	(	struct mansession *	s,
		struct ast_datastore *	datastore
	)

Remove a datastore from a session.

Return values:

	0	success
	non-zero	failure

Since:

1.6.1

Definition at line 7254 of file manager.c.

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

{
   return AST_LIST_REMOVE(&s->session->datastores, datastore, entry) ? 0 : -1;
}

int astman_is_authed

(

uint32_t

ident

)

Determinie if a manager session ident is authenticated.

Definition at line 5592 of file manager.c.

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

Referenced by http_post_callback(), and static_callback().

{
   int authed;
   struct mansession_session *session;

   if (!(session = find_session(ident, 0)))
      return 0;

   authed = (session->authenticated != 0);

   ao2_unlock(session);
   unref_mansession(session);

   return authed;
}

int astman_verify_session_readpermissions	(	uint32_t	ident,
		int	perm
	)

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

Parameters:

	ident	session identity
	perm	permission mask to verify

Return values:

	1	if the session has the permission mask capabilities
	0	otherwise

Definition at line 5608 of file manager.c.

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

{
   int result = 0;
   struct mansession_session *session;
   struct ao2_iterator i;

   if (ident == 0) {
      return 0;
   }

   i = ao2_iterator_init(sessions, 0);
   while ((session = ao2_iterator_next(&i))) {
      ao2_lock(session);
      if ((session->managerid == ident) && (session->readperm & perm)) {
         result = 1;
         ao2_unlock(session);
         unref_mansession(session);
         break;
      }
      ao2_unlock(session);
      unref_mansession(session);
   }
   ao2_iterator_destroy(&i);
   return result;
}

int astman_verify_session_writepermissions	(	uint32_t	ident,
		int	perm
	)

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

Parameters:

	ident	session identity
	perm	permission mask to verify

Return values:

	1	if the session has the permission mask capabilities, otherwise 0
	0	otherwise

Definition at line 5634 of file manager.c.

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

Referenced by http_post_callback().

{
   int result = 0;
   struct mansession_session *session;
   struct ao2_iterator i;

   if (ident == 0) {
      return 0;
   }

   i = ao2_iterator_init(sessions, 0);
   while ((session = ao2_iterator_next(&i))) {
      ao2_lock(session);
      if ((session->managerid == ident) && (session->writeperm & perm)) {
         result = 1;
         ao2_unlock(session);
         unref_mansession(session);
         break;
      }
      ao2_unlock(session);
      unref_mansession(session);
   }
   ao2_iterator_destroy(&i);
   return result;
}

int init_manager

(

void

)

Called by Asterisk initialization.

Definition at line 7237 of file manager.c.

References __init_manager().

Referenced by main().

{
   return __init_manager(0);
}

int reload_manager

(

void

)

Called by Asterisk module functions and the CLI command.

Definition at line 7242 of file manager.c.

References __init_manager().

Referenced by handle_manager_reload().

{
   return __init_manager(1);
}