Telephony::Asterisk::AMI - Simple Asterisk Manager Interface client
This document describes version 0.006 of Telephony::Asterisk::AMI, released December 26, 2015.
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;
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.
$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.
$ami
%args
key => value
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).
hostname:port
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" & "disconnect" methods also consume an ActionID for the implicit Login & Logoff actions.) (default: 1)
Debug
If set to a true value, sets Debug_FH to STDERR (unless it was already set to a different value). (default: false)
Debug_FH
STDERR
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 while the "action" method is waiting for a response. The event data is passed as a hashref, just like the return value of the action method. You MUST NOT call any methods on $ami from inside the callback. (default: events are ignored)
action
The constructor throws an exception if a required parameter is omitted.
$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.
$success
undef
$ami->error
$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.
disconnect
connect
$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.)
Action
Do not pass an ActionID in %args. The ActionID is provided automatically.
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. Unless it's an error response, it will also have an ActionID key whose value is the ActionID assigned to it. (An error response might or might not have an ActionID.)
$response
Response
Success
Error
Any events that are received while waiting for the response to the action are dispatched to the Event_Callback (if any). If no callback was provided, events are discarded.
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!" and set $ami->error.
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" and set $ami->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 exceptions are the automatic Login and Logoff actions performed by the "connect" and "disconnect" methods, which do set error on failure.
error
It returns undef if there has been no communication error.
You shouldn't normally need to use these methods, but sometimes you need more control over the communication with Asterisk.
$actionid = $ami->send_action(%args);
Sends an action request to Asterisk and returns the ActionID. The %args are the same as for "action".
Do not pass an ActionID in %args. The ActionID is provided automatically and returned.
If you have not called the connect method (or it failed), calling send_action will return undef and set $ami->error to "Not connected to Asterisk!".
send_action
If communication with Asterisk fails, it will return undef and set $ami->error to "Writing to socket failed: %s".
$response = $ami->read_response;
Reads a single message from Asterisk. Blocks until a message arrives. The action method waits for the response, so read_response is only useful for reading events (or if you used the low-level send_action method).
read_response
It returns a hashref in the same format as the return value of the action method. See that for details.
Note that events received by read_response are not delivered to the Event_Callback (if any). The callback is used only for events that are received during the execution of the action method.
If you have not called the connect method (or it failed), calling read_response will return a manufactured Error response with Message "Not connected to Asterisk!" and set $ami->error.
If communication with Asterisk fails, it will return a manufactured Error response with Message "Reading from socket failed: %s" and set $ami->error.
https://wiki.asterisk.org/wiki/display/AST/Home
Asterisk::AMI is a more sophisticated AMI client better suited for event-driven programs.
If you're using POE, you may want POE::Component::Client::Asterisk::Manager.
Required parameter %s not defined
You omitted a required parameter from a method call.
Telephony::Asterisk::AMI requires no configuration files or environment variables.
Telephony::Asterisk::AMI depends on IO::Socket::IP, which became a core module with Perl 5.20. There are no other non-core dependencies.
None reported.
No bugs have been reported.
Christopher J. Madsen <perl AT cjmweb.net>
<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.
<bug-Telephony-Asterisk-AMI AT rt.cpan.org>
You can follow or contribute to Telephony-Asterisk-AMI's development at https://github.com/madsen/Telephony-Asterisk-AMI.
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.
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.
To install Telephony::Asterisk::AMI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Telephony::Asterisk::AMI
CPAN shell
perl -MCPAN -e shell install Telephony::Asterisk::AMI
For more information on module installation, please visit the detailed CPAN module installation guide.