.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Telephony::Asterisk::AMI 3pm"
.TH Telephony::Asterisk::AMI 3pm "2022-11-20" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Telephony::Asterisk::AMI \- Simple Asterisk Manager Interface client
.SH "VERSION"
.IX Header "VERSION"
This document describes version 0.006 of
Telephony::Asterisk::AMI, released December 26, 2015.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Telephony::Asterisk::AMI ();
\&
\&  my $ami = Telephony::Asterisk::AMI\->new(
\&    Username => \*(Aquser\*(Aq,
\&    Secret => \*(Aqpassword\*(Aq,
\&  );
\&
\&  $ami\->connect or die $ami\->error;
\&
\&  my $response = $ami\->action(Action => \*(AqPing\*(Aq);
\&
\&  $ami\->disconnect or die $ami\->error;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
If you need a more sophisticated client (especially for use in an
event-driven program), try Asterisk::AMI.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructor"
.IX Subsection "Constructor"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\&  $ami = Telephony::Asterisk::AMI\->new(%args);
.Ve
.PP
Constructs a new \f(CW$ami\fR object.  The \f(CW%args\fR may be passed as a
hashref or a list of \f(CW\*(C`key => value\*(C'\fR pairs.
.PP
This does not do any network communication; you must call \*(L"connect\*(R"
to open the connection before doing anything else.
.PP
The parameters are:
.ie n .IP """Username""" 4
.el .IP "\f(CWUsername\fR" 4
.IX Item "Username"
The \s-1AMI\s0 username to use when logging in. (required)
.ie n .IP """Secret""" 4
.el .IP "\f(CWSecret\fR" 4
.IX Item "Secret"
The \s-1AMI\s0 secret (password) to use when logging in. (required)
.ie n .IP """Host""" 4
.el .IP "\f(CWHost\fR" 4
.IX Item "Host"
The hostname to connect to.
You can also specify \f(CW\*(C`hostname:port\*(C'\fR as a single string.
(default: localhost).
.ie n .IP """Port""" 4
.el .IP "\f(CWPort\fR" 4
.IX Item "Port"
The port number to connect to (if no port was specified with \f(CW\*(C`Host\*(C'\fR).
(default: 5038)
.ie n .IP """ActionID""" 4
.el .IP "\f(CWActionID\fR" 4
.IX Item "ActionID"
The ActionID to start at.  Each call to \*(L"action\*(R" increments the ActionID.
(Note: The \*(L"connect\*(R" & \*(L"disconnect\*(R" methods also consume an ActionID for
the implicit Login & Logoff actions.)
(default: 1)
.ie n .IP """Debug""" 4
.el .IP "\f(CWDebug\fR" 4
.IX Item "Debug"
If set to a true value, sets \f(CW\*(C`Debug_FH\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR
(unless it was already set to a different value).
(default: false)
.ie n .IP """Debug_FH""" 4
.el .IP "\f(CWDebug_FH\fR" 4
.IX Item "Debug_FH"
A filehandle to write a transcript of the communications to.
Lines sent to Asterisk are prefixed with \f(CW\*(C`>>\*(C'\fR, and lines
received from Asterisk are prefixed with \f(CW\*(C`<<\*(C'\fR.
(default: no transcript)
.ie n .IP """Event_Callback""" 4
.el .IP "\f(CWEvent_Callback\fR" 4
.IX Item "Event_Callback"
A coderef that is called when an event is received from Asterisk while
the \*(L"action\*(R" method is waiting for a response.  The event data is
passed as a hashref, just like the return value of the \f(CW\*(C`action\*(C'\fR
method.  You \s-1MUST NOT\s0 call any methods on \f(CW$ami\fR from inside the
callback.
(default: events are ignored)
.PP
The constructor throws an exception if a required parameter is
omitted.
.SS "Main Methods"
.IX Subsection "Main Methods"
\fIconnect\fR
.IX Subsection "connect"
.PP
.Vb 1
\&  $success = $ami\->connect;
.Ve
.PP
Opens the connection to Asterisk and logs in.
\&\f(CW$success\fR is true if the login was successful, or \f(CW\*(C`undef\*(C'\fR on error.
On failure, you can get the error message with \f(CW\*(C`$ami\->error\*(C'\fR.
.PP
\fIdisconnect\fR
.IX Subsection "disconnect"
.PP
.Vb 1
\&  $success = $ami\->disconnect;
.Ve
.PP
Logs off of Asterisk and closes the connection.
\&\f(CW$success\fR is true if the logoff was successful, or \f(CW\*(C`undef\*(C'\fR on error.
On failure, you can get the error message with \f(CW\*(C`$ami\->error\*(C'\fR.
.PP
After a successful call to \f(CW\*(C`disconnect\*(C'\fR, you may call \f(CW\*(C`connect\*(C'\fR
again to reestablish the connection.
.PP
\fIaction\fR
.IX Subsection "action"
.PP
.Vb 1
\&  $response = $ami\->action(%args);
.Ve
.PP
Sends an action request to Asterisk and returns the response.  The
\&\f(CW%args\fR may be passed as a hashref or a list of \f(CW\*(C`key => value\*(C'\fR pairs, where the keys are the Asterisk field names.  To create
more than one instance of a field, make the value an arrayref.
.PP
The only required key is \f(CW\*(C`Action\*(C'\fR.  (Asterisk may require other keys
depending on the value of \f(CW\*(C`Action\*(C'\fR, but that is not enforced by this
module.)
.PP
Do not pass an \f(CW\*(C`ActionID\*(C'\fR in \f(CW%args\fR.  The ActionID is provided
automatically.
.PP
The \f(CW$response\fR is a hashref formed from Asterisk's response in the
same format as \f(CW%args\fR.  It will have a \f(CW\*(C`Response\*(C'\fR key whose value
is either \f(CW\*(C`Success\*(C'\fR or \f(CW\*(C`Error\*(C'\fR.  Unless it's an error response, it
will also have an \f(CW\*(C`ActionID\*(C'\fR key whose value is the ActionID assigned
to it.  (An error response might or might not have an ActionID.)
.PP
Any events that are received while waiting for the response to the
action are dispatched to the \f(CW\*(C`Event_Callback\*(C'\fR (if any).  If no
callback was provided, events are discarded.
.PP
If you have not called the \f(CW\*(C`connect\*(C'\fR method (or it failed), calling
\&\f(CW\*(C`action\*(C'\fR will return a manufactured Error response with Message
\&\*(L"Not connected to Asterisk!\*(R" and set \f(CW\*(C`$ami\->error\*(C'\fR.
.PP
If communication with Asterisk fails, it will return a manufactured
Error response with Message \*(L"Writing to socket failed: \f(CW%s\fR\*(R" or
\&\*(L"Reading from socket failed: \f(CW%s\fR\*(R" and set \f(CW\*(C`$ami\->error\*(C'\fR.
.PP
\fIerror\fR
.IX Subsection "error"
.PP
.Vb 1
\&  $error_message = $ami\->error;
.Ve
.PP
If communication with Asterisk fails, this method will return an error
message describing the problem.
.PP
If Asterisk returns \*(L"Response: Error\*(R" for some action, that does not
set \f(CW\*(C`$ami\->error\*(C'\fR.  The exceptions are the automatic Login and Logoff
actions performed by the \*(L"connect\*(R" and \*(L"disconnect\*(R" methods, which
do set \f(CW\*(C`error\*(C'\fR on failure.
.PP
It returns \f(CW\*(C`undef\*(C'\fR if there has been no communication error.
.SS "Low-Level Methods"
.IX Subsection "Low-Level Methods"
You shouldn't normally need to use these methods, but sometimes you
need more control over the communication with Asterisk.
.PP
\fIsend_action\fR
.IX Subsection "send_action"
.PP
.Vb 1
\&  $actionid = $ami\->send_action(%args);
.Ve
.PP
Sends an action request to Asterisk and returns the ActionID.  The
\&\f(CW%args\fR are the same as for \*(L"action\*(R".
.PP
Do not pass an \f(CW\*(C`ActionID\*(C'\fR in \f(CW%args\fR.  The ActionID is provided
automatically and returned.
.PP
If you have not called the \f(CW\*(C`connect\*(C'\fR method (or it failed), calling
\&\f(CW\*(C`send_action\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR and set \f(CW\*(C`$ami\->error\*(C'\fR to
\&\*(L"Not connected to Asterisk!\*(R".
.PP
If communication with Asterisk fails, it will return \f(CW\*(C`undef\*(C'\fR and set
\&\f(CW\*(C`$ami\->error\*(C'\fR to \*(L"Writing to socket failed: \f(CW%s\fR\*(R".
.PP
\fIread_response\fR
.IX Subsection "read_response"
.PP
.Vb 1
\&  $response = $ami\->read_response;
.Ve
.PP
Reads a single message from Asterisk.  Blocks until a message arrives.
The \f(CW\*(C`action\*(C'\fR method waits for the response, so \f(CW\*(C`read_response\*(C'\fR
is only useful for reading events (or if you used the low-level
\&\f(CW\*(C`send_action\*(C'\fR method).
.PP
It returns a hashref in the same format as the return value of the
\&\f(CW\*(C`action\*(C'\fR method.  See that for details.
.PP
Note that events received by \f(CW\*(C`read_response\*(C'\fR are not delivered to the
\&\f(CW\*(C`Event_Callback\*(C'\fR (if any).  The callback is used only for events
that are received during the execution of the \f(CW\*(C`action\*(C'\fR method.
.PP
If you have not called the \f(CW\*(C`connect\*(C'\fR method (or it failed), calling
\&\f(CW\*(C`read_response\*(C'\fR will return a manufactured Error response with Message
\&\*(L"Not connected to Asterisk!\*(R" and set \f(CW\*(C`$ami\->error\*(C'\fR.
.PP
If communication with Asterisk fails, it will return a manufactured
Error response with Message \*(L"Reading from socket failed: \f(CW%s\fR\*(R" and set
\&\f(CW\*(C`$ami\->error\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<https://wiki.asterisk.org/wiki/display/AST/Home>
.PP
Asterisk::AMI is a more sophisticated \s-1AMI\s0 client better suited for
event-driven programs.
.PP
If you're using \s-1POE\s0, you may want
POE::Component::Client::Asterisk::Manager.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """Required parameter %s not defined""" 4
.el .IP "\f(CWRequired parameter %s not defined\fR" 4
.IX Item "Required parameter %s not defined"
You omitted a required parameter from a method call.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Telephony::Asterisk::AMI requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "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.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
Christopher J. Madsen  \f(CW\*(C`<perl AT cjmweb.net>\*(C'\fR
.PP
Please report any bugs or feature requests
to \f(CW\*(C`<bug\-Telephony\-Asterisk\-AMI AT rt.cpan.org>\*(C'\fR
or through the web interface at
<http://rt.cpan.org/Public/Bug/Report.html?Queue=Telephony\-Asterisk\-AMI>.
.PP
You can follow or contribute to Telephony-Asterisk-AMI's development at
<https://github.com/madsen/Telephony\-Asterisk\-AMI>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015 by Christopher J. Madsen.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE 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 \*(L"AS IS\*(R" 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.\s0
.PP
\&\s-1IN 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\s0 (\s-1INCLUDING 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\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.\s0