Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:49:05 2009

## 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)
struct ast_variable * | astman_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,
|  | d |  | ) | 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(), 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(), 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 1651 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(), 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(), cfg, DEFAULT_MANAGER_PORT, EVENT_FLAG_CALL, EVENT_FLAG_COMMAND, LOG_NOTICE, LOG_WARNING, manager_state_cb(), and option_verbose.

Referenced by main(), and reload_manager().

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

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

External routines may send asterisk manager events this way

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

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

Referenced by ast_module_reload(), and main().

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