NAME
Asterisk::AMI::Common - Extends Asterisk::AMI to provide simple access to common AMI commands and functions
VERSION
0.2.8
SYNOPSIS
use Asterisk::AMI::Common;
my $astman = Asterisk::AMI::Common->new( PeerAddr => '127.0.0.1',
PeerPort => '5038',
Username => 'admin',
Secret => 'supersecret'
);
die "Unable to connect to asterisk" unless ($astman);
$astman->db_get();DESCRIPTION
This module extends the AMI module to provide easier access to common actions and commands available through the AMI.
Constructor
new([ARGS])
Creates new a Asterisk::AMI::Common object which takes the arguments as key-value pairs.
This module inherits all options from the AMI module.
Methods
attended_transfer ( CHANNEL, EXTEN, CONTEXT [, TIMEOUT ] )
Requires Asterisk 1.8+.
Performs an attended transfer on CHANNEL to EXTEN@CONTEXT. Returns 1 on success, 0 on failure, or undef on
error or timeout. TIMEOUT is optionalbridge ( CHANNEL1, CHANNEL2 [, TIMEOUT ] )
Requires Asterisk 1.8+.
Bridges CHANNEL1 and CHANNEL2. Returns 1 on success, 0 on failure, or undef on error or timeout.
TIMEOUT is optional.commands ( [ TIMEOUT ] )
Returns a hash reference of commands available through the AMI. TIMEOUT is optional
$hashref->{'CommandName'}->{'Desc'} Contains the command description
{'Priv'} Contains list of required privileges.db_show ( [ TIMEOUT ] )
Returns a hash reference containing the contents of the Asterisk database, or undef on error or timeout.
TIMEOUT is optional.
Values in the hash reference are stored as below:
$hashref->{FAMILY}->{KEY}db_get ( FAMILY, KEY [, TIMEOUT ])
Returns the value of the Asterisk database entry specified by the FAMILY and KEY pair, or undef if
does not exist or an error occurred. TIMEOUT is optional.db_put ( FAMILY, KEY, VALUE [, TIMEOUT ])
Inserts VALUE for the Asterisk database entry specified by the FAMILY and KEY pair. Returns 1 on success, 0 if it
failed or undef on error or timeout. TIMEOUT is optional.db_del ( FAMILY, KEY [, TIMEOUT ])
Requires Asterisk 1.8+.
Support for Asterisk 1.4 is provided through CLI commands.
Deletes the Asterisk database for FAMILY/KEY. Returns 1 on success, 0 if it failed
or undef on error or timeout. TIMEOUT is optional.db_deltree ( FAMILY [, KEY, TIMEOUT ])
Requires Asterisk 1.8+.
Support for Asterisk 1.4 is provided through CLI commands.
Deletes the entire Asterisk database tree found under FAMILY/KEY. KEY is optional. Returns 1 on success, 0 if it failed
or undef on error or timeout. TIMEOUT is optional.get_var ( CHANNEL, VARIABLE [, TIMEOUT ])
Returns the value of VARIABLE for CHANNEL, or undef on error or timeout. TIMEOUT is optional.set_var ( CHANNEL, VARIABLE, VALUE [, TIMEOUT ])
Sets VARIABLE to VALUE for CHANNEL. Returns 1 on success, 0 if it failed, or undef on error or timeout.
TIMEOUT is optional.hangup ( CHANNEL [, TIMEOUT ])
Hangs up CHANNEL. Returns 1 on success, 0 if it failed, or undef on error or timeout. TIMEOUT is optional.exten_state ( EXTEN, CONTEXT [, TIMEOUT ])
Returns the state of the EXTEN in CONTEXT, or undef on error or timeout. TIMEOUT is optional
States:
-1 = Extension not found
0 = Idle
1 = In Use
2 = Busy
4 = Unavailable
8 = Ringing
16 = On Holdpark ( CHANNEL, CHANNEL2 [, PARKTIME, TIMEOUT ] )
Parks CHANNEL and announces park information to CHANNEL2. CHANNEL2 is also the channel the call will return to if
it times out.
PARKTIME is optional and can be used to control how long a person is parked for. TIMEOUT is optional.
Returns 1 if the call was parked, or 0 if it failed, or undef on error and timeout.parked_calls ( [ TIMEOUT ] )
Returns a hash reference containing parking lots and their members, or undef if an error/timeout or if no calls
were parked. TIMEOUT is optional.
Hash reference structure:
$hashref->{lotnumber}->{'Channel'}
{'Timeout'}
{'CallerID'}
{'CallerIDName'}sip_peers ( [ TIMEOUT ] )
Returns a hash reference containing all SIP peers, or undef on error or timeout. TIMEOUT is optional.
Hash reference structure:
$hashref->{peername}->{'Channeltype'}
{'ChanObjectType'}
{'IPaddress'}
{'IPport'}
{'Dynamic'}
{'Natsupport'}
{'VideoSupport'}
{'ACL'}
{'Status'}
{'RealtimeDevice'}sip_peer ( PEERNAME [, TIMEOUT ] )
Returns a hash reference containing the information for PEERNAME, or undef on error or timeout.
TIMEOUT is optional.
Hash reference structure:
$hashref->{'SIPLastMsg'}
{'SIP-UserPhone'}
{'Dynamic'}
{'TransferMode'}
{'SIP-NatSupport'}
{'Call-limit'}
{'CID-CallingPres'}
{'LastMsgsSent'}
{'Status'}
{'Address-IP'}
{'RegExpire'}
{'ToHost'}
{'Codecs'},
{'Default-addr-port'}
{'SIP-DTMFmode'}
{'Channeltype'}
{'ChanObjectType'}
{'AMAflags'}
{'SIP-AuthInsecure'}
{'SIP-VideoSupport'}
{'Callerid'}
{'Address-Port'}
{'Context'}
{'ObjectName'}
{'ACL'}
{'Default-addr-IP'}
{'SIP-PromiscRedir'}
{'MaxCallBR'}
{'MD5SecretExist'}
{'SIP-CanReinvite'}
{'CodecOrder'}
{'SecretExist'}sip_notify ( PEER, EVENT [, TIMEOUT ])
Sends a SIP NOTIFY to PEER with EVENT. Returns 1 on success 0 on failure or undef on error or timeout.
Example - Sending a 'check-sync' event to to a SIP PEER named 'Polycom1':
$astman->sip_notify('Polycom1', 'check-sync');mailboxcount ( EXTENSION, CONTEXT [, TIMEOUT ] )
Returns an hash reference containing the message counts for the mailbox EXTENSION@CONTEXT, or undef on error or
timeout. TIMEOUT is optional.
Hash reference structure:
$hashref->{'Mailbox'}
{'NewMessages'}
{'OldMessages'}mailboxstatus ( EXTENSION, CONTEXT [, TIMEOUT ] )
Returns the status of the mailbox or undef on error or timeout. TIMEOUT is optionalchan_timeout ( CHANNEL, CHANNELTIMEOUT [, TIMEOUT ] )
Sets CHANNEL to timeout in CHANNELTIMEOUT seconds. Returns 1 on success, 0 on failure, or undef on error or timeout.
TIMEOUT is optional.queues ( [ TIMEOUT ] )
Returns a hash reference containing all queues, queue members, and people currently waiting in the queue,
or undef on error or timeout. TIMEOUT is optional
Hash reference structure:
$hashref->{queue}->{'Max'}
{'Calls'}
{'Holdtime'}
{'Completed'}
{'Abandoned'}
{'ServiceLevel'}
{'ServicelevelPerf'}
{'Weight'}
{'MEMBERS'}->{name}->{'Location'}
{'Membership'}
{'Penalty'}
{'CallsTaken'}
{'LastCall'}
{'Status'}
{'Paused'}
{'ENTRIES'}->{position}->{'Channel'}
{'CallerID'}
{'CallerIDName'}
{'Wait'}queue_status ( QUEUE [, TIMEOUT ] )
Returns a hash reference containing the queue status, members, and people currently waiting in the queue,
or undef on error or timeout. TIMEOUT is optional.
Hash reference structure
$hashref->{'Max'}
{'Calls'}
{'Holdtime'}
{'Completed'}
{'Abandoned'}
{'ServiceLevel'}
{'ServicelevelPerf'}
{'Weight'}
{'MEMBERS'}->{name}->{'Location'}
{'Membership'}
{'Penalty'}
{'CallsTaken'}
{'LastCall'}
{'Status'}
{'Paused'}
{'ENTRIES'}->{position}->{'Channel'}
{'CallerID'}
{'CallerIDName'}
{'Wait'}queue_member_pause ( QUEUE, MEMBER, PAUSEVALUE [, TIMEOUT ] )
Sets the MEMBER of QUEUE to PAUSEVALUE. A value of 0 will un-pause a member, and 1 will pause them.
Returns 1 if the PAUSEVALUE was set, 0 if it failed, or undef on error or timeout. TIMEOUT is optional.queue_member_toggle ( QUEUE, MEMBER [, TIMEOUT ] )
Toggles MEMBER of QUEUE pause status. From paused to un-paused, and un-paused to paused.
Returns 1 if the the pause status was toggled, 0 if failed, or undef on error or timeout. TIMEOUT is optionalqueue_add ( QUEUE, MEMEBER [, TIMEOUT ] )
Adds MEMBER to QUEUE. Returns 1 if the MEMBER was added, or 0 if it failed, or undef on error or timeout.
TIMEOUT is optional.queue_remove ( QUEUE, MEMEBER [, TIMEOUT ] )
Removes MEMBER from QUEUE. Returns 1 if the MEMBER was removed, 0 if it failed, or undef on error or timeout.
TIMEOUT is optional.play_dtmf ( CHANNEL, DIGIT [, TIMEOUT ] )
Plays the dtmf DIGIT on CHANNEL. Returns 1 if the DIGIT was queued on the channel, or 0 if it failed, or
undef on error or timeout.
TIMEOUT is optional.play_digits ( CHANNEL, DIGITS [, TIMEOUT ] )
Plays the dtmf DIGITS on CHANNEL. DIGITS should be passed as an array reference. Returns 1 if all DIGITS
were queued on the channel, or 0 if an any queuing failed. TIMEOUT is optional.channels ( [ TIMEOUT ] )
Returns a hash reference containing all channels with their information, or undef on error or timeout.
TIMEOUT is optional.
Hash reference structure:
$hashref->{channel}->{'Context'}
{'CallerID'}
{'CallerIDNum'}
{'CallerIDName'}
{'Account'}
{'State'}
{'Context'}
{'Extension'}
{'Priority'}
{'Seconds'}
{'Link'}
{'Uniqueid'}chan_status ( CHANNEL [, TIMEOUT ] )
Returns a hash reference containing the status of the channel, or undef on error or timeout.
TIMEOUT is optional.
Hash reference structure:
$hashref->{'Channel'}
{'CallerID'}
{'CallerIDNum'}
{'CallerIDName'}
{'Account'}
{'State'}
{'Context'}
{'Extension'}
{'Priority'}
{'Seconds'}
{'Link'}
{'Uniqueid'}transfer ( CHANNEL, EXTENSION, CONTEXT [, TIMEOUT ] )
Transfers CHANNEL to EXTENSION at CONTEXT. Returns 1 if the channel was transferred, 0 if it failed,
or undef on error or timeout. TIMEOUT is optional.meetme_list ( [ TIMEOUT ] )
Full support requires Asterisk 1.8+.
Partial support is provided on Asterisk 1.4 via cli commands. When using with asteirsk 1.4 the following
keys are missing: Role, MarkedUser
Returns a hash reference containing all meetme conferences and their members, or undef if an error occurred.
TIMEOUT is optional.
Hash reference:
$hashref->{RoomNum}->{MemberChannels}->{'Muted'}
{'Role'}
{'Talking'}
{'UserNumber'}
{'CallerIDName'}
{'MarkedUser'}
{'CallerIDNum'}
{'Admin'}meetme_members ( ROOMNUM [, TIMEOUT ] )
Full support requires Asterisk 1.8+.
Partial support is provided on Asterisk 1.4 via cli commands. When using with asteirsk 1.4 the following
keys are missing: Role, MarkedUser
Returns a hash reference containing all members of a meetme conference, or undef if an error occurred.
TIMEOUT is optional.
Hash reference:
$hashref->{MemberChannels}->{'Muted'}
{'Role'}
{'Talking'}
{'UserNumber'}
{'CallerIDName'}
{'MarkedUser'}
{'CallerIDNum'}
{'Admin'}meetme_mute ( CONFERENCE, USERNUM [, TIMEOUT ] )
Mutes USERNUM in CONFERENCE. Returns 1 if the user was muted, 0 if it failed, or undef on error or timeout.
TIMEOUT is optional.meetme_unmute ( CONFERENCE, USERNUM [, TIMEOUT ] )
Un-mutes USERNUM in CONFERENCE. Returns 1 if the user was un-muted, or 0 if it failed, or undef on error or timeout.
TIMEOUT is optional.mute_chan ( CHANNEL [, DIRECTION, TIMEOUT ] )
Mutes audio on CHANNEL. DIRECTION is optiona and can be 'in' for inbound audio only, 'out' for outbound audio
only or 'all' to for both directions. If not supplied it defaults to 'all'. Returns 1 on success, 0 if it failed,
or undef on error or timeout. TIMEOUT is optional.unmute_chan ( CHANNEL [, DIRECTION, TIMEOUT ] )
UnMutes audio on CHANNEL. DIRECTION is optiona and can be 'in' for inbound audio only, 'out' for outbound audio
only or 'all' to for both directions. If not supplied it defaults to 'all'. Returns 1 on success, 0 if it failed,
or undef on error or timeout. TIMEOUT is optional.monitor ( CHANNEL, FILE [, TIMEOUT ] )
Begins recording CHANNEL to FILE. Uses the 'wav' format and also mixes both directions into a single file.
Returns 1 if the channel was set to record, or 0 if it failed, or undef on error or timeout. TIMEOUT is optional.monitor_stop ( CHANNEL [, TIMEOUT ])
Stops recording CHANNEL. Returns 1 if recording on the channel was stopped, 0 if it failed, or undef on error
or timeout.
TIMEOUT is optional.monitor_pause ( CHANNEL [, TIMEOUT ])
Pauses recording on CHANNEL. Returns 1 if recording on the channel was paused, 0 if it failed, or undef on error
or timeout.
TIMEOUT is optional.monitor_unpause ( CHANNEL [, TIMEOUT ])
Un-pauses recording on CHANNEL. Returns 1 if recording on the channel was un-paused, 0 if it failed, or undef on error
or timeout.
TIMEOUT is optional.monitor_change ( CHANNEL, FILE [, TIMEOUT ] )
Changes the monitor file for CHANNEL to FILE. Returns 1 if the file was change, 0 if it failed, or undef on error
or timeout.
TIMEOUT is optional.mixmonitor_mute ( CHANNEL [, DIRECTION, TIMEOUT] )
Requires Asterisk 1.8+
Mutes audio on CHANNEL. DIRECTION is optiona and can be 'read' for inbound audio only, 'write' for outbound audio
only or 'both' to for both directions. If not supplied it defaults to 'both'. Returns 1 on success, 0 if it failed,
or undef on error or timeout. TIMEOUT is optional.mixmonitor_unmute ( CHANNEL [, DIRECTION, TIMEOUT] )
Requires Asterisk 1.8+
UnMutes audio on CHANNEL. DIRECTION is optiona and can be 'read' for inbound audio only, 'write' for outbound audio
only or 'both' to for both directions. If not supplied it defaults to 'both'. Returns 1 on success, 0 if it failed,
or undef on error or timeout. TIMEOUT is optional.text ( CHANNEL, MESSAGE [, TIMEOUT ] )
Requires Asterisk 1.8+.
Sends MESSAGE as a text on CHANNEL. Returns 1 on success, 0 on failure, or undef on error or timeout.
TIMEOUT is optional.voicemail_list ( [ TIMEOUT ] )
Requires Asterisk 1.8+.
Returns a hash reference of all mailboxes on the system, or undef if an error occurred.
TIMEOUT is optional.
Hash reference:
$hashref->{context}->{mailbox}->{'AttachmentFormat'}
{'TimeZone'}
{'Pager'}
{'SayEnvelope'}
{'ExitContext'}
{'AttachMessage'}
{'SayCID'}
{'ServerEmail'}
{'CanReview'}
{'DeleteMessage'}
{'UniqueID'}
{'Email'}
{'MaxMessageLength'}
{'CallOperator'}
{'SayDurationMinimum'}
{'NewMessageCount'}
{'Language'}
{'MaxMessageCount'}
{'Fullname'}
{'Callback'}
{'MailCommand'}
{'VolumeGain'}
{'Dialout'}module_check ( MODULE [, TIMEOUT ] )
Full support requires Asterisk 1.8+.
Partial support is provided on Asterisk 1.4 via cli commands.
Checks to see if MODULE is loaded. Returns 1 on success (loaded), 0 on failure (not loaded), or undef on error or timeout.
MODULE is the name of the module minus its extension. To check for 'app_meetme.so' you would only use 'app_meetme'.
TIMEOUT is optional.module_load, module_reload, module_unload ( MODULE [, TIMEOUT ] )
Requires Asterisk 1.8+.
Attempts to load/reload/unload MODULE. Returns 1 on success, 0 on failure, or undef on error or timeout.
MODULE is the name of the module with its extension or an asterisk subsystem. To load 'app_meetme.so' you would use 'app_meetme.so'.
TIMEOUT is optional.
Valid Asterisk Subsystems:
cdr
enum
dnsmgr
extconfig
manager
rtp
httporiginate ( CHANNEL, CONTEXT, EXTEN [, CALLERID, CTIMEOUT, TIMEOUT ] )
Attempts to dial CHANNEL and then drops it into EXTEN@CONTEXT in the dialplan. Optionally a CALLERID can be provided.
CTIMEOUT is optional and determines how long the call will dial/ring for in seconds. TIMEOUT is optional.
CTIMEOUT + TIMEOUT will be used for the command timeout. For example if CTIMEOUT is 30 seconds and TIMEOUT is 5 seconds, the entire
command will timeout after 35 seconds.
Returns 1 on success 0 on failure, or undef on error or timeout.
WARNING: This method can block for a very long time (CTIMEOUT + TIMEOUT).originate_async ( CHANNEL, CONTEXT, EXTEN [, CALLERID, CTIMEOUT, TIMEOUT ] )
Attempts to dial CHANNEL and then drops it into EXTEN@CONTEXT in the dialplan asynchronously. Optionally a CALLERID can be provided.
CTIMEOUT is optional and determines how long the call will dial/ring for in seconds. TIMEOUT is optional and only affects how long we will
wait for the initial response from Asterisk indicating if the call has been queued.
Returns 1 if the call was successfully queued, 0 on failure, or undef on error or timeout.
WARNING: A successfully queued call does not mean the call completed or even originated.See Also
Asterisk::AMI, Asterisk::AMI::Common::Dev
AUTHOR
Ryan Bullock (rrb3942@gmail.com)
BUG REPORTING AND FEEBACK
Please report any bugs or errors to our github issue tracker at http://github.com/rrb3942/perl-Asterisk-AMI/issues or the cpan request tracker at https://rt.cpan.org/Public/Bug/Report.html?Queue=perl-Asterisk-AMI
LICENSE
Copyright (C) 2011 by Ryan Bullock (rrb3942@gmail.com)
This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.