Mon Mar 31 07:41:53 2008

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(), 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 bridge_exec(), change_hold_state(), conf_run(), fast_originate(), init_manager(), join_queue(), leave_queue(), load_module(), manager_log(), manager_state_cb(), notify_new_message(), park_call_full(), 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(), and load_module().

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

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

02587 {
02588    int result = 0;
02589    struct mansession *s;
02590 
02591    AST_LIST_LOCK(&sessions);
02592    AST_LIST_TRAVERSE(&sessions, s, list) {
02593       ast_mutex_lock(&s->__lock);
02594       if ((s->managerid == ident) && (s->readperm & perm)) {
02595          result = 1;
02596          ast_mutex_unlock(&s->__lock);
02597          break;
02598       }
02599       ast_mutex_unlock(&s->__lock);
02600    }
02601    AST_LIST_UNLOCK(&sessions);
02602    return result;
02603 }

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

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

02606 {
02607    int result = 0;
02608    struct mansession *s;
02609 
02610    AST_LIST_LOCK(&sessions);
02611    AST_LIST_TRAVERSE(&sessions, s, list) {
02612       ast_mutex_lock(&s->__lock);
02613       if ((s->managerid == ident) && (s->writeperm & perm)) {
02614          result = 1;
02615          ast_mutex_unlock(&s->__lock);
02616          break;
02617       }
02618       ast_mutex_unlock(&s->__lock);
02619    }
02620    AST_LIST_UNLOCK(&sessions);
02621    return result;
02622 }

void const char int init_manager ( void   ) 

Called by Asterisk initialization

Definition at line 2824 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, errno, 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().

02825 {
02826    struct ast_config *cfg = NULL;
02827    const char *val;
02828    char *cat = NULL;
02829    int oldportno = portno;
02830    static struct sockaddr_in ba;
02831    int x = 1;
02832    int flags;
02833    int webenabled = 0;
02834    int newhttptimeout = 60;
02835    struct ast_manager_user *user = NULL;
02836 
02837    if (!registered) {
02838       /* Register default actions */
02839       ast_manager_register2("Ping", 0, action_ping, "Keepalive command", mandescr_ping);
02840       ast_manager_register2("Events", 0, action_events, "Control Event Flow", mandescr_events);
02841       ast_manager_register2("Logoff", 0, action_logoff, "Logoff Manager", mandescr_logoff);
02842       ast_manager_register2("Hangup", EVENT_FLAG_CALL, action_hangup, "Hangup Channel", mandescr_hangup);
02843       ast_manager_register("Status", EVENT_FLAG_CALL, action_status, "Lists channel status" );
02844       ast_manager_register2("Setvar", EVENT_FLAG_CALL, action_setvar, "Set Channel Variable", mandescr_setvar );
02845       ast_manager_register2("Getvar", EVENT_FLAG_CALL, action_getvar, "Gets a Channel Variable", mandescr_getvar );
02846       ast_manager_register2("GetConfig", EVENT_FLAG_CONFIG, action_getconfig, "Retrieve configuration", mandescr_getconfig);
02847       ast_manager_register2("UpdateConfig", EVENT_FLAG_CONFIG, action_updateconfig, "Update basic configuration", mandescr_updateconfig);
02848       ast_manager_register2("Redirect", EVENT_FLAG_CALL, action_redirect, "Redirect (transfer) a call", mandescr_redirect );
02849       ast_manager_register2("Originate", EVENT_FLAG_CALL, action_originate, "Originate Call", mandescr_originate);
02850       ast_manager_register2("Command", EVENT_FLAG_COMMAND, action_command, "Execute Asterisk CLI Command", mandescr_command );
02851       ast_manager_register2("ExtensionState", EVENT_FLAG_CALL, action_extensionstate, "Check Extension Status", mandescr_extensionstate );
02852       ast_manager_register2("AbsoluteTimeout", EVENT_FLAG_CALL, action_timeout, "Set Absolute Timeout", mandescr_timeout );
02853       ast_manager_register2("MailboxStatus", EVENT_FLAG_CALL, action_mailboxstatus, "Check Mailbox", mandescr_mailboxstatus );
02854       ast_manager_register2("MailboxCount", EVENT_FLAG_CALL, action_mailboxcount, "Check Mailbox Message Count", mandescr_mailboxcount );
02855       ast_manager_register2("ListCommands", 0, action_listcommands, "List available manager commands", mandescr_listcommands);
02856       ast_manager_register2("UserEvent", EVENT_FLAG_USER, action_userevent, "Send an arbitrary event", mandescr_userevent);
02857       ast_manager_register2("WaitEvent", 0, action_waitevent, "Wait for an event to occur", mandescr_waitevent);
02858 
02859       ast_cli_register_multiple(cli_manager, sizeof(cli_manager) / sizeof(struct ast_cli_entry));
02860       ast_extension_state_add(NULL, NULL, manager_state_cb, NULL);
02861       registered = 1;
02862       /* Append placeholder event so master_eventq never runs dry */
02863       append_event("Event: Placeholder\r\n\r\n", 0);
02864    }
02865    portno = DEFAULT_MANAGER_PORT;
02866    displayconnects = 1;
02867    cfg = ast_config_load("manager.conf");
02868    if (!cfg) {
02869       ast_log(LOG_NOTICE, "Unable to open management configuration manager.conf.  Call management disabled.\n");
02870       return 0;
02871    }
02872    val = ast_variable_retrieve(cfg, "general", "enabled");
02873    if (val)
02874       enabled = ast_true(val);
02875 
02876    val = ast_variable_retrieve(cfg, "general", "block-sockets");
02877    if (val)
02878       block_sockets = ast_true(val);
02879 
02880    val = ast_variable_retrieve(cfg, "general", "webenabled");
02881    if (val)
02882       webenabled = ast_true(val);
02883 
02884    if ((val = ast_variable_retrieve(cfg, "general", "port"))) {
02885       if (sscanf(val, "%d", &portno) != 1) {
02886          ast_log(LOG_WARNING, "Invalid port number '%s'\n", val);
02887          portno = DEFAULT_MANAGER_PORT;
02888       }
02889    }
02890 
02891    if ((val = ast_variable_retrieve(cfg, "general", "displayconnects")))
02892       displayconnects = ast_true(val);
02893 
02894    if ((val = ast_variable_retrieve(cfg, "general", "timestampevents")))
02895       timestampevents = ast_true(val);
02896 
02897    if ((val = ast_variable_retrieve(cfg, "general", "httptimeout")))
02898       newhttptimeout = atoi(val);
02899 
02900    memset(&ba, 0, sizeof(ba));
02901    ba.sin_family = AF_INET;
02902    ba.sin_port = htons(portno);
02903 
02904    if ((val = ast_variable_retrieve(cfg, "general", "bindaddr"))) {
02905       if (!inet_aton(val, &ba.sin_addr)) { 
02906          ast_log(LOG_WARNING, "Invalid address '%s' specified, using 0.0.0.0\n", val);
02907          memset(&ba.sin_addr, 0, sizeof(ba.sin_addr));
02908       }
02909    }
02910    
02911 
02912    if ((asock > -1) && ((portno != oldportno) || !enabled)) {
02913 #if 0
02914       /* Can't be done yet */
02915       close(asock);
02916       asock = -1;
02917 #else
02918       ast_log(LOG_WARNING, "Unable to change management port / enabled\n");
02919 #endif
02920    }
02921 
02922    AST_LIST_LOCK(&users);
02923 
02924    while ((cat = ast_category_browse(cfg, cat))) {
02925       struct ast_variable *var = NULL;
02926 
02927       if (!strcasecmp(cat, "general"))
02928          continue;
02929 
02930       /* Look for an existing entry, if none found - create one and add it to the list */
02931       if (!(user = ast_get_manager_by_name_locked(cat))) {
02932          if (!(user = ast_calloc(1, sizeof(*user))))
02933             break;
02934          /* Copy name over */
02935          ast_copy_string(user->username, cat, sizeof(user->username));
02936          /* Insert into list */
02937          AST_LIST_INSERT_TAIL(&users, user, list);
02938       }
02939 
02940       /* Make sure we keep this user and don't destroy it during cleanup */
02941       user->keep = 1;
02942 
02943       var = ast_variable_browse(cfg, cat);
02944       while (var) {
02945          if (!strcasecmp(var->name, "secret")) {
02946             if (user->secret)
02947                free(user->secret);
02948             user->secret = ast_strdup(var->value);
02949          } else if (!strcasecmp(var->name, "deny") ) {
02950             if (user->deny)
02951                free(user->deny);
02952             user->deny = ast_strdup(var->value);
02953          } else if (!strcasecmp(var->name, "permit") ) {
02954             if (user->permit)
02955                free(user->permit);
02956             user->permit = ast_strdup(var->value);
02957          }  else if (!strcasecmp(var->name, "read") ) {
02958             if (user->read)
02959                free(user->read);
02960             user->read = ast_strdup(var->value);
02961          }  else if (!strcasecmp(var->name, "write") ) {
02962             if (user->write)
02963                free(user->write);
02964             user->write = ast_strdup(var->value);
02965          }  else if (!strcasecmp(var->name, "displayconnects") )
02966             user->displayconnects = ast_true(var->value);
02967          else
02968             ast_log(LOG_DEBUG, "%s is an unknown option.\n", var->name);
02969          var = var->next;
02970       }
02971    }
02972 
02973    /* Perform cleanup - essentially prune out old users that no longer exist */
02974    AST_LIST_TRAVERSE_SAFE_BEGIN(&users, user, list) {
02975       if (user->keep) {
02976          user->keep = 0;
02977          continue;
02978       }
02979       /* We do not need to keep this user so take them out of the list */
02980       AST_LIST_REMOVE_CURRENT(&users, list);
02981       /* Free their memory now */
02982       if (user->secret)
02983          free(user->secret);
02984       if (user->deny)
02985          free(user->deny);
02986       if (user->permit)
02987          free(user->permit);
02988       if (user->read)
02989          free(user->read);
02990       if (user->write)
02991          free(user->write);
02992       free(user);
02993    }
02994    AST_LIST_TRAVERSE_SAFE_END
02995 
02996    AST_LIST_UNLOCK(&users);
02997 
02998    ast_config_destroy(cfg);
02999    
03000    if (webenabled && enabled) {
03001       if (!webregged) {
03002          ast_http_uri_link(&rawmanuri);
03003          ast_http_uri_link(&manageruri);
03004          ast_http_uri_link(&managerxmluri);
03005          webregged = 1;
03006       }
03007    } else {
03008       if (webregged) {
03009          ast_http_uri_unlink(&rawmanuri);
03010          ast_http_uri_unlink(&manageruri);
03011          ast_http_uri_unlink(&managerxmluri);
03012          webregged = 0;
03013       }
03014    }
03015 
03016    if (newhttptimeout > 0)
03017       httptimeout = newhttptimeout;
03018 
03019    /* If not enabled, do nothing */
03020    if (!enabled)
03021       return 0;
03022 
03023    if (asock < 0) {
03024       asock = socket(AF_INET, SOCK_STREAM, 0);
03025       if (asock < 0) {
03026          ast_log(LOG_WARNING, "Unable to create socket: %s\n", strerror(errno));
03027          return -1;
03028       }
03029       setsockopt(asock, SOL_SOCKET, SO_REUSEADDR, &x, sizeof(x));
03030       if (bind(asock, (struct sockaddr *)&ba, sizeof(ba))) {
03031          ast_log(LOG_WARNING, "Unable to bind socket: %s\n", strerror(errno));
03032          close(asock);
03033          asock = -1;
03034          return -1;
03035       }
03036       if (listen(asock, 2)) {
03037          ast_log(LOG_WARNING, "Unable to listen on socket: %s\n", strerror(errno));
03038          close(asock);
03039          asock = -1;
03040          return -1;
03041       }
03042       flags = fcntl(asock, F_GETFL);
03043       fcntl(asock, F_SETFL, flags | O_NONBLOCK);
03044       if (option_verbose)
03045          ast_verbose("Asterisk Management interface listening on port %d\n", portno);
03046       ast_pthread_create_background(&t, NULL, accept_thread, NULL);
03047    }
03048    return 0;
03049 }

int reload_manager ( void   ) 

Definition at line 3051 of file manager.c.

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

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


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 Mon Mar 31 07:41:53 2008 for Asterisk - the Open Source PBX by  doxygen 1.5.1