Wed Oct 28 11:46:13 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 "asterisk/network.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  manager_custom_hook
struct  message

Defines

#define AMI_VERSION   "1.1"
#define ast_manager_register(a, b, c, d)   ast_manager_register2(a, b, c, d, NULL)
 External routines may register/unregister manager callbacks this way.
#define AST_MAX_MANHEADERS   128
 Export manager structures.
#define DEFAULT_MANAGER_PORT   5038
#define manager_event(category, event, contents,...)   __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)
 External routines may send asterisk manager events this way.
Manager event classes


#define EVENT_FLAG_AGENT   (1 << 5)
#define EVENT_FLAG_CALL   (1 << 1)
#define EVENT_FLAG_CDR   (1 << 10)
#define EVENT_FLAG_COMMAND   (1 << 4)
#define EVENT_FLAG_CONFIG   (1 << 7)
#define EVENT_FLAG_DIALPLAN   (1 << 11)
#define EVENT_FLAG_DTMF   (1 << 8)
#define EVENT_FLAG_LOG   (1 << 2)
#define EVENT_FLAG_ORIGINATE   (1 << 12)
#define EVENT_FLAG_REPORTING   (1 << 9)
#define EVENT_FLAG_SYSTEM   (1 << 0)
#define EVENT_FLAG_USER   (1 << 6)
#define EVENT_FLAG_VERBOSE   (1 << 3)

Typedefs

typedef int(* manager_hook_t )(int, const char *, char *)
 Manager Helper Function.

Functions

int __manager_event (int category, const char *event, const char *file, int line, const char *func, const char *contents,...)
 manager_event: Send AMI event to client
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 manager command with the manager interface.
void ast_manager_register_hook (struct manager_custom_hook *hook)
 Add a custom hook to be called when an event is fired.
int ast_manager_unregister (char *action)
 Unregister a registered manager command.
void ast_manager_unregister_hook (struct manager_custom_hook *hook)
 Delete a custom hook to be called when an event is fired.
void astman_append (struct mansession *s, const char *fmt,...)
const char * astman_get_header (const struct message *m, char *var)
 Get header from mananger transaction.
struct ast_variableastman_get_variables (const struct message *m)
 Get a linked list of the Variable: headers.
int astman_is_authed (uint32_t ident)
 Determinie if a manager session ident is authenticated.
void astman_send_ack (struct mansession *s, const struct message *m, char *msg)
 Send ack in manager transaction.
void astman_send_error (struct mansession *s, const struct message *m, char *error)
 Send error in manager transaction.
void astman_send_listack (struct mansession *s, const struct message *m, char *msg, char *listflag)
 Send ack in manager list transaction.
void astman_send_response (struct mansession *s, const struct message *m, char *resp, char *msg)
 Send response in manager transaction.
int astman_verify_session_readpermissions (uint32_t ident, int perm)
 Verify a session's read permissions against a permission mask.
int astman_verify_session_writepermissions (uint32_t ident, int perm)
 Verify a session's write permissions against a permission mask.
int check_manager_enabled (void)
 Check if AMI is enabled.
int check_webmanager_enabled (void)
 Check if AMI/HTTP is enabled.
int init_manager (void)
 Called by Asterisk initialization.
int reload_manager (void)
 Called by Asterisk module functions and the CLI command.


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.


 For Actions replies, the first line of the reply is a "Response:" header with
 values "success", "error" or "follows". "Follows" implies that the
 response is coming as separate events with the same ActionID. If the
 Action request has no ActionID, it will be hard matching events
 to the Action request in the manager client.

 The first header type is the "Event" header.  Other headers vary from
 event to event.  Headers end with standard \\r\\n termination.
 The last line of the manager response or event is an empty line.
 (\\r\\n)

Note:
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 AMI_VERSION   "1.1"

Definition at line 55 of file manager.h.

Referenced by action_coresettings(), and session_do().

#define ast_manager_register ( a,
b,
c,
 )     ast_manager_register2(a, b, c, d, NULL)

External routines may register/unregister manager callbacks this way.

Note:
Use ast_manager_register2() to register with help text for new manager commands

Definition at line 131 of file manager.h.

Referenced by __init_manager(), ast_features_init(), astdb_init(), and load_module().

#define AST_MAX_MANHEADERS   128

Export manager structures.

Definition at line 76 of file manager.h.

Referenced by do_message(), and generic_http_callback().

#define DEFAULT_MANAGER_PORT   5038

Definition at line 56 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_AGENT   (1 << 5)

#define EVENT_FLAG_CALL   (1 << 1)

#define EVENT_FLAG_CDR   (1 << 10)

Definition at line 70 of file manager.h.

Referenced by manager_log().

#define EVENT_FLAG_COMMAND   (1 << 4)

Definition at line 64 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_CONFIG   (1 << 7)

Definition at line 67 of file manager.h.

Referenced by __init_manager(), load_pbx(), and manager_show_dialplan().

#define EVENT_FLAG_DIALPLAN   (1 << 11)

#define EVENT_FLAG_DTMF   (1 << 8)

Definition at line 68 of file manager.h.

Referenced by send_dtmf_event().

#define EVENT_FLAG_LOG   (1 << 2)

Definition at line 62 of file manager.h.

#define EVENT_FLAG_ORIGINATE   (1 << 12)

Definition at line 72 of file manager.h.

Referenced by __init_manager().

#define EVENT_FLAG_REPORTING   (1 << 9)

#define EVENT_FLAG_SYSTEM   (1 << 0)

#define EVENT_FLAG_USER   (1 << 6)

Definition at line 66 of file manager.h.

Referenced by __init_manager(), action_userevent(), aji_log_hook(), and userevent_exec().

#define EVENT_FLAG_VERBOSE   (1 << 3)

Definition at line 63 of file manager.h.

#define manager_event ( category,
event,
contents,
...   )     __manager_event(category, event, __FILE__, __LINE__, __PRETTY_FUNCTION__, contents , ## __VA_ARGS__)

External routines may send asterisk manager events this way.

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

Definition at line 179 of file manager.h.

Referenced by __ast_channel_alloc_ap(), __expire_registry(), __iax2_poke_noanswer(), __init_manager(), action_userevent(), add_to_queue(), agent_logoff_maintenance(), agi_handle_command(), aji_log_hook(), ast_cdr_setaccount(), ast_change_name(), ast_channel_bridge(), ast_do_masquerade(), ast_hangup(), ast_monitor_start(), ast_monitor_stop(), ast_rtcp_read(), ast_rtcp_write_sr(), ast_rtp_destroy(), ast_setstate(), bridge_exec(), conf_free(), conf_run(), dahdi_dnd(), dahdi_handle_event(), do_reload(), expire_register(), fast_originate(), frame_set_var(), gtalk_answer(), gtalk_new(), handle_alarms(), handle_init_event(), handle_request_refer(), handle_response_invite(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), iax2_ami_channelupdate(), join_queue(), launch_asyncagi(), leave_queue(), load_modules(), local_attended_transfer(), log_jitterstats(), logger_print_normal(), login_exec(), manager_bridge_event(), manager_log(), manager_show_dialplan(), manager_state_cb(), mwi_thread(), notify_new_message(), park_call_full(), park_exec(), parse_register_contact(), pbx_builtin_setvar_helper(), pbx_extension_helper(), phase_e_handler(), post_manager_event(), private_enum_init(), process_sdp(), quit_handler(), realtime_exec(), record_abandoned(), register_verify(), reload_config(), reload_logger(), remove_from_queue(), report_new_callerid(), ring_entry(), send_agent_complete(), send_dtmf_event(), senddialendevent(), senddialevent(), set_member_paused(), set_member_penalty(), shared_write(), sip_new(), sip_poke_noanswer(), sip_reg_timeout(), sip_request_call(), socket_process(), try_calling(), update_registry(), update_status(), userevent_exec(), and vm_execmain().


Typedef Documentation

typedef int(* manager_hook_t)(int, const char *, char *)

Manager Helper Function.

Definition at line 79 of file manager.h.


Function Documentation

int astman_is_authed ( uint32_t  ident  ) 

Determinie if a manager session ident is authenticated.

Definition at line 3284 of file manager.c.

References mansession_session::__lock, ast_mutex_unlock(), mansession_session::authenticated, and find_session().

Referenced by static_callback().

03285 {
03286    int authed;
03287    struct mansession_session *session;
03288 
03289    if (!(session = find_session(ident, 0)))
03290       return 0;
03291 
03292    authed = (session->authenticated != 0);
03293 
03294    ast_mutex_unlock(&session->__lock);
03295 
03296    return authed;
03297 }

int astman_verify_session_readpermissions ( uint32_t  ident,
int  perm 
)

Verify a session's read permissions against a permission mask.

Parameters:
ident session identity
perm permission mask to verify
Return values:
1 if the session has the permission mask capabilities
0 otherwise

Definition at line 3299 of file manager.c.

References mansession_session::__lock, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), mansession_session::managerid, and mansession_session::readperm.

03300 {
03301    int result = 0;
03302    struct mansession_session *session;
03303 
03304    AST_LIST_LOCK(&sessions);
03305    AST_LIST_TRAVERSE(&sessions, session, list) {
03306       ast_mutex_lock(&session->__lock);
03307       if ((session->managerid == ident) && (session->readperm & perm)) {
03308          result = 1;
03309          ast_mutex_unlock(&session->__lock);
03310          break;
03311       }
03312       ast_mutex_unlock(&session->__lock);
03313    }
03314    AST_LIST_UNLOCK(&sessions);
03315    return result;
03316 }

int astman_verify_session_writepermissions ( uint32_t  ident,
int  perm 
)

Verify a session's write permissions against a permission mask.

Parameters:
ident session identity
perm permission mask to verify
Return values:
1 if the session has the permission mask capabilities, otherwise 0
0 otherwise

Definition at line 3318 of file manager.c.

References mansession_session::__lock, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), mansession_session::managerid, and mansession_session::writeperm.

03319 {
03320    int result = 0;
03321    struct mansession_session *session;
03322 
03323    AST_LIST_LOCK(&sessions);
03324    AST_LIST_TRAVERSE(&sessions, session, list) {
03325       ast_mutex_lock(&session->__lock);
03326       if ((session->managerid == ident) && (session->writeperm & perm)) {
03327          result = 1;
03328          ast_mutex_unlock(&session->__lock);
03329          break;
03330       }
03331       ast_mutex_unlock(&session->__lock);
03332    }
03333    AST_LIST_UNLOCK(&sessions);
03334    return result;
03335 }

int init_manager ( void   ) 

Called by Asterisk initialization.

Definition at line 4115 of file manager.c.

References __init_manager().

Referenced by main().

04116 {
04117    return __init_manager(0);
04118 }

int reload_manager ( void   ) 

Called by Asterisk module functions and the CLI command.

Definition at line 4120 of file manager.c.

References __init_manager().

Referenced by handle_manager_reload().

04121 {
04122    return __init_manager(1);
04123 }


Generated on Wed Oct 28 11:46:13 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6