Mon Mar 20 08:26:01 2006

Asterisk developer's documentation


Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

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"

Go to the source code of this file.

Data Structures

struct  eventqent
struct  manager_action
struct  mansession
struct  message

Defines

#define ast_manager_register(a, b, c, d)   ast_manager_register2(a, b, c, d, NULL)
#define AST_MAX_MANHEADER_LEN   256
#define AST_MAX_MANHEADERS   80
#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_LOG   (1 << 2)
#define EVENT_FLAG_SYSTEM   (1 << 0)
#define EVENT_FLAG_USER   (1 << 6)
#define EVENT_FLAG_VERBOSE   (1 << 3)

Functions

int ast_carefulwrite (int fd, char *s, int len, int timeoutms)
int ast_manager_register2 (const char *action, int authority, int(*func)(struct mansession *s, 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)
char * astman_get_header (struct message *m, char *var)
ast_variableastman_get_variables (struct message *m)
void astman_send_ack (struct mansession *s, struct message *m, char *msg)
void astman_send_error (struct mansession *s, struct message *m, char *error)
void astman_send_response (struct mansession *s, struct message *m, char *resp, char *msg)
int init_manager (void)
int manager_event (int category, char *event, char *contents,...) __attribute__((format(printf
int reload_manager (void)


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 125 of file manager.h.

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

#define AST_MAX_MANHEADER_LEN   256
 

Definition at line 60 of file manager.h.

#define AST_MAX_MANHEADERS   80
 

Definition at line 59 of file manager.h.

Referenced by session_do().

#define DEFAULT_MANAGER_PORT   5038
 

Definition at line 48 of file manager.h.

#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_hangup(), agent_logoff(), changethread(), load_module(), 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_request(), ast_set_callerid(), ast_setstate(), conf_run(), do_parking_thread(), fast_originate(), forward_message(), init_manager(), join_queue(), leave_queue(), load_module(), manager_log(), manager_state_cb(), notify_new_message(), park_exec(), pbx_extension_helper(), process_sdp(), realtime_exec(), senddialevent(), socket_read(), and vm_execmain().

#define EVENT_FLAG_COMMAND   (1 << 4)
 

Definition at line 54 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 ast_log(), astdb_init(), expire_register(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), iax2_poke_noanswer(), load_module(), parse_register_contact(), quit_handler(), register_verify(), reload_logger(), reload_manager(), sip_poke_noanswer(), sip_reg_timeout(), socket_read(), ss_thread(), update_registry(), and zt_handle_event().

#define EVENT_FLAG_USER   (1 << 6)
 

Definition at line 56 of file manager.h.

Referenced by userevent_exec().

#define EVENT_FLAG_VERBOSE   (1 << 3)
 

Definition at line 53 of file manager.h.


Function Documentation

int init_manager void   ) 
 

Called by Asterisk initialization

Definition at line 1643 of file manager.c.

References accept_thread(), action_command(), action_events(), action_extensionstate(), action_getvar(), action_hangup(), action_listcommands(), action_logoff(), action_mailboxcount(), action_mailboxstatus(), action_originate(), action_ping(), action_redirect(), action_setvar(), action_status(), action_timeout(), asock, ast_cli_register(), ast_config_destroy(), ast_config_load(), ast_extension_state_add(), ast_log(), ast_manager_register, ast_manager_register2(), ast_pthread_create, ast_true(), ast_variable_retrieve(), ast_verbose(), block_sockets, cfg, displayconnects, enabled, EVENT_FLAG_CALL, EVENT_FLAG_COMMAND, LOG_NOTICE, LOG_WARNING, manager_state_cb(), mandescr_command, mandescr_events, mandescr_extensionstate, mandescr_getvar, mandescr_hangup, mandescr_listcommands, mandescr_logoff, mandescr_mailboxcount, mandescr_mailboxstatus, mandescr_originate, mandescr_ping, mandescr_redirect, mandescr_setvar, mandescr_timeout, portno, registered, show_mancmd_cli, show_mancmds_cli, show_manconn_cli, t, and val.

Referenced by main(), and reload_manager().

01644 {
01645    struct ast_config *cfg;
01646    char *val;
01647    int oldportno = portno;
01648    static struct sockaddr_in ba;
01649    int x = 1;
01650    if (!registered) {
01651       /* Register default actions */
01652       ast_manager_register2("Ping", 0, action_ping, "Keepalive command", mandescr_ping);
01653       ast_manager_register2("Events", 0, action_events, "Control Event Flow", mandescr_events);
01654       ast_manager_register2("Logoff", 0, action_logoff, "Logoff Manager", mandescr_logoff);
01655       ast_manager_register2("Hangup", EVENT_FLAG_CALL, action_hangup, "Hangup Channel", mandescr_hangup);
01656       ast_manager_register("Status", EVENT_FLAG_CALL, action_status, "Lists channel status" );
01657       ast_manager_register2("Setvar", EVENT_FLAG_CALL, action_setvar, "Set Channel Variable", mandescr_setvar );
01658       ast_manager_register2("Getvar", EVENT_FLAG_CALL, action_getvar, "Gets a Channel Variable", mandescr_getvar );
01659       ast_manager_register2("Redirect", EVENT_FLAG_CALL, action_redirect, "Redirect (transfer) a call", mandescr_redirect );
01660       ast_manager_register2("Originate", EVENT_FLAG_CALL, action_originate, "Originate Call", mandescr_originate);
01661       ast_manager_register2("Command", EVENT_FLAG_COMMAND, action_command, "Execute Asterisk CLI Command", mandescr_command );
01662       ast_manager_register2("ExtensionState", EVENT_FLAG_CALL, action_extensionstate, "Check Extension Status", mandescr_extensionstate );
01663       ast_manager_register2("AbsoluteTimeout", EVENT_FLAG_CALL, action_timeout, "Set Absolute Timeout", mandescr_timeout );
01664       ast_manager_register2("MailboxStatus", EVENT_FLAG_CALL, action_mailboxstatus, "Check Mailbox", mandescr_mailboxstatus );
01665       ast_manager_register2("MailboxCount", EVENT_FLAG_CALL, action_mailboxcount, "Check Mailbox Message Count", mandescr_mailboxcount );
01666       ast_manager_register2("ListCommands", 0, action_listcommands, "List available manager commands", mandescr_listcommands);
01667 
01668       ast_cli_register(&show_mancmd_cli);
01669       ast_cli_register(&show_mancmds_cli);
01670       ast_cli_register(&show_manconn_cli);
01671       ast_extension_state_add(NULL, NULL, manager_state_cb, NULL);
01672       registered = 1;
01673    }
01674    portno = DEFAULT_MANAGER_PORT;
01675    displayconnects = 1;
01676    cfg = ast_config_load("manager.conf");
01677    if (!cfg) {
01678       ast_log(LOG_NOTICE, "Unable to open management configuration manager.conf.  Call management disabled.\n");
01679       return 0;
01680    }
01681    memset(&ba, 0, sizeof(ba));
01682    val = ast_variable_retrieve(cfg, "general", "enabled");
01683    if (val)
01684       enabled = ast_true(val);
01685 
01686    val = ast_variable_retrieve(cfg, "general", "block-sockets");
01687    if(val)
01688       block_sockets = ast_true(val);
01689 
01690    if ((val = ast_variable_retrieve(cfg, "general", "port"))) {
01691       if (sscanf(val, "%d", &portno) != 1) {
01692          ast_log(LOG_WARNING, "Invalid port number '%s'\n", val);
01693          portno = DEFAULT_MANAGER_PORT;
01694       }
01695    } else if ((val = ast_variable_retrieve(cfg, "general", "portno"))) {
01696       if (sscanf(val, "%d", &portno) != 1) {
01697          ast_log(LOG_WARNING, "Invalid port number '%s'\n", val);
01698          portno = DEFAULT_MANAGER_PORT;
01699       }
01700       ast_log(LOG_NOTICE, "Use of portno in manager.conf deprecated.  Please use 'port=%s' instead.\n", val);
01701    }
01702    /* Parsing the displayconnects */
01703    if ((val = ast_variable_retrieve(cfg, "general", "displayconnects"))) {
01704          displayconnects = ast_true(val);;
01705    }
01706             
01707    
01708    ba.sin_family = AF_INET;
01709    ba.sin_port = htons(portno);
01710    memset(&ba.sin_addr, 0, sizeof(ba.sin_addr));
01711    
01712    if ((val = ast_variable_retrieve(cfg, "general", "bindaddr"))) {
01713       if (!inet_aton(val, &ba.sin_addr)) { 
01714          ast_log(LOG_WARNING, "Invalid address '%s' specified, using 0.0.0.0\n", val);
01715          memset(&ba.sin_addr, 0, sizeof(ba.sin_addr));
01716       }
01717    }
01718    
01719    if ((asock > -1) && ((portno != oldportno) || !enabled)) {
01720 #if 0
01721       /* Can't be done yet */
01722       close(asock);
01723       asock = -1;
01724 #else
01725       ast_log(LOG_WARNING, "Unable to change management port / enabled\n");
01726 #endif
01727    }
01728    ast_config_destroy(cfg);
01729    
01730    /* If not enabled, do nothing */
01731    if (!enabled) {
01732       return 0;
01733    }
01734    if (asock < 0) {
01735       asock = socket(AF_INET, SOCK_STREAM, 0);
01736       if (asock < 0) {
01737          ast_log(LOG_WARNING, "Unable to create socket: %s\n", strerror(errno));
01738          return -1;
01739       }
01740       setsockopt(asock, SOL_SOCKET, SO_REUSEADDR, &x, sizeof(x));
01741       if (bind(asock, (struct sockaddr *)&ba, sizeof(ba))) {
01742          ast_log(LOG_WARNING, "Unable to bind socket: %s\n", strerror(errno));
01743          close(asock);
01744          asock = -1;
01745          return -1;
01746       }
01747       if (listen(asock, 2)) {
01748          ast_log(LOG_WARNING, "Unable to listen on socket: %s\n", strerror(errno));
01749          close(asock);
01750          asock = -1;
01751          return -1;
01752       }
01753       if (option_verbose)
01754          ast_verbose("Asterisk Management interface listening on port %d\n", portno);
01755       ast_pthread_create(&t, NULL, accept_thread, NULL);
01756    }
01757    return 0;
01758 }

int manager_event int  category,
char *  event,
char *  contents,
  ...
 

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

Referenced by __login_exec(), action_agent_callback_login(), add_to_queue(), agent_hangup(), agent_logoff(), ast_change_name(), ast_channel_bridge(), ast_do_masquerade(), ast_hangup(), ast_log(), ast_park_call(), ast_request(), ast_set_callerid(), ast_setstate(), changethread(), conf_run(), do_parking_thread(), expire_register(), fast_originate(), forward_message(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), iax2_poke_noanswer(), join_queue(), leave_queue(), manager_log(), manager_state_cb(), notify_new_message(), park_exec(), parse_register_contact(), pbx_extension_helper(), process_sdp(), quit_handler(), realtime_exec(), register_verify(), reload_logger(), reload_manager(), remove_from_queue(), ring_entry(), senddialevent(), set_member_paused(), sip_poke_noanswer(), sip_reg_timeout(), socket_read(), ss_thread(), try_calling(), update_registry(), update_status(), userevent_exec(), vm_execmain(), and zt_handle_event().

int reload_manager void   ) 
 

Called by Asterisk initialization

Definition at line 1760 of file manager.c.

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

Referenced by ast_module_reload(), and main().

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


Generated on Mon Mar 20 08:26:01 2006 for Asterisk - the Open Source PBX by  doxygen 1.3.9.1