Thu May 24 14:22:59 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  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)
int 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.

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_hangup(), 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_init_event(), 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 1644 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, DEFAULT_MANAGER_PORT, 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, option_verbose, portno, show_mancmd_cli, show_mancmds_cli, show_manconn_cli, and t.

Referenced by main(), and reload_manager().

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

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

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

int reload_manager ( void   ) 

Called by Asterisk initialization

Definition at line 1761 of file manager.c.

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

Referenced by ast_module_reload(), and main().

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


Generated on Thu May 24 14:22:59 2007 for Asterisk - the Open Source PBX by  doxygen 1.4.7