Mon Apr 30 07:45:13 2007

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 <stdarg.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include "asterisk/lock.h"

Include dependency graph for manager.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	manager_action
struct	message
Defines
#define	ast_manager_register(a, b, c, d)   ast_manager_register2(a, b, c, d, NULL)
#define	AST_MAX_MANHEADERS   128
#define	DEFAULT_MANAGER_PORT   5038
#define	EVENT_FLAG_AGENT   (1 << 5)
#define	EVENT_FLAG_CALL   (1 << 1)
#define	EVENT_FLAG_COMMAND   (1 << 4)
#define	EVENT_FLAG_CONFIG   (1 << 7)
#define	EVENT_FLAG_LOG   (1 << 2)
#define	EVENT_FLAG_SYSTEM   (1 << 0)
#define	EVENT_FLAG_USER   (1 << 6)
#define	EVENT_FLAG_VERBOSE   (1 << 3)
Functions
void	__attribute__ ((format(printf, 2, 3))) astman_append(struct mansession *s
int	__attribute__ ((format(printf, 3, 4))) manager_event(int category
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 new command with manager, including online help. This is the preferred way to register a manager command
int	ast_manager_unregister (char *action)
int const char const char const char *	astman_get_header (const struct message *m, char *var)
ast_variable *	astman_get_variables (const struct message *m)
void	astman_send_ack (struct mansession *s, const struct message *m, char *msg)
void	astman_send_error (struct mansession *s, const struct message *m, char *error)
void	astman_send_response (struct mansession *s, const struct message *m, char *resp, char *msg)
int	astman_verify_session_readpermissions (unsigned long ident, int perm)
	Verify a session's read permissions against a permission mask.
int	astman_verify_session_writepermissions (unsigned long ident, int perm)
	Verify a session's write permissions against a permission mask.
void const char int	init_manager (void)
int	reload_manager (void)
Variables
int const char const char *	contents
int const char *	event
void const char *	fmt

---

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.

The first header type is the "Event" header. Other headers vary from event to event. Headers end with standard
termination. The last line of the manager response or event is an empty line. (
)

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 doc/manager.txt

Definition in file manager.h.

---

Define Documentation

#define ast_manager_register	(	a,
		b,
		c,
		d		)	ast_manager_register2(a, b, c, d, NULL)

Definition at line 85 of file manager.h.

Referenced by astdb_init(), init_manager(), and load_module().

#define AST_MAX_MANHEADERS   128

Definition at line 60 of file manager.h.

Referenced by do_message().

#define DEFAULT_MANAGER_PORT   5038

Definition at line 48 of file manager.h.

Referenced by init_manager().

#define EVENT_FLAG_AGENT   (1 << 5)

Definition at line 55 of file manager.h.

Referenced by __login_exec(), action_agent_callback_login(), add_to_queue(), agent_logoff_maintenance(), changethread(), load_module(), record_abandoned(), remove_from_queue(), ring_entry(), set_member_paused(), try_calling(), and update_status().

#define EVENT_FLAG_CALL   (1 << 1)

Definition at line 51 of file manager.h.

Referenced by ast_change_name(), ast_channel_bridge(), ast_do_masquerade(), ast_hangup(), ast_park_call(), ast_set_callerid(), ast_setstate(), conf_run(), fast_originate(), init_manager(), join_queue(), leave_queue(), load_module(), manager_log(), manager_state_cb(), notify_new_message(), park_exec(), pbx_extension_helper(), phase_e_handler(), post_manager_event(), process_sdp(), realtime_exec(), senddialevent(), socket_process(), and vm_execmain().

#define EVENT_FLAG_COMMAND   (1 << 4)

Definition at line 54 of file manager.h.

Referenced by init_manager().

#define EVENT_FLAG_CONFIG   (1 << 7)

Definition at line 57 of file manager.h.

Referenced by init_manager().

#define EVENT_FLAG_LOG   (1 << 2)

Definition at line 52 of file manager.h.

#define EVENT_FLAG_SYSTEM   (1 << 0)

Definition at line 50 of file manager.h.

Referenced by __expire_registry(), __iax2_poke_noanswer(), ast_log(), astdb_init(), expire_register(), handle_init_event(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), load_module(), parse_register_contact(), quit_handler(), register_verify(), reload_logger(), reload_manager(), sip_poke_noanswer(), sip_reg_timeout(), socket_process(), ss_thread(), update_registry(), and zt_handle_event().

#define EVENT_FLAG_USER   (1 << 6)

Definition at line 56 of file manager.h.

Referenced by action_userevent(), aji_log_hook(), init_manager(), and userevent_exec().

#define EVENT_FLAG_VERBOSE   (1 << 3)

Definition at line 53 of file manager.h.

---

Function Documentation

void __attribute__

(

(format(printf, 2, 3))

)

int __attribute__

(

(format(printf, 3, 4))

)

Parameters:

	category	Event category, matches manager authorization
	event	Event name
	contents	Contents of event

int astman_verify_session_readpermissions	(	unsigned long	ident,
		int	perm
	)

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

Parameters:

	ident	session identity
	perm	permission mask to verify

Returns:

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

Definition at line 2460 of file manager.c.

References AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), result, s, and sessions.

{
   int result = 0;
   struct mansession *s;

   AST_LIST_LOCK(&sessions);
   AST_LIST_TRAVERSE(&sessions, s, list) {
      ast_mutex_lock(&s->__lock);
      if ((s->managerid == ident) && (s->readperm & perm)) {
         result = 1;
         ast_mutex_unlock(&s->__lock);
         break;
      }
      ast_mutex_unlock(&s->__lock);
   }
   AST_LIST_UNLOCK(&sessions);
   return result;
}

int astman_verify_session_writepermissions	(	unsigned long	ident,
		int	perm
	)

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

Parameters:

	ident	session identity
	perm	permission mask to verify

Returns:

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

Definition at line 2479 of file manager.c.

References AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), result, s, and sessions.

{
   int result = 0;
   struct mansession *s;

   AST_LIST_LOCK(&sessions);
   AST_LIST_TRAVERSE(&sessions, s, list) {
      ast_mutex_lock(&s->__lock);
      if ((s->managerid == ident) && (s->writeperm & perm)) {
         result = 1;
         ast_mutex_unlock(&s->__lock);
         break;
      }
      ast_mutex_unlock(&s->__lock);
   }
   AST_LIST_UNLOCK(&sessions);
   return result;
}

void const char int init_manager

(

void

)

Called by Asterisk initialization

Definition at line 2693 of file manager.c.

References accept_thread(), action_command(), action_events(), action_extensionstate(), action_getconfig(), action_getvar(), action_hangup(), action_listcommands(), action_logoff(), action_mailboxcount(), action_mailboxstatus(), action_originate(), action_ping(), action_redirect(), action_setvar(), action_status(), action_timeout(), action_updateconfig(), action_userevent(), action_waitevent(), append_event(), asock, ast_calloc, ast_category_browse(), ast_cli_register_multiple(), ast_config_destroy(), ast_config_load(), ast_extension_state_add(), ast_get_manager_by_name_locked(), ast_http_uri_link(), ast_http_uri_unlink(), AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_log(), ast_manager_register, ast_manager_register2(), ast_pthread_create_background, ast_strdup, ast_true(), ast_variable_browse(), ast_variable_retrieve(), ast_verbose(), block_sockets, cli_manager, DEFAULT_MANAGER_PORT, ast_manager_user::deny, ast_manager_user::displayconnects, displayconnects, enabled, EVENT_FLAG_CALL, EVENT_FLAG_COMMAND, EVENT_FLAG_CONFIG, EVENT_FLAG_USER, free, httptimeout, ast_manager_user::keep, LOG_DEBUG, LOG_WARNING, manager_state_cb(), manageruri, managerxmluri, option_verbose, ast_manager_user::permit, portno, rawmanuri, ast_manager_user::read, ast_manager_user::secret, t, timestampevents, var, and ast_manager_user::write.

Referenced by main(), and reload_manager().

{
   struct ast_config *cfg = NULL;
   const char *val;
   char *cat = NULL;
   int oldportno = portno;
   static struct sockaddr_in ba;
   int x = 1;
   int flags;
   int webenabled = 0;
   int newhttptimeout = 60;
   struct ast_manager_user *user = NULL;

   if (!registered) {
      /* Register default actions */
      ast_manager_register2("Ping", 0, action_ping, "Keepalive command", mandescr_ping);
      ast_manager_register2("Events", 0, action_events, "Control Event Flow", mandescr_events);
      ast_manager_register2("Logoff", 0, action_logoff, "Logoff Manager", mandescr_logoff);
      ast_manager_register2("Hangup", EVENT_FLAG_CALL, action_hangup, "Hangup Channel", mandescr_hangup);
      ast_manager_register("Status", EVENT_FLAG_CALL, action_status, "Lists channel status" );
      ast_manager_register2("Setvar", EVENT_FLAG_CALL, action_setvar, "Set Channel Variable", mandescr_setvar );
      ast_manager_register2("Getvar", EVENT_FLAG_CALL, action_getvar, "Gets a Channel Variable", mandescr_getvar );
      ast_manager_register2("GetConfig", EVENT_FLAG_CONFIG, action_getconfig, "Retrieve configuration", mandescr_getconfig);
      ast_manager_register2("UpdateConfig", EVENT_FLAG_CONFIG, action_updateconfig, "Update basic configuration", mandescr_updateconfig);
      ast_manager_register2("Redirect", EVENT_FLAG_CALL, action_redirect, "Redirect (transfer) a call", mandescr_redirect );
      ast_manager_register2("Originate", EVENT_FLAG_CALL, action_originate, "Originate Call", mandescr_originate);
      ast_manager_register2("Command", EVENT_FLAG_COMMAND, action_command, "Execute Asterisk CLI Command", mandescr_command );
      ast_manager_register2("ExtensionState", EVENT_FLAG_CALL, action_extensionstate, "Check Extension Status", mandescr_extensionstate );
      ast_manager_register2("AbsoluteTimeout", EVENT_FLAG_CALL, action_timeout, "Set Absolute Timeout", mandescr_timeout );
      ast_manager_register2("MailboxStatus", EVENT_FLAG_CALL, action_mailboxstatus, "Check Mailbox", mandescr_mailboxstatus );
      ast_manager_register2("MailboxCount", EVENT_FLAG_CALL, action_mailboxcount, "Check Mailbox Message Count", mandescr_mailboxcount );
      ast_manager_register2("ListCommands", 0, action_listcommands, "List available manager commands", mandescr_listcommands);
      ast_manager_register2("UserEvent", EVENT_FLAG_USER, action_userevent, "Send an arbitrary event", mandescr_userevent);
      ast_manager_register2("WaitEvent", 0, action_waitevent, "Wait for an event to occur", mandescr_waitevent);

      ast_cli_register_multiple(cli_manager, sizeof(cli_manager) / sizeof(struct ast_cli_entry));
      ast_extension_state_add(NULL, NULL, manager_state_cb, NULL);
      registered = 1;
      /* Append placeholder event so master_eventq never runs dry */
      append_event("Event: Placeholder\r\n\r\n", 0);
   }
   portno = DEFAULT_MANAGER_PORT;
   displayconnects = 1;
   cfg = ast_config_load("manager.conf");
   if (!cfg) {
      ast_log(LOG_NOTICE, "Unable to open management configuration manager.conf.  Call management disabled.\n");
      return 0;
   }
   val = ast_variable_retrieve(cfg, "general", "enabled");
   if (val)
      enabled = ast_true(val);

   val = ast_variable_retrieve(cfg, "general", "block-sockets");
   if (val)
      block_sockets = ast_true(val);

   val = ast_variable_retrieve(cfg, "general", "webenabled");
   if (val)
      webenabled = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "port"))) {
      if (sscanf(val, "%d", &portno) != 1) {
         ast_log(LOG_WARNING, "Invalid port number '%s'\n", val);
         portno = DEFAULT_MANAGER_PORT;
      }
   }

   if ((val = ast_variable_retrieve(cfg, "general", "displayconnects")))
      displayconnects = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "timestampevents")))
      timestampevents = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "httptimeout")))
      newhttptimeout = atoi(val);

   memset(&ba, 0, sizeof(ba));
   ba.sin_family = AF_INET;
   ba.sin_port = htons(portno);

   if ((val = ast_variable_retrieve(cfg, "general", "bindaddr"))) {
      if (!inet_aton(val, &ba.sin_addr)) { 
         ast_log(LOG_WARNING, "Invalid address '%s' specified, using 0.0.0.0\n", val);
         memset(&ba.sin_addr, 0, sizeof(ba.sin_addr));
      }
   }
   

   if ((asock > -1) && ((portno != oldportno) || !enabled)) {
#if 0
      /* Can't be done yet */
      close(asock);
      asock = -1;
#else
      ast_log(LOG_WARNING, "Unable to change management port / enabled\n");
#endif
   }

   AST_LIST_LOCK(&users);

   while ((cat = ast_category_browse(cfg, cat))) {
      struct ast_variable *var = NULL;

      if (!strcasecmp(cat, "general"))
         continue;

      /* Look for an existing entry, if none found - create one and add it to the list */
      if (!(user = ast_get_manager_by_name_locked(cat))) {
         if (!(user = ast_calloc(1, sizeof(*user))))
            break;
         /* Copy name over */
         ast_copy_string(user->username, cat, sizeof(user->username));
         /* Insert into list */
         AST_LIST_INSERT_TAIL(&users, user, list);
      }

      /* Make sure we keep this user and don't destroy it during cleanup */
      user->keep = 1;

      var = ast_variable_browse(cfg, cat);
      while (var) {
         if (!strcasecmp(var->name, "secret")) {
            if (user->secret)
               free(user->secret);
            user->secret = ast_strdup(var->value);
         } else if (!strcasecmp(var->name, "deny") ) {
            if (user->deny)
               free(user->deny);
            user->deny = ast_strdup(var->value);
         } else if (!strcasecmp(var->name, "permit") ) {
            if (user->permit)
               free(user->permit);
            user->permit = ast_strdup(var->value);
         }  else if (!strcasecmp(var->name, "read") ) {
            if (user->read)
               free(user->read);
            user->read = ast_strdup(var->value);
         }  else if (!strcasecmp(var->name, "write") ) {
            if (user->write)
               free(user->write);
            user->write = ast_strdup(var->value);
         }  else if (!strcasecmp(var->name, "displayconnects") )
            user->displayconnects = ast_true(var->value);
         else
            ast_log(LOG_DEBUG, "%s is an unknown option.\n", var->name);
         var = var->next;
      }
   }

   /* Perform cleanup - essentially prune out old users that no longer exist */
   AST_LIST_TRAVERSE_SAFE_BEGIN(&users, user, list) {
      if (user->keep) {
         user->keep = 0;
         continue;
      }
      /* We do not need to keep this user so take them out of the list */
      AST_LIST_REMOVE_CURRENT(&users, list);
      /* Free their memory now */
      if (user->secret)
         free(user->secret);
      if (user->deny)
         free(user->deny);
      if (user->permit)
         free(user->permit);
      if (user->read)
         free(user->read);
      if (user->write)
         free(user->write);
      free(user);
   }
   AST_LIST_TRAVERSE_SAFE_END

   AST_LIST_UNLOCK(&users);

   ast_config_destroy(cfg);
   
   if (webenabled && enabled) {
      if (!webregged) {
         ast_http_uri_link(&rawmanuri);
         ast_http_uri_link(&manageruri);
         ast_http_uri_link(&managerxmluri);
         webregged = 1;
      }
   } else {
      if (webregged) {
         ast_http_uri_unlink(&rawmanuri);
         ast_http_uri_unlink(&manageruri);
         ast_http_uri_unlink(&managerxmluri);
         webregged = 0;
      }
   }

   if (newhttptimeout > 0)
      httptimeout = newhttptimeout;

   /* If not enabled, do nothing */
   if (!enabled)
      return 0;

   if (asock < 0) {
      asock = socket(AF_INET, SOCK_STREAM, 0);
      if (asock < 0) {
         ast_log(LOG_WARNING, "Unable to create socket: %s\n", strerror(errno));
         return -1;
      }
      setsockopt(asock, SOL_SOCKET, SO_REUSEADDR, &x, sizeof(x));
      if (bind(asock, (struct sockaddr *)&ba, sizeof(ba))) {
         ast_log(LOG_WARNING, "Unable to bind socket: %s\n", strerror(errno));
         close(asock);
         asock = -1;
         return -1;
      }
      if (listen(asock, 2)) {
         ast_log(LOG_WARNING, "Unable to listen on socket: %s\n", strerror(errno));
         close(asock);
         asock = -1;
         return -1;
      }
      flags = fcntl(asock, F_GETFL);
      fcntl(asock, F_SETFL, flags | O_NONBLOCK);
      if (option_verbose)
         ast_verbose("Asterisk Management interface listening on port %d\n", portno);
      ast_pthread_create_background(&t, NULL, accept_thread, NULL);
   }
   return 0;
}

int reload_manager

(

void

)

Definition at line 2920 of file manager.c.

References EVENT_FLAG_SYSTEM, init_manager(), and manager_event().

{
   manager_event(EVENT_FLAG_SYSTEM, "Reload", "Message: Reload Requested\r\n");
   return init_manager();
}

---

Variable Documentation

int const char const char* contents

Definition at line 129 of file manager.h.

int const char* event

Definition at line 129 of file manager.h.

Referenced by action_userevent(), adsi_process(), ast_rtp_read(), handle_event_nt(), handle_frm(), handle_request_info(), handle_request_notify(), handle_request_subscribe(), handle_soft_key_event_message(), handle_stimulus_message(), log_events(), monitor_main(), onevent(), process_cisco_dtmf(), process_rfc2833(), ql_exec(), receive_ademco_contact_id(), sla_handle_hold_event(), sla_queue_event_full(), sla_thread(), and write_event().

void const char* fmt

Definition at line 142 of file manager.h.

Referenced by __oh323_new(), add_codec_to_sdp(), ast_cdr_getvar(), ast_cli_netstats(), ast_codec_pref_getsize(), ast_openvstream(), ast_request(), ast_rtp_write(), ast_streamfile(), check_header(), get_filestream(), gtalk_new(), handle_open_receive_channel_ack_message(), iax2_request(), local_new(), mgcp_new(), setformat(), sip_new(), skinny_new(), transmit_connect(), try_suggested_sip_codec(), and write_header().

---