NAME
Telephony::Asterisk::AMI - Simple Asterisk Manager Interface client
VERSION
This document describes version 0.002 of Telephony::Asterisk::AMI, released November 7, 2015.
SYNOPSIS
use Telephony::Asterisk::AMI ();
my $ami = Telephony::Asterisk::AMI->new(
Username => 'user',
Secret => 'password',
);
$ami->connect or die $ami->error;
my $response = $ami->action(Action => 'Ping');
$ami->disconnect or die $ami->error;
DESCRIPTION
Telephony::Asterisk::AMI is a simple client for the Asterisk Manager Interface. It's better documented and less buggy than Asterisk::Manager, and has fewer prerequisites than Asterisk::AMI. It uses IO::Socket::IP, so it should support either IPv4 or IPv6.
If you need a more sophisticated client (especially for use in an event-driven program), try Asterisk::AMI.
METHODS
new
$ami = Telephony::Asterisk::AMI->new(%args);
Constructs a new $ami
object. The %args
may be passed as a hashref or a list of key => value
pairs.
This does not do any network communication; you must call "connect" to open the connection before doing anything else.
The parameters are:
Username
-
The AMI username to use when logging in. (required)
Secret
-
The AMI secret (password) to use when logging in. (required)
Host
-
The hostname to connect to. You can also specify
hostname:port
as a single string. (default: localhost). Port
-
The port number to connect to (if no port was specified with
Host
). (default: 5038) ActionID
-
The ActionID to start at. Each call to "action" increments the ActionID. (Note: The "connect" method also consumes an ActionID for the implicit Login action.) (default: 1)
Debug
-
If set to a true value, sets
Debug_FH
toSTDERR
(unless it was already set to a different value). (default: false) Debug_FH
-
A filehandle to write a transcript of the communications to. Lines sent to Asterisk are prefixed with
>>
, and lines received from Asterisk are prefixed with<<
. (default: no transcript) Event_Callback
-
A coderef that is called when an event is received from Asterisk. The event data is passed as a hashref, just like the return value of the
action
method. Events are only received while waiting for a response to an action. You MUST NOT call any methods on$ami
from inside the callback. (default: events are ignored)
The constructor throws an exception if a required parameter is omitted.
connect
$success = $ami->connect;
Opens the connection to Asterisk and logs in. $success
is true if the login was successful, or undef
on error. On failure, you can get the error message with $ami->error
.
disconnect
$success = $ami->disconnect;
Logs off of Asterisk and closes the connection. $success
is true if the logoff was successful, or undef
on error. On failure, you can get the error message with $ami->error
.
After a successful call to disconnect
, you may call connect
again to reestablish the connection.
action
$response = $ami->action(%args);
Sends an action request to Asterisk and returns the response. The %args
may be passed as a hashref or a list of key => value
pairs, where the keys are the Asterisk field names. To create more than one instance of a field, make the value an arrayref.
The only required key is Action
. (Asterisk may require other keys depending on the value of Action
, but that is not enforced by this module.)
The $response
is a hashref formed from Asterisk's response in the same format as %args
. It will have a Response
key whose value is either Success
or Error
.
If you have not called the connect
method (or it failed), calling action
will return a manufactured Error response with Message "Not connected to Asterisk!".
If communication with Asterisk fails, it will return a manufactured Error response with Message "Writing to socket failed: %s" or "Reading from socket failed: %s". In this case, $ami->error
will also be set.
error
$error_message = $ami->error;
If communication with Asterisk fails, this method will return an error message describing the problem.
If Asterisk returns "Response: Error" for some action, that does not set $ami->error
. The one exception is the automatic Login action performed by the "connect" method, which does set error
on failure.
It returns undef
if there has been no communication error.
SEE ALSO
https://wiki.asterisk.org/wiki/display/AST/Home
Asterisk::AMI is a more sophisticated AMI client better suited for event-driven programs.
DIAGNOSTICS
CONFIGURATION AND ENVIRONMENT
Telephony::Asterisk::AMI requires no configuration files or environment variables.
DEPENDENCIES
Telephony::Asterisk::AMI depends on IO::Socket::IP, which became a core module with Perl 5.20. There are no other non-core dependencies.
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
No bugs have been reported.
AUTHOR
Christopher J. Madsen <perl AT cjmweb.net>
Please report any bugs or feature requests to <bug-Telephony-Asterisk-AMI AT rt.cpan.org>
or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Telephony-Asterisk-AMI.
You can follow or contribute to Telephony-Asterisk-AMI's development at https://github.com/madsen/Telephony-Asterisk-AMI.
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Christopher J. Madsen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.