Fri Aug 24 02:26:54 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_variableastman_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,
 )     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(), change_hold_state(), 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(), 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 2499 of file manager.c.

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

02500 {
02501    int result = 0;
02502    struct mansession *s;
02503 
02504    AST_LIST_LOCK(&sessions);
02505    AST_LIST_TRAVERSE(&sessions, s, list) {
02506       ast_mutex_lock(&s->__lock);
02507       if ((s->managerid == ident) && (s->readperm & perm)) {
02508          result = 1;
02509          ast_mutex_unlock(&s->__lock);
02510          break;
02511       }
02512       ast_mutex_unlock(&s->__lock);
02513    }
02514    AST_LIST_UNLOCK(&sessions);
02515    return result;
02516 }

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 2518 of file manager.c.

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

02519 {
02520    int result = 0;
02521    struct mansession *s;
02522 
02523    AST_LIST_LOCK(&sessions);
02524    AST_LIST_TRAVERSE(&sessions, s, list) {
02525       ast_mutex_lock(&s->__lock);
02526       if ((s->managerid == ident) && (s->writeperm & perm)) {
02527          result = 1;
02528          ast_mutex_unlock(&s->__lock);
02529          break;
02530       }
02531       ast_mutex_unlock(&s->__lock);
02532    }
02533    AST_LIST_UNLOCK(&sessions);
02534    return result;
02535 }

void const char int init_manager ( void   ) 

Called by Asterisk initialization

Definition at line 2732 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, ast_channel::flags, 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, users, var, and ast_manager_user::write.

Referenced by main(), and reload_manager().

02733 {
02734    struct ast_config *cfg = NULL;
02735    const char *val;
02736    char *cat = NULL;
02737    int oldportno = portno;
02738    static struct sockaddr_in ba;
02739    int x = 1;
02740    int flags;
02741    int webenabled = 0;
02742    int newhttptimeout = 60;
02743    struct ast_manager_user *user = NULL;
02744 
02745    if (!registered) {
02746       /* Register default actions */
02747       ast_manager_register2("Ping", 0, action_ping, "Keepalive command", mandescr_ping);
02748       ast_manager_register2("Events", 0, action_events, "Control Event Flow", mandescr_events);
02749       ast_manager_register2("Logoff", 0, action_logoff, "Logoff Manager", mandescr_logoff);
02750       ast_manager_register2("Hangup", EVENT_FLAG_CALL, action_hangup, "Hangup Channel", mandescr_hangup);
02751       ast_manager_register("Status", EVENT_FLAG_CALL, action_status, "Lists channel status" );
02752       ast_manager_register2("Setvar", EVENT_FLAG_CALL, action_setvar, "Set Channel Variable", mandescr_setvar );
02753       ast_manager_register2("Getvar", EVENT_FLAG_CALL, action_getvar, "Gets a Channel Variable", mandescr_getvar );
02754       ast_manager_register2("GetConfig", EVENT_FLAG_CONFIG, action_getconfig, "Retrieve configuration", mandescr_getconfig);
02755       ast_manager_register2("UpdateConfig", EVENT_FLAG_CONFIG, action_updateconfig, "Update basic configuration", mandescr_updateconfig);
02756       ast_manager_register2("Redirect", EVENT_FLAG_CALL, action_redirect, "Redirect (transfer) a call", mandescr_redirect );
02757       ast_manager_register2("Originate", EVENT_FLAG_CALL, action_originate, "Originate Call", mandescr_originate);
02758       ast_manager_register2("Command", EVENT_FLAG_COMMAND, action_command, "Execute Asterisk CLI Command", mandescr_command );
02759       ast_manager_register2("ExtensionState", EVENT_FLAG_CALL, action_extensionstate, "Check Extension Status", mandescr_extensionstate );
02760       ast_manager_register2("AbsoluteTimeout", EVENT_FLAG_CALL, action_timeout, "Set Absolute Timeout", mandescr_timeout );
02761       ast_manager_register2("MailboxStatus", EVENT_FLAG_CALL, action_mailboxstatus, "Check Mailbox", mandescr_mailboxstatus );
02762       ast_manager_register2("MailboxCount", EVENT_FLAG_CALL, action_mailboxcount, "Check Mailbox Message Count", mandescr_mailboxcount );
02763       ast_manager_register2("ListCommands", 0, action_listcommands, "List available manager commands", mandescr_listcommands);
02764       ast_manager_register2("UserEvent", EVENT_FLAG_USER, action_userevent, "Send an arbitrary event", mandescr_userevent);
02765       ast_manager_register2("WaitEvent", 0, action_waitevent, "Wait for an event to occur", mandescr_waitevent);
02766 
02767       ast_cli_register_multiple(cli_manager, sizeof(cli_manager) / sizeof(struct ast_cli_entry));
02768       ast_extension_state_add(NULL, NULL, manager_state_cb, NULL);
02769       registered = 1;
02770       /* Append placeholder event so master_eventq never runs dry */
02771       append_event("Event: Placeholder\r\n\r\n", 0);
02772    }
02773    portno = DEFAULT_MANAGER_PORT;
02774    displayconnects = 1;
02775    cfg = ast_config_load("manager.conf");
02776    if (!cfg) {
02777       ast_log(LOG_NOTICE, "Unable to open management configuration manager.conf.  Call management disabled.\n");
02778       return 0;
02779    }
02780    val = ast_variable_retrieve(cfg, "general", "enabled");
02781    if (val)
02782       enabled = ast_true(val);
02783 
02784    val = ast_variable_retrieve(cfg, "general", "block-sockets");
02785    if (val)
02786       block_sockets = ast_true(val);
02787 
02788    val = ast_variable_retrieve(cfg, "general", "webenabled");
02789    if (val)
02790       webenabled = ast_true(val);
02791 
02792    if ((val = ast_variable_retrieve(cfg, "general", "port"))) {
02793       if (sscanf(val, "%d", &portno) != 1) {
02794          ast_log(LOG_WARNING, "Invalid port number '%s'\n", val);
02795          portno = DEFAULT_MANAGER_PORT;
02796       }
02797    }
02798 
02799    if ((val = ast_variable_retrieve(cfg, "general", "displayconnects")))
02800       displayconnects = ast_true(val);
02801 
02802    if ((val = ast_variable_retrieve(cfg, "general", "timestampevents")))
02803       timestampevents = ast_true(val);
02804 
02805    if ((val = ast_variable_retrieve(cfg, "general", "httptimeout")))
02806       newhttptimeout = atoi(val);
02807 
02808    memset(&ba, 0, sizeof(ba));
02809    ba.sin_family = AF_INET;
02810    ba.sin_port = htons(portno);
02811 
02812    if ((val = ast_variable_retrieve(cfg, "general", "bindaddr"))) {
02813       if (!inet_aton(val, &ba.sin_addr)) { 
02814          ast_log(LOG_WARNING, "Invalid address '%s' specified, using 0.0.0.0\n", val);
02815          memset(&ba.sin_addr, 0, sizeof(ba.sin_addr));
02816       }
02817    }
02818    
02819 
02820    if ((asock > -1) && ((portno != oldportno) || !enabled)) {
02821 #if 0
02822       /* Can't be done yet */
02823       close(asock);
02824       asock = -1;
02825 #else
02826       ast_log(LOG_WARNING, "Unable to change management port / enabled\n");
02827 #endif
02828    }
02829 
02830    AST_LIST_LOCK(&users);
02831 
02832    while ((cat = ast_category_browse(cfg, cat))) {
02833       struct ast_variable *var = NULL;
02834 
02835       if (!strcasecmp(cat, "general"))
02836          continue;
02837 
02838       /* Look for an existing entry, if none found - create one and add it to the list */
02839       if (!(user = ast_get_manager_by_name_locked(cat))) {
02840          if (!(user = ast_calloc(1, sizeof(*user))))
02841             break;
02842          /* Copy name over */
02843          ast_copy_string(user->username, cat, sizeof(user->username));
02844          /* Insert into list */
02845          AST_LIST_INSERT_TAIL(&users, user, list);
02846       }
02847 
02848       /* Make sure we keep this user and don't destroy it during cleanup */
02849       user->keep = 1;
02850 
02851       var = ast_variable_browse(cfg, cat);
02852       while (var) {
02853          if (!strcasecmp(var->name, "secret")) {
02854             if (user->secret)
02855                free(user->secret);
02856             user->secret = ast_strdup(var->value);
02857          } else if (!strcasecmp(var->name, "deny") ) {
02858             if (user->deny)
02859                free(user->deny);
02860             user->deny = ast_strdup(var->value);
02861          } else if (!strcasecmp(var->name, "permit") ) {
02862             if (user->permit)
02863                free(user->permit);
02864             user->permit = ast_strdup(var->value);
02865          }  else if (!strcasecmp(var->name, "read") ) {
02866             if (user->read)
02867                free(user->read);
02868             user->read = ast_strdup(var->value);
02869          }  else if (!strcasecmp(var->name, "write") ) {
02870             if (user->write)
02871                free(user->write);
02872             user->write = ast_strdup(var->value);
02873          }  else if (!strcasecmp(var->name, "displayconnects") )
02874             user->displayconnects = ast_true(var->value);
02875          else
02876             ast_log(LOG_DEBUG, "%s is an unknown option.\n", var->name);
02877          var = var->next;
02878       }
02879    }
02880 
02881    /* Perform cleanup - essentially prune out old users that no longer exist */
02882    AST_LIST_TRAVERSE_SAFE_BEGIN(&users, user, list) {
02883       if (user->keep) {
02884          user->keep = 0;
02885          continue;
02886       }
02887       /* We do not need to keep this user so take them out of the list */
02888       AST_LIST_REMOVE_CURRENT(&users, list);
02889       /* Free their memory now */
02890       if (user->secret)
02891          free(user->secret);
02892       if (user->deny)
02893          free(user->deny);
02894       if (user->permit)
02895          free(user->permit);
02896       if (user->read)
02897          free(user->read);
02898       if (user->write)
02899          free(user->write);
02900       free(user);
02901    }
02902    AST_LIST_TRAVERSE_SAFE_END
02903 
02904    AST_LIST_UNLOCK(&users);
02905 
02906    ast_config_destroy(cfg);
02907    
02908    if (webenabled && enabled) {
02909       if (!webregged) {
02910          ast_http_uri_link(&rawmanuri);
02911          ast_http_uri_link(&manageruri);
02912          ast_http_uri_link(&managerxmluri);
02913          webregged = 1;
02914       }
02915    } else {
02916       if (webregged) {
02917          ast_http_uri_unlink(&rawmanuri);
02918          ast_http_uri_unlink(&manageruri);
02919          ast_http_uri_unlink(&managerxmluri);
02920          webregged = 0;
02921       }
02922    }
02923 
02924    if (newhttptimeout > 0)
02925       httptimeout = newhttptimeout;
02926 
02927    /* If not enabled, do nothing */
02928    if (!enabled)
02929       return 0;
02930 
02931    if (asock < 0) {
02932       asock = socket(AF_INET, SOCK_STREAM, 0);
02933       if (asock < 0) {
02934          ast_log(LOG_WARNING, "Unable to create socket: %s\n", strerror(errno));
02935          return -1;
02936       }
02937       setsockopt(asock, SOL_SOCKET, SO_REUSEADDR, &x, sizeof(x));
02938       if (bind(asock, (struct sockaddr *)&ba, sizeof(ba))) {
02939          ast_log(LOG_WARNING, "Unable to bind socket: %s\n", strerror(errno));
02940          close(asock);
02941          asock = -1;
02942          return -1;
02943       }
02944       if (listen(asock, 2)) {
02945          ast_log(LOG_WARNING, "Unable to listen on socket: %s\n", strerror(errno));
02946          close(asock);
02947          asock = -1;
02948          return -1;
02949       }
02950       flags = fcntl(asock, F_GETFL);
02951       fcntl(asock, F_SETFL, flags | O_NONBLOCK);
02952       if (option_verbose)
02953          ast_verbose("Asterisk Management interface listening on port %d\n", portno);
02954       ast_pthread_create_background(&t, NULL, accept_thread, NULL);
02955    }
02956    return 0;
02957 }

int reload_manager ( void   ) 

Definition at line 2959 of file manager.c.

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

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


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().


Generated on Fri Aug 24 02:26:55 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1