Constructor¶

  $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" & "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"

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)

The constructor throws an exception if a required parameter is omitted.

Main Methods¶

  $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.)

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.)

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

  $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.

It returns "undef" if there has been no communication error.

Low-Level Methods¶

send_action

  $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!".

If communication with Asterisk fails, it will return "undef" and set "$ami->error" to "Writing to socket failed: %s".

read_response

  $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).

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".