.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "Vgetty 3pm"
.TH Vgetty 3pm "2022-05-12" "perl v5.34.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"
Modem::Vgetty \- interface to vgetty(8)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&        use Modem::Vgetty;
\&        $v = new Modem::Vgetty;
\&
\&        $string = $v\->receive;
\&        $v\->send($string);
\&        $string = $v\->expect($str1, $str2, ...);
\&        $v\->waitfor($string);
\&        $rv = $v\->chat($expect1, $send1, $expect2, $send2, ...);
\&
\&        $ttyname = $v\->getty;
\&        $rv = $v\->device($dev_type);
\&        $rv = $v\->autostop($bool);
\&        $rv = $v\->modem_type; # !!! see the docs below.
\&
\&        $rv = $v\->beep($freq, $len);
\&        $rv = $v\->dial($number);
\&        $rv = $v\->play($filename);
\&        $rv = $v\->record($filename);
\&        $rv = $v\->wait($seconds);
\&        $rv = $v\->play_and_wait($filename);
\&        $v\->stop;
\&
\&        $v\->add_handler($event, $handler_name, $handler);
\&        $v\->del_handler($event, $handler_name);
\&        $v\->enable_events;
\&        $v\->disable_events;
\&
\&        $number = $v\->readnum($message, $tmout, $repeat);
\&
\&        $v\->shutdown;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Modem::Vgetty\*(C'\fR is an encapsulation object for writing applications
for voice modems using the \fB\fBvgetty\fB\|(8)\fR or \fB\fBvm\fB\|(8)\fR package. The answering
machines and sofisticated voice applications can be written using this
module.
.SH "OVERVIEW"
.IX Header "OVERVIEW"
\&\fIVoice modem\fR is a special kind of modem, which (besides the normal
data and/or fax mode) can communicate also in voice mode. It means
it can record sounds it hears from the phone line to the file,
Play-back recorded files, it can beep to the line, and it can detect
various standard sounds coming from the line (busy tone, silence,
dual tone modulation frequency (\s-1DTMF\s0) keypad tones, etc).
An example of the voice modem can be the ZyXEL U1496, \s-1US\s0 Robotics
Sportster (not Courier), etc.
.PP
To use this software with the voice modem you need to have the
\&\fB\fBvgetty\fB\|(8)\fR package installed. \fBVgetty\fR is distributed as a part of
\&\fBmgetty\fR package. In fact, \fBvgetty\fR is a \fB\fBmgetty\fB\|(8)\fR with the voice
extensions. Vgetty has some support for scripting \- when it receives
an incoming call, it runs a voice shell (it is program specified in
the \fBvoice.conf\fR file) as its child process, establishes the read
and write pipes to it, and tells it the number of the appropriate
descriptors in the environment variables. Voice shell can now
communicate with \fBvgetty\fR. It can tell \fBvgetty\fR \*(L"Play this file\*(R",
or \*(L"Record anything you hear to that file\*(R", or \*(L"Notify me when
user hangs up\*(R", etc. Sophisticated voice systems and answering
machines can be build on top of \fBvgetty\fR.
.PP
\&\fBmgetty\fR (including the \fBvgetty\fR) is available at
the following \s-1URL:\s0
.PP
.Vb 1
\&        ftp://alpha.greenie.net/pub/mgetty/
.Ve
.PP
Originally there was a (Bourne) shell interface to \fBvgetty\fR only.
The \fBModem::Vgetty\fR module allows user to write the voice shell in Perl.
The typical use is to write a script and point the \fBvgetty\fR to it
(in \fBvoice.conf\fR file). The script will be run when somebody calls in.
Another use is running voice shell from the \fB\fBvm\fB\|(8)\fR program, which
can for example dial somewhere and say something.
.SH "QUICK START"
.IX Header "QUICK START"
.Vb 10
\&        #!/usr/bin/perl
\&        use Modem::Vgetty;
\&        my $v = new Modem::Vgetty;
\&        $v\->add_handler(\*(AqBUSY_TONE\*(Aq, \*(Aqendh\*(Aq, sub { $v\->stop; exit(0); });
\&        local $SIG{ALRM} = sub { $v\->stop; };
\&        $v\->enable_events;
\&        $v\->record(\*(Aq/tmp/hello.rmd\*(Aq);
\&        alarm(20);
\&        $v\->waitfor(\*(AqREADY\*(Aq);
\&        $v\->shutdown;
.Ve
.PP
The above example installs the simple `exit now'-style handler for the
\&\fB\s-1BUSY_TONE\s0\fR event (which is sent by \fBvgetty\fR when user hangs up)
and then records the \fBhello.rmd\fR file. Put this text into a file
and then point \fBvgetty\fR to it in the \fBvoice.conf\fR. After you dial into
your voice modem, you can record a 20\-seconds of some message.
Verify that \fB/tmp/hello.rmd\fR exists. Now delete the line contaning
the word \*(L"record\*(R" and two subsequent lines and insert to the file
the following line instead of them:
.PP
.Vb 1
\&        $v\->play_and_wait(\*(Aq/tmp/hello.rmd\*(Aq);
.Ve
.PP
Now call the voice modem and listen to the sounds you have just recorded.
.SH "METHODS"
.IX Header "METHODS"
.SS "Begin and end of communication"
.IX Subsection "Begin and end of communication"
The \fBModem::Vgetty\fR object will initialize the communication pipes to
the \fBvgetty\fR at the creation time \- in the constructor. The closing
of the communication is done via the \fBshutdown\fR method:
.PP
.Vb 1
\&        $v\->shutdown;
.Ve
.PP
The module will call this method itself from the destructor, if you do
not call it explicitly.
.SS "Low-level communication"
.IX Subsection "Low-level communication"
Users probably don't want to use these methods directly. Use the higher-level
functions instead.
.IP "receive" 4
.IX Item "receive"
This method returns a string received from the \fBvgetty\fR. It parses
the string for the event types and runs appropriate event handlers.
If event handler is run it waits for another string.
.IP "send($string)" 4
.IX Item "send($string)"
This method sends the string \fB\f(CB$string\fB\fR to the \fBvgetty\fR process.
.ie n .IP "expect($string1, $string2, ...)" 4
.el .IP "expect($string1, \f(CW$string2\fR, ...)" 4
.IX Item "expect($string1, $string2, ...)"
Receives a string from \fBvgetty\fR (using the \fBreceive\fR method described
above) and returns it iff it is equal to one of the strings in the argument
list. When something different is received, this method returns \fBundef\fR.
.IP "waitfor($string)" 4
.IX Item "waitfor($string)"
Waits until the string \fB\f(CB$sring\fB\fR is received from \fBvgetty\fR (using the
\&\fBreceive\fR method described above).
=item chat($expect1, \f(CW$sent1\fR, \f(CW$expect2\fR, \f(CW$sent2\fR, ...)
.Sp
A chat-script with \fBvgetty\fR. Arguments are interpreted as the received-sent
string pairs. A received string equals to the empty string means that no
\&\fBreceive\fR method will be called at that place. This can be used for
constructing chat scripts beginning with the sent string instead of the
received one.
.SS "Vgetty control methods"
.IX Subsection "Vgetty control methods"
There are miscellaneous methods for controllig \fBvgetty\fR and querying its
status.
.IP "getty" 4
.IX Item "getty"
Returns the name of the modem special file (e.g. \fB/dev/ttyC4\fR).
.IP "device($name)" 4
.IX Item "device($name)"
Sets the port of the voice modem input and output is done to.
Possible values are qw(\s-1NO_DEVICE DIALUP_LINE EXTERNAL_MICROPHONE
INTERNAL_SPEAKER LOCAL_HANDSET\s0).
.IP "autostop($bool)" 4
.IX Item "autostop($bool)"
With autostop on, the voicelib will automatically abort a
play in progress and return \s-1READY.\s0 This is useful for faster
reaction times for voice menus. Possible arguments are qw(\s-1ON OFF\s0).
\&\fBNote:\fR The interface should probably be changed to accept the
Perl boolean arguments (undef, something else). Returns defined
value on success, undef on failure.
.IP "modem_type" 4
.IX Item "modem_type"
\&\fBvgetty\fR currently has no way of telling voice shell
the type of the current modem. This method is a proposed interface
for determining this type. Currently returns \fBundef\fR. The appropriate
low-level interface has to be implemented in \fBvgetty\fR first.
.SS "Voice commands"
.IX Subsection "Voice commands"
.ie n .IP "beep($freq, $len)" 4
.el .IP "beep($freq, \f(CW$len\fR)" 4
.IX Item "beep($freq, $len)"
Sends a beep through the chosen device using given frequency (\s-1HZ\s0) and length
(in miliseconds).
Returns a defined value on success or undef on failure.
The state of the vgetty changes to \*(L"\s-1BEEPING\*(R"\s0 and \fBvgetty\fR
returns \*(L"\s-1READY\*(R"\s0 after a beep is finshed. Example:
.Sp
.Vb 3
\&        $v\->beep(50,10);
\&        # Possibly do something else
\&        $v\->waitfor(\*(AqREADY\*(Aq);
.Ve
.IP "dial($number)" 4
.IX Item "dial($number)"
Modem tries to dial a given number. The \fBvgetty\fR changes its state
to \*(L"\s-1DIALING\*(R"\s0 and returns \*(L"\s-1READY\*(R"\s0 after the dialing is finished.
.IP "play($filename)" 4
.IX Item "play($filename)"
The \fBvgetty\fR tries to play the given file as a raw modem data.
See the \*(L"Voice data\*(R" section for details on creating the raw modem data
file. It changes the state to \*(L"\s-1PLAYING\*(R"\s0 and returns \*(L"\s-1READY\*(R"\s0 after
playing the whole file.
.IP "record($filename)" 4
.IX Item "record($filename)"
The \fBvgetty\fR records the voice it can hear on the line to the given file.
It uses the raw modem data format (which can be re-played using the
\&\fBplay\fR subroutine). \fBvgetty\fR changes its state to \*(L"\s-1RECORDING\*(R"\s0 and
you need to manually stop the recording using the \fBstop\fR method
after some time (or, you can set \fBautostop\fR and wait for any event
\&\- silence, busy tone, etc).
.IP "wait($seconds)" 4
.IX Item "wait($seconds)"
The modem waits for a given number of seconds. Changes its state to
\&\*(L"\s-1WAITING\*(R"\s0 and returns \*(L"\s-1READY\*(R"\s0 after the wait is finished. Example:
.Sp
.Vb 2
\&        $v\->wait(5);
\&        $v\->waitfor(\*(AqREADY\*(Aq);
.Ve
.IP "stop" 4
.IX Item "stop"
The \fBvgetty\fR stops anything it is currently doing and returns to the
command state. You must use \fBstop\fR when you want to call another
\&\fBbeep\fR, \fBdial\fR, \fBplay\fR, \fBrecord\fR or \fBwait\fR before the previous
one is finished. The \fBvgetty\fR returns \*(L"\s-1READY\*(R"\s0 after the \fBstop\fR
is called. So it is possible to interrupt a main routine waiting
for \*(L"\s-1READY\*(R"\s0 from the event handler:
.Sp
.Vb 6
\&        my $dtmf;
\&        $v\->add_handler(\*(AqRECEIVED_DTMF\*(Aq, \*(Aqreadnum\*(Aq,
\&                sub { my $self=shift; $self\->stop; $dtmf = $_[2]; });
\&        $v\->enable_events;
\&        $v\->wait(10); 
\&        $v\->waitfor(\*(AqREADY\*(Aq);
.Ve
.Sp
In the previous example the \fBwaitfor\fR method can be finished either by
the 10\-second timeout expired, or by the '\s-1READY\s0' generated by the
\&\fBstop\fR in the event handler. See also the \fBEvents\fR section.
.IP "play_and_wait($file)" 4
.IX Item "play_and_wait($file)"
It is an abbreviation for the following:
.Sp
.Vb 2
\&        $v\->play($file);
\&        $v\->waitfor(\*(AqREADY\*(Aq);
.Ve
.Sp
It is repeated so much time in the voice applications so I have decided
to make a special routine for it. I may add the similar routines
for \fBdial\fR, \fBrecord\fR, \fBbeep\fR and even \fBwait\fR in the future releases.
.SS "Event handler methods"
.IX Subsection "Event handler methods"
.ie n .IP "add_handler($event, $handler_name, $handler)" 4
.el .IP "add_handler($event, \f(CW$handler_name\fR, \f(CW$handler\fR)" 4
.IX Item "add_handler($event, $handler_name, $handler)"
Installs a call-back routine \f(CW$handler\fR for the event type \f(CW$event\fR.
The call-back routine is called with three arguments. The first
one is the Modem::Vgetty object itself, the second one is the
event name and the third one is optional event argument.
The \fB\f(CB$handler_name\fB\fR argument can be anything. It is used when you
want to delete this handler for identificating it.
.ie n .IP "del_handler($event, $handler_name)" 4
.el .IP "del_handler($event, \f(CW$handler_name\fR)" 4
.IX Item "del_handler($event, $handler_name)"
This method deletes the handler \f(CW$handler_name\fR for the \f(CW$event\fR event.
The result of unregistering the handler from the
event handler of the same event is unspecified. It may or may not be
called.
.IP "enable_events" 4
.IX Item "enable_events"
Tells the \fBvgetty\fR that the voice shell is willing to dispatch events.
No events are sent by \fBvgetty\fR until this method is called.
.IP "disable_events" 4
.IX Item "disable_events"
Tells the \fBvgetty\fR that the voice shell doesn't want to receive
any events anymore.
.SS "The \fBreadnum\fP method"
.IX Subsection "The readnum method"
.ie n .IP "readnum($message, $tmout, $repeat)" 4
.el .IP "readnum($message, \f(CW$tmout\fR, \f(CW$repeat\fR)" 4
.IX Item "readnum($message, $tmout, $repeat)"
The applications often need to read the multi-digit
number via the \s-1DTMF\s0 tones.  This routine plays the \fB\f(CB$message\fB\fR to the
voice object and then waits for the
sequence of the \s-1DTMF\s0 keys finished by the `#' key. If no key is pressed
for \fB\f(CB$tmout\fB\fR of seconds, it re-plays the message again. It returns
failure if no key is pressed after the message is played \fB\f(CB$repeat\fB\fR\-th
time. It returns a string (a sequence of \s-1DTMF\s0 tones 0\-9,A\-D and `*')
without the final `#'. When some \s-1DTMF\s0 tones are received and no terminating
`#' or other tone is received for \fB\f(CB$tmout\fB\fR seconds, the routine returns
the string it currently has without waiting for the final '#'.
\&\s-1DTMF\s0 tones are accepted even at the time the \fB\f(CB$message\fB\fR is played.
When the \s-1DTMF\s0 tone is received, the playing of the \fB\f(CB$message\fB\fR is
(with some latency, of course) stopped.
.Sp
\&\fB\s-1NOTE:\s0\fR The interface of this routine can be changed in future releases,
because I am not (yet) decided whether the current interface is the best one.
See also the \fB\s-1EXAMPLES\s0\fR section where the source code of this routine
(and its co-routine) is discussed.
.SH "EVENTS"
.IX Header "EVENTS"
.SS "Introduction"
.IX Subsection "Introduction"
Events are asynchronous messages sent by \fBvgetty\fR to the voice shell.
The \fBModem::Vgetty\fR module dispatches events itself in the \fBreceive\fR
method. User can register any number of handlers for each event.
When an event arrives, all handlers for that event are called (in no
specified order).
.SS "Event types"
.IX Subsection "Event types"
At this time, the \fBModem::Vgetty\fR module recognizes the following
event types (description is mostly re-typed from the \fBvgetty\fR
documentation):
.IP "\s-1BONG_TONE\s0" 4
.IX Item "BONG_TONE"
The modem detected a bong tone on the line.
.IP "\s-1BUSY_TONE\s0" 4
.IX Item "BUSY_TONE"
The modem detected busy tone on the line (when dialing to the busy
number or when caller finished the call).
.IP "\s-1CALL_WAITING\s0" 4
.IX Item "CALL_WAITING"
Defined in \s-1IS\-101\s0 (I think it is when the line receives another call-in
when some call is already in progress. \-Yenya).
.IP "\s-1DIAL_TONE\s0" 4
.IX Item "DIAL_TONE"
The modem detected dial tone on the line.
.IP "\s-1DATA_CALLING_TONE\s0" 4
.IX Item "DATA_CALLING_TONE"
The modem detected data calling tone on the line.
.IP "\s-1DATA_OR_FAX_DETECTED\s0" 4
.IX Item "DATA_OR_FAX_DETECTED"
The modem detected data or fax calling tones on the line.
.IP "\s-1FAX_CALLING_TONE\s0" 4
.IX Item "FAX_CALLING_TONE"
The modem detected fax calling tone on the line.
.IP "\s-1HANDSET_ON_HOOK\s0" 4
.IX Item "HANDSET_ON_HOOK"
Locally connected handset went on hook.
.IP "\s-1HANDSET_OFF_HOOK\s0" 4
.IX Item "HANDSET_OFF_HOOK"
Locally connected handset went off hook.
.IP "\s-1LOOP_BREAK\s0" 4
.IX Item "LOOP_BREAK"
Defined in \s-1IS\-101.\s0
.IP "\s-1LOOP_POLARITY_CHANGE\s0" 4
.IX Item "LOOP_POLARITY_CHANGE"
Defined in \s-1IS\-101.\s0
.IP "\s-1NO_ANSWER\s0" 4
.IX Item "NO_ANSWER"
After dialing the modem didn't detect answer for the time
give in dial_timeout in voice.conf.
.IP "\s-1NO_DIAL_TONE\s0" 4
.IX Item "NO_DIAL_TONE"
The modem didn't detect dial tone (make sure your modem is
connected properly to your telephone company's line, or check
the \s-1ATX\s0 command if dial tone in your system differs from
the standard).
.IP "\s-1NO_VOICE_ENERGY\s0" 4
.IX Item "NO_VOICE_ENERGY"
It means that the modem detected voice energy at the
beginning of the session, but after that there was a
period of some time of silence (the actual time can be set using
the \fBrec_silence_len\fR and \fBrec_silence_treshold\fR parameters
in \fBvoice.conf\fR).
.IP "\s-1RING_DETECTED\s0" 4
.IX Item "RING_DETECTED"
The modem detected an incoming ring.
.IP "\s-1RINGBACK_DETECTED\s0" 4
.IX Item "RINGBACK_DETECTED"
The modem detected a ringback condition on the line.
.IP "\s-1RECEIVE_DTMF\s0" 4
.IX Item "RECEIVE_DTMF"
The modem detected a dtmf code. The actual code value
(one of 0\-9, *, #, A\-D) is given to the event handler as the
third argument.
.IP "\s-1SILENCE_DETECTED\s0" 4
.IX Item "SILENCE_DETECTED"
The modem detected that there was no voice energy at the
beginning of the session and after some time of silence
(the actual time can be set using
the \fBrec_silence_len\fR and \fBrec_silence_treshold\fR parameters
in \fBvoice.conf\fR).
.IP "\s-1SIT_TONE\s0" 4
.IX Item "SIT_TONE"
Defined in \s-1IS\-101.\s0
.IP "\s-1TDD_DETECTED\s0" 4
.IX Item "TDD_DETECTED"
Defined in \s-1IS\-101.\s0
.IP "\s-1VOICE_DETECTED\s0" 4
.IX Item "VOICE_DETECTED"
The modem detected a voice signal on the line. \s-1IS\-101\s0 does
not define, how the modem makes this decision, so be careful.
.IP "\s-1UNKNOWN_EVENT\s0" 4
.IX Item "UNKNOWN_EVENT"
None of the above :)
.SH "VOICE DATA"
.IX Header "VOICE DATA"
Voice shell can send the voice data to the modem using the \fBplay\fR
method and record them using the \fBrecord\fR method. The \*(L".rmd\*(R" extension
(Raw Modem Data) is usually used for these files. The \*(L".rmd\*(R" is not
a single format \- every modem has its own format (sampling frequency,
data bit depth, etc). There is a \fBpvftools\fR package for converting
the sound files (it is a set of filters similar to the \fBnetpbm\fR for image
files). The \fB\fBpvftormd\fB\|(1)\fR filter can be used to create the \s-1RMD\s0 files
for all known types of modems.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Answering machine"
.IX Subsection "Answering machine"
A simple answering machine can look like this:
.PP
.Vb 10
\&        #!/usr/bin/perl
\&        use Modem::Vgetty;
\&        my $voicemaster = \*(Aqroot@localhost\*(Aq;
\&        my $tmout = 30;
\&        my $finish = 0;
\&        my $v = new Modem::Vgetty;
\&        $v\->add_handler(\*(AqBUSY_TONE\*(Aq, \*(Aqfinish\*(Aq,
\&                sub { $v\->stop; $finish=1; });
\&        $v\->add_handler(\*(AqSILENCE_DETECTED\*(Aq, \*(Aqfinish\*(Aq,
\&                sub { $v\->stop; $finish=1; });
\&        local $SIG{ALRM} = sub { $v\->stop; };
\&        $v\->enable_events;
\&        $v\->play_and_wait(\*(Aq/path/welcome.rmd\*(Aq);
\&        $v\->beep(100,10);
\&        $v\->waitfor(\*(AqREADY\*(Aq);
\&        if ($finish == 0) {
\&                my $num = 0;
\&                $num++ while(\-r "/path/$num.rmd");
\&                $v\->record("/path/$num.rmd");
\&                alarm $tmout;
\&                $v\->waitfor(\*(AqREADY\*(Aq);
\&        }
\&        system "echo \*(AqPlay with rmdtopvf /path/$num.rmd|pvftoau >/dev/audio\*(Aq" .
\&                 " | mail \-s \*(AqNew voice message\*(Aq $voicemaster";
\&        exit 0;
.Ve
.PP
See the \fBexamples/answering_machine.pl\fR in the source distribution,
which contains a more configurable version of the above text.
It first sets the event handlers for the case of busy tone (the caller
hangs up) or silence (the caller doesn't speak at all). The handler
stops \fBvgetty\fR from anything it is currently doing and sets the \f(CW$finish\fR
variable to 1. Then the reception of the events is enabled and 
the welcome message is played. Then the answering machine beeps
and starts to record the message. Note that we need to check the
\&\f(CW$finish\fR variable before we start recording to determine if user
hanged up the phone. Now we find the first filename <number>.rmd
such that this file does not exist and we start to record the message
to this file. We record until user hangs up the phone or until
the timeout occurs.
.SS "Readnum routine"
.IX Subsection "Readnum routine"
An interesting application of the low-level routines is the
\&\fBVoice::Modem::readnum\fR method. The calling sequence of this method
has been discussed above. The source code for this routine and its
co-routine will be discussed here, so that you can write your own
variants of \fBreadnum\fR (which in fact does not have too general
interface). See also the source code of \fBVgetty.pm\fR for the \fBreadnum\fR
source.
.PP
The \fBreadnum\fR routine needs to have its own event handler for the
\&\fB\s-1RECEIVED_DTMF\s0\fR event and the way the handler can communicate with
this routine. In our solution we use \*(L"static\*(R" variables:
.PP
.Vb 3
\&        my $_readnum_number = \*(Aq\*(Aq;
\&        my $_readnum_timeout = 10;
\&        my $_readnum_in_timeout = 1;
.Ve
.PP
The event handler will add the new character to the end of the 
\&\fB\f(CB$_readnum_number\fB\fR variable. The \fB\f(CB$_readnum_timeout\fB\fR is the number
of seconds both \fBreadnum\fR and the event handler should wait for the
next keypress, and the \fB\f(CB$_readnum_in_timeout\fB\fR is a flag used by the
event handler for notifying the main \fBreadnum\fR routine that it forced
the \fBvgetty\fR to emit the `\s-1READY\s0' message because of the final `#'
has been received.
.PP
.Vb 4
\&        sub _readnum_event {
\&                my $self = shift;
\&                my $input = shift; # Unused. Should be \*(AqRECEIVED_DTMF\*(Aq.
\&                my $dtmf = shift;
\&
\&                if ($dtmf eq \*(Aq#\*(Aq) { # Stop the reading now.
\&                        $_readnum_in_timeout = 0;
\&                        $self\->stop;
\&                        $self\->{LOG}\->print("_readnum_event(): Got #; stopping\en");
\&                        return;
\&                }
\&                $_readnum_number .= $dtmf;
\&                $self\->stop;
\&                $self\->expect(\*(AqREADY\*(Aq);
\&                # Restart the wait again.
\&                $_readnum_in_timeout = 1;
\&                $self\->wait($_readnum_timeout);
\&        }
.Ve
.PP
The event handler is installed for the `\s-1RECEIVED_DTMF\s0' event only, so it
doesn't need to check for the \fB\f(CB$input\fB\fR value. The actual \s-1DTMF\s0 key is in
the third parameter, \fB\f(CB$dtmf\fB\fR. Note that the handler will be called
when \fBvgetty\fR is \s-1PLAYING\s0 or \s-1WAITING\s0 and the \fBreadnum\fR routine will
be waiting for the `\s-1READY\s0' message. This allows us to immediately
interrupt waiting by the \fB\f(CB$self\fB\-\fRstop> (which emits the `\s-1READY\s0' message).
So when the `#' \s-1DTMF\s0 tone is received, we send a \fBstop\fR to \fBvgetty\fR.
If something else is received, we \fBstop\fR the \fBvgetty\fR too but we
enter a new wait using \fB\f(CB$self\fB\-\fRwait>.
.PP
.Vb 9
\&        sub readnum {
\&                my $self = shift;
\&                my $message = shift;
\&                my $timeout = shift;
\&                my $times = shift;
\&                $_readnum_number = \*(Aq\*(Aq;
\&                $_readnum_in_timeout = 1;
\&                $_readnum_timeout = $timeout if $timeout != 0;
\&                $times = 3 if $times == 0;
\&
\&                # Install the handler.
\&                $self\->add_handler(\*(AqRECEIVED_DTMF\*(Aq, \*(Aqreadnum\*(Aq, \e&_readnum_event);
\&                while($_readnum_in_timeout != 0 && $_readnum_number eq \*(Aq\*(Aq
\&                        && $times\-\- > 0) {
\&                        $self\->play_and_wait($message);
\&                        last if $_readnum_in_timeout == 0;
\&                        while ($_readnum_in_timeout != 0) {
\&                                $self\->wait($_readnum_timeout);
\&                                $self\->expect(\*(AqREADY\*(Aq);
\&                        }
\&                }
\&                return undef if $times < 0;
\&                $self\->del_handler(\*(AqRECEIVED_DTMF\*(Aq, \*(Aqreadnum\*(Aq);
\&                $self\->stop;
\&                $self\->expect(\*(AqREADY\*(Aq);
\&                $_readnum_number;
\&        }
.Ve
.PP
The \fBreadnum\fR routine just sets up the event handler, then plays
the \fB\f(CB$message\fB\fR and waits for the input (possibly several times).
The main work is done in the event handler. At the end the handler
is unregistered and the final value is returned.
.SS "Callme script"
.IX Subsection "Callme script"
In the \fBexamples\fR subdirectory of the source distribution there is
a \fBcallme.pl\fR script. This dials the given number and plays the
given message. Use the following command to run it:
.PP
.Vb 1
\&        vm shell \-S /usr/bin/perl callme.pl <number> <message>.rmd
.Ve
.SH "BUGS"
.IX Header "BUGS"
There may be some, but it will more likely be in the \fBvgetty\fR itself.
On the other hand, there can be typos in this manual (English is not my
native language) or some parts of the interface that should be
redesigned. Feel free to mail any comments on this module to me.
.SH "TODO"
.IX Header "TODO"
.IP "Modem type recognition" 4
.IX Item "Modem type recognition"
The \fBvgetty\fR should be able to tell the voice shell the name of the
current modem type.
.IP "The \fB_wait()\fR routines" 4
.IX Item "The _wait() routines"
I need to implement the routines similar to \fBplay_and_wait\fR for other
\&\fBvgetty\fR states as well.
.IP "Debugging information" 4
.IX Item "Debugging information"
The module has currently some support for writing a debug logs
(use the \f(CW$Modem::Vgetty::testing\fR = 1 and watch the /var/log/voicelog
file). This needs to be re-done using (I think) Sys::Syslog.
I need to implement some kind of log-levels, etc.
.IP "Mgetty/Vgetty 1.1.17" 4
.IX Item "Mgetty/Vgetty 1.1.17"
Need to figure out what is new in 1.1.17 (I use 1.1.14 now). I think
new \fBvgetty\fR can play more than one file in the single `\s-1PLAY\s0' command,
it (I think) have some support for sending voice data from/to the voice
shell via the pipe, etc.
.SH "AUTHOR"
.IX Header "AUTHOR"
The \fBModem::Vgetty\fR package was written by Jan \*(L"Yenya\*(R" Kasprzak
<kas@fi.muni.cz>. Feel free to mail me any suggestions etc.
on this module. Module itself is available from \s-1CPAN,\s0 but be sure
to check the following address, where the development versions can
be found:
.PP
.Vb 1
\&        http://www.fi.muni.cz/~kas/vgetty/
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1998 Jan \*(L"Yenya\*(R" Kasprzak <kas@fi.muni.cz>. All rights
reserved. This package is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.