.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Asterisk::AGI 3pm" .TH Asterisk::AGI 3pm "2016-12-22" "perl v5.24.1" "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" Asterisk::AGI \- Simple Asterisk Gateway Interface Class .SH "SYNOPSIS" .IX Header "SYNOPSIS" use Asterisk::AGI; .PP \&\f(CW$AGI\fR = new Asterisk::AGI; .PP # pull \s-1AGI\s0 variables into \f(CW%input\fR .PP .Vb 1 \& %input = $AGI\->ReadParse(); .Ve .PP # say the number 1984 .PP .Vb 1 \& $AGI\->say_number(1984); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module should make it easier to write scripts that interact with the asterisk open source pbx via \s-1AGI \s0(asterisk gateway interface) .SH "MODULE COMMANDS" .IX Header "MODULE COMMANDS" .ie n .IP "$AGI\->setcallback($funcref)" 4 .el .IP "\f(CW$AGI\fR\->setcallback($funcref)" 4 .IX Item "$AGI->setcallback($funcref)" Set function to execute when call is hungup or function returns error. .Sp Example: \f(CW$AGI\fR\->setcallback(\e&examplecallback); .SH "AGI COMMANDS" .IX Header "AGI COMMANDS" .ie n .IP "$AGI\->\fIanswer()\fR" 4 .el .IP "\f(CW$AGI\fR\->\fIanswer()\fR" 4 .IX Item "$AGI->answer()" Executes \s-1AGI\s0 Command \*(L"\s-1ANSWER\*(R"\s0 .Sp Answers channel if not already in answer state .Sp Example: \f(CW$AGI\fR\->\fIanswer()\fR; .Sp Returns: \-1 on channel failure, or 0 if successful .ie n .IP "$AGI\->channel_status([$channel])" 4 .el .IP "\f(CW$AGI\fR\->channel_status([$channel])" 4 .IX Item "$AGI->channel_status([$channel])" Executes \s-1AGI\s0 Command \*(L"\s-1CHANNEL STATUS\s0 \f(CW$channel\fR\*(R" .Sp Returns the status of the specified channel. If no channel name is given the returns the status of the current channel. .Sp Example: \f(CW$AGI\fR\->\fIchannel_status()\fR; .Sp Returns: \-1 Channel hungup or error 0 Channel is down and available 1 Channel is down, but reserved 2 Channel is off hook 3 Digits (or equivalent) have been dialed 4 Line is ringing 5 Remote end is ringing 6 Line is up 7 Line is busy .ie n .IP "$AGI\->control_stream_file($filename, $digits [, $skipms [, $ffchar [, $rewchar [, $pausechar]]]])" 4 .el .IP "\f(CW$AGI\fR\->control_stream_file($filename, \f(CW$digits\fR [, \f(CW$skipms\fR [, \f(CW$ffchar\fR [, \f(CW$rewchar\fR [, \f(CW$pausechar\fR]]]])" 4 .IX Item "$AGI->control_stream_file($filename, $digits [, $skipms [, $ffchar [, $rewchar [, $pausechar]]]])" Executes \s-1AGI\s0 Command \*(L"\s-1CONTROL STREAM FILE\s0 \f(CW$filename\fR \f(CW$digits\fR [$skipms [$ffchar [$rewchar [$pausechar]]]]\*(R" .Sp Send the given file, allowing playback to be controlled by the given digits, if any. Use double quotes for the digits if you wish none to be permitted. Remember, the file extension must not be included in the filename. .Sp Note: ffchar and rewchar default to * and # respectively. .Sp Example: \f(CW$AGI\fR\->control_stream_file('status', 'authorized'); .Sp Returns: \-1 on error or hangup; 0 if playback completes without a digit being pressed; the \s-1ASCII\s0 numerical value of the digit of one was pressed. .ie n .IP "$AGI\->database_del($family, $key)" 4 .el .IP "\f(CW$AGI\fR\->database_del($family, \f(CW$key\fR)" 4 .IX Item "$AGI->database_del($family, $key)" Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE DEL\s0 \f(CW$family\fR \f(CW$key\fR\*(R" .Sp Removes database entry / .Sp Example: \f(CW$AGI\fR\->database_del('test', 'status'); .Sp Returns: 1 on success, 0 otherwise .ie n .IP "$AGI\->database_deltree($family, $key)" 4 .el .IP "\f(CW$AGI\fR\->database_deltree($family, \f(CW$key\fR)" 4 .IX Item "$AGI->database_deltree($family, $key)" Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE DELTREE\s0 \f(CW$family\fR \f(CW$key\fR\*(R" .Sp Deletes a family or specific keytree within a family in the Asterisk database .Sp Example: \f(CW$AGI\fR\->database_deltree('test', 'status'); Example: \f(CW$AGI\fR\->database_deltree('test'); .Sp Returns: 1 on success, 0 otherwise .ie n .IP "$AGI\->database_get($family, $key)" 4 .el .IP "\f(CW$AGI\fR\->database_get($family, \f(CW$key\fR)" 4 .IX Item "$AGI->database_get($family, $key)" Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE GET\s0 \f(CW$family\fR \f(CW$key\fR\*(R" .Sp Example: \f(CW$var\fR = \f(CW$AGI\fR\->database_get('test', 'status'); .Sp Returns: The value of the variable, or undef if variable does not exist .ie n .IP "$AGI\->database_put($family, $key, $value)" 4 .el .IP "\f(CW$AGI\fR\->database_put($family, \f(CW$key\fR, \f(CW$value\fR)" 4 .IX Item "$AGI->database_put($family, $key, $value)" Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE PUT\s0 \f(CW$family\fR \f(CW$key\fR \f(CW$value\fR\*(R" .Sp Set/modifes database entry / to .Sp Example: \f(CW$AGI\fR\->database_put('test', 'status', 'authorized'); .Sp Returns: 1 on success, 0 otherwise .ie n .IP "$AGI\->exec($app, $options)" 4 .el .IP "\f(CW$AGI\fR\->exec($app, \f(CW$options\fR)" 4 .IX Item "$AGI->exec($app, $options)" Executes \s-1AGI\s0 Command \*(L"\s-1EXEC\s0 \f(CW$app\fR \*(R"$options"" .Sp The most powerful \s-1AGI\s0 command. Executes the given application passing the given options. .Sp Example: \f(CW$AGI\fR\->exec('Dial', 'Zap/g2/8005551212'); .Sp Returns: \-2 on failure to find application, or whatever the given application returns .ie n .IP "$AGI\->get_data($filename, $timeout, $maxdigits)" 4 .el .IP "\f(CW$AGI\fR\->get_data($filename, \f(CW$timeout\fR, \f(CW$maxdigits\fR)" 4 .IX Item "$AGI->get_data($filename, $timeout, $maxdigits)" Executes \s-1AGI\s0 Command \*(L"\s-1GET DATA\s0 \f(CW$filename\fR \f(CW$timeout\fR \f(CW$maxdigits\fR\*(R" .Sp Streams \f(CW$filename\fR and returns when \f(CW$maxdigits\fR have been received or when \f(CW$timeout\fR has been reached. Timeout is specified in ms .Sp Example: \f(CW$AGI\fR\->get_data('demo\-welcome', 15000, 5); .ie n .IP "$AGI\->get_full_variable($variable [, $channel])" 4 .el .IP "\f(CW$AGI\fR\->get_full_variable($variable [, \f(CW$channel\fR])" 4 .IX Item "$AGI->get_full_variable($variable [, $channel])" Executes \s-1AGI\s0 Command \*(L"\s-1GET FULL VARIABLE\s0 \f(CW$variablename\fR \f(CW$channel\fR\*(R" .Sp Similar to get_variable, but additionally understands complex variable names and builtin variables. If \f(CW$channel\fR is not set, uses the current channel. .Sp Example: \f(CW$AGI\fR\->get_full_variable('status', '\s-1SIP/4382\s0'); .Sp Returns: The value of the variable, or undef if variable does not exist .ie n .IP "$AGI\->get_option($filename, $digits [, $timeout])" 4 .el .IP "\f(CW$AGI\fR\->get_option($filename, \f(CW$digits\fR [, \f(CW$timeout\fR])" 4 .IX Item "$AGI->get_option($filename, $digits [, $timeout])" Executes \s-1AGI\s0 Command \*(L"\s-1GET OPTION\s0 \f(CW$filename\fR \f(CW$digits\fR \f(CW$timeout\fR\*(R" .Sp Behaves similar to \s-1STREAM FILE\s0 but used with a timeout option. .Sp Streams \f(CW$filename\fR and returns when \f(CW$digits\fR is pressed or when \f(CW$timeout\fR has been reached. Timeout is specified in ms. If \f(CW$timeout\fR is not specified, the command will only terminate on the \f(CW$digits\fR set. \f(CW$filename\fR can be an array of files or a single filename. .Sp Example: \f(CW$AGI\fR\->get_option('demo\-welcome', '#', 15000); \f(CW$AGI\fR\->get_option(['demo\-welcome', 'demo\-echotest'], '#', 15000); .ie n .IP "$AGI\->get_variable($variable)" 4 .el .IP "\f(CW$AGI\fR\->get_variable($variable)" 4 .IX Item "$AGI->get_variable($variable)" Executes \s-1AGI\s0 Command \*(L"\s-1GET VARIABLE\s0 \f(CW$variablename\fR\*(R" .Sp Gets the channel variable .Sp Example: \f(CW$AGI\fR\->get_variable('status'); .Sp Returns: The value of the variable, or undef if variable does not exist .ie n .IP "$AGI\->hangup($channel)" 4 .el .IP "\f(CW$AGI\fR\->hangup($channel)" 4 .IX Item "$AGI->hangup($channel)" Executes \s-1AGI\s0 Command \*(L"\s-1HANGUP\s0 \f(CW$channel\fR\*(R" .Sp Hangs up the passed \f(CW$channel\fR, or the current channel if \f(CW$channel\fR is not passed. It is left to the \s-1AGI\s0 script to exit properly, otherwise you could end up with zombies. .Sp Example: \f(CW$AGI\fR\->\fIhangup()\fR; .Sp Returns: Always returns 1 .ie n .IP "$AGI\->\fInoop()\fR" 4 .el .IP "\f(CW$AGI\fR\->\fInoop()\fR" 4 .IX Item "$AGI->noop()" Executes \s-1AGI\s0 Command \*(L"\s-1NOOP\*(R"\s0 .Sp Does absolutely nothing except pop up a log message. Useful for outputting debugging information to the Asterisk console. .Sp Example: \f(CW$AGI\fR\->noop(\*(L"Test Message\*(R"); .Sp Returns: \-1 on hangup or error, 0 otherwise .ie n .IP "$AGI\->receive_char($timeout)" 4 .el .IP "\f(CW$AGI\fR\->receive_char($timeout)" 4 .IX Item "$AGI->receive_char($timeout)" Executes \s-1AGI\s0 Command \*(L"\s-1RECEIVE CHAR\s0 \f(CW$timeout\fR\*(R" .Sp Receives a character of text on a channel. Specify timeout to be the maximum time to wait for input in milliseconds, or 0 for infinite. Most channels do not support the reception of text. .Sp Example: \f(CW$AGI\fR\->receive_char(3000); .Sp Returns: Returns the decimal value of the character if one is received, or 0 if the channel does not support text reception. Returns \-1 only on error/hangup. .ie n .IP "$AGI\->receive_text($timeout)" 4 .el .IP "\f(CW$AGI\fR\->receive_text($timeout)" 4 .IX Item "$AGI->receive_text($timeout)" Executes \s-1AGI\s0 Command \*(L"\s-1RECEIVE TEXT\s0 \f(CW$timeout\fR\*(R" .Sp Receives a string of text on a channel. Specify timeout to be the maximum time to wait for input in milliseconds, or 0 for infinite. Most channels do not support the reception of text. .Sp Example: \f(CW$AGI\fR\->receive_text(3000); .Sp Returns: Returns the string of text if received, or \-1 for failure, error or hangup. .ie n .IP "$AGI\->record_file($filename, $format, $digits, $timeout, $beep, $offset, $beep, $silence)" 4 .el .IP "\f(CW$AGI\fR\->record_file($filename, \f(CW$format\fR, \f(CW$digits\fR, \f(CW$timeout\fR, \f(CW$beep\fR, \f(CW$offset\fR, \f(CW$beep\fR, \f(CW$silence\fR)" 4 .IX Item "$AGI->record_file($filename, $format, $digits, $timeout, $beep, $offset, $beep, $silence)" Executes \s-1AGI\s0 Command \*(L"\s-1RECORD FILE\s0 \f(CW$filename\fR \f(CW$format\fR \f(CW$digits\fR \f(CW$timeout\fR [$offset [$beep [s=$silence]]]\*(R" .Sp Record to a file until \f(CW$digits\fR are received as dtmf. The \f(CW$format\fR will specify what kind of file will be recorded. The \f(CW$timeout\fR is the maximum record time in milliseconds, or \-1 for no timeout. .Sp \&\f(CW$offset\fR samples is optional, and if provided will seek to the offset without exceeding the end of the file. .Sp \&\f(CW$silence\fR is the number of seconds of silence allowed before the function returns despite the lack of dtmf digits or reaching timeout. .Sp Example: \f(CW$AGI\fR\->record_file('foo', 'wav', '#', '5000', '0', 1, '2'); .Sp Returns: 1 on success, \-1 on hangup or error. .ie n .IP "$AGI\->say_alpha($string, $digits)" 4 .el .IP "\f(CW$AGI\fR\->say_alpha($string, \f(CW$digits\fR)" 4 .IX Item "$AGI->say_alpha($string, $digits)" Executes \s-1AGI\s0 Command \*(L"\s-1SAY ALPHA \s0\*(R"$string\*(L" \f(CW$digits\fR\*(R" .Sp Say a given character string, returning early if any of the given \s-1DTMF\s0 \f(CW$digits\fR are received on the channel. .Sp Returns Example: \f(CW$AGI\fR\->say_alpha('Joe Smith', '#'); .Sp Returns: 0 if playback completes without a digit being pressed; the \s-1ASCII\s0 numerical value of the digit if one was pressed; \-1 on error/hangup. .ie n .IP "$AGI\->say_date($time [, $digits])" 4 .el .IP "\f(CW$AGI\fR\->say_date($time [, \f(CW$digits\fR])" 4 .IX Item "$AGI->say_date($time [, $digits])" .PD 0 .ie n .IP "$AGI\->say_time($time [, $digits])" 4 .el .IP "\f(CW$AGI\fR\->say_time($time [, \f(CW$digits\fR])" 4 .IX Item "$AGI->say_time($time [, $digits])" .ie n .IP "$AGI\->say_datetime($time [, $digits [, $format [, $timezone]]])" 4 .el .IP "\f(CW$AGI\fR\->say_datetime($time [, \f(CW$digits\fR [, \f(CW$format\fR [, \f(CW$timezone\fR]]])" 4 .IX Item "$AGI->say_datetime($time [, $digits [, $format [, $timezone]]])" .PD Executes \s-1AGI\s0 Command \*(L"\s-1SAY DATE\s0 \f(CW$number\fR \f(CW$digits\fR\*(R" Executes \s-1AGI\s0 Command \*(L"\s-1SAY TIME\s0 \f(CW$number\fR \f(CW$digits\fR\*(R" Executes \s-1AGI\s0 Command \*(L"\s-1SAY DATETIME\s0 \f(CW$number\fR \f(CW$digits\fR \f(CW$format\fR \f(CW$timezone\fR\*(R" .Sp Say a given date or time, returning early if any of the optional \s-1DTMF\s0 \f(CW$digits\fR are received on the channel. \f(CW$time\fR is number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (\s-1UTC\s0), commonly known as \&\*(L"unixtime.\*(R" .Sp For say_datetime, \f(CW$format\fR is the format the time should be said in; see voicemail.conf (defaults to \*(L"ABdY 'digits/at' IMp\*(R"). Acceptable values for \&\f(CW$timezone\fR can be found in /usr/share/zoneinfo. Defaults to machine default. .Sp Example: \f(CW$AGI\fR\->say_date('100000000'); \f(CW$AGI\fR\->say_time('100000000', '#'); \f(CW$AGI\fR\->say_datetime('100000000', '#', 'ABdY IMp', '\s-1EDT\s0'); .Sp Returns: \-1 on error or hangup; 0 if playback completes without a digit being pressed; the \s-1ASCII\s0 numerical value of the digit of one was pressed. .ie n .IP "$AGI\->say_digits($number, $digits)" 4 .el .IP "\f(CW$AGI\fR\->say_digits($number, \f(CW$digits\fR)" 4 .IX Item "$AGI->say_digits($number, $digits)" Executes \s-1AGI\s0 Command \*(L"\s-1SAY DIGITS\s0 \f(CW$number\fR \f(CW$digits\fR\*(R" .Sp Says the given digit string \f(CW$number\fR, returning early if any of the \f(CW$digits\fR are received. .Sp Example: \f(CW$AGI\fR\->say_digits('8675309'); .Sp Returns: \-1 on error or hangup, 0 if playback completes without a digit being pressed, or the \s-1ASCII\s0 numerical value of the digit of one was pressed. .ie n .IP "$AGI\->say_number($number, $digits, $gender)" 4 .el .IP "\f(CW$AGI\fR\->say_number($number, \f(CW$digits\fR, \f(CW$gender\fR)" 4 .IX Item "$AGI->say_number($number, $digits, $gender)" Executes \s-1AGI\s0 Command \*(L"\s-1SAY NUMBER\s0 \f(CW$number\fR \f(CW$digits\fR [$gender]\*(R" .Sp Says the given \f(CW$number\fR, returning early if any of the \f(CW$digits\fR are received. .Sp Example: \f(CW$AGI\fR\->say_number('98765'); .Sp Returns: \-1 on error or hangup, 0 if playback completes without a digit being pressed, or the \s-1ASCII\s0 numerical value of the digit of one was pressed. .ie n .IP "$AGI\->say_phonetic($string, $digits)" 4 .el .IP "\f(CW$AGI\fR\->say_phonetic($string, \f(CW$digits\fR)" 4 .IX Item "$AGI->say_phonetic($string, $digits)" Executes \s-1AGI\s0 Command \*(L"\s-1SAY PHONETIC \s0\*(R"$string\*(L" \f(CW$digits\fR\*(R" .Sp Say a given character string with phonetics, returning early if any of the given \s-1DTMF\s0 digits are received on the channel. .Sp Example: \f(CW$AGI\fR\->say_phonetic('Joe Smith', '#'); .Sp Returns: 0 if playback completes without a digit being pressed; the \s-1ASCII\s0 numerical value of the digit if one was pressed; \-1 on error/hangup. .ie n .IP "$AGI\->send_image($image)" 4 .el .IP "\f(CW$AGI\fR\->send_image($image)" 4 .IX Item "$AGI->send_image($image)" Executes \s-1AGI\s0 Command "\s-1SEND IMAGE\s0 \f(CW$image\fR .Sp Sends the given image on a channel. Most channels do not support the transmission of images. .Sp Example: \f(CW$AGI\fR\->send_image('image.png'); .Sp Returns: \-1 on error or hangup, 0 if the image was sent or if the channel does not support image transmission. .ie n .IP "$AGI\->send_text($text)" 4 .el .IP "\f(CW$AGI\fR\->send_text($text)" 4 .IX Item "$AGI->send_text($text)" Executes \s-1AGI\s0 Command \*(L"\s-1SEND TEXT \s0\*(R"$text" .Sp Sends the given text on a channel. Most channels do not support the transmission of text. .Sp Example: \f(CW$AGI\fR\->send_text('You've got mail!'); .Sp Returns: \-1 on error or hangup, 0 if the text was sent or if the channel does not support text transmission. .ie n .IP "$AGI\->set_autohangup($time)" 4 .el .IP "\f(CW$AGI\fR\->set_autohangup($time)" 4 .IX Item "$AGI->set_autohangup($time)" Executes \s-1AGI\s0 Command \*(L"\s-1SET AUTOHANGUP\s0 \f(CW$time\fR\*(R" .Sp Cause the channel to automatically hangup at