Pat Deegan

VoiceXML::Client::DeviceHandle

NAME

        VoiceXML::Client::DeviceHandle - Encapsulates the communications device (eg Voice Modem)

SYNOPSIS

The VoiceXML::Client::DeviceHandle module is meant to serve as an abstract base class for voice communication devices.

It provides the interface VoiceXML::Client::DeviceHandle::XXX modules are expected to implement.

AUTHOR

LICENSE

    VoiceXML::Client::DeviceHandle module, device handle api based on the VOCP voice messaging system package
    VOCP::Device.
    
    Copyright (C) 2002,2008 Patrick Deegan
    All rights reserved

This file is part of VoiceXML::Client.

    VoiceXML::Client is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    VoiceXML::Client is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with VoiceXML::Client.  If not, see <http://www.gnu.org/licenses/>.

new [PARAMHREF]

Creates a new instance, calling init() with PARAMHREF if passed. Returns a new blessed object.

init PARAMHREF

Called by new(). This method is used in derived classes to perform startup initialisation. Override this method if required.

Subclass method stubs

The following methods are in this parent class (but only implemented as stubs) in order to define a common interface for all VoiceXML::Client::DeviceHandle subclasses.

These methods are actually heavily based on the Modem::Vgetty package methods and the interface should be considered tentative and expected to change as new devices are added (eg a SIP voice over IP interface would be nice).

beep FREQUENCY LENGTH

Sends a beep through the chosen device using given frequency (HZ) and length (in miliseconds). Returns a defined and true value on success.

dial DESTINATION

Connects to destination. Returns defined & true on success.

play PLAYPARAM

plays a sound (file, text-to-speech, whatever is appropriate) base on PLAYPARAM. May or may not block during play depending on device implementation. Returns true on success.

record TOFILE

Records input from user to device to file TOFILE. Returns true on success.

wait TIME

Simply waits for TIME seconds. Device should accept/queue user input during interval.

waitFor STATE

Waits until STATE is reached/returned by device. Device should accept/queue user input during interval.

stop

Immediately stop any current activity (wait, play, record, etc.).

blocking_play PLAYTHIS

play PLAYTHIS and return only when done.

inputMode [MODE]

Returns the current input mode (single- or multi- digit currently supported), optionally setting to MODE, if passed - use the %VoiceXML::Client::DeviceHandle::InputMode hash for valid MODE values.

readnum PLAYTHIS TIMEOUT [REPEATTIMES]

Plays the PLAYTHIS and then waits for the sequence of the digit input finished. If no are entered within TIMEOUT seconds, it re-plays the message again. It returns failure (undefined value) if no digits are entered after the message has been played REPEATTIMES (defaults to 3) times.

It returns a string (a sequence of DTMF tones 0-9,A-D and `*') without the final stop key (normally '#').

validDataFormats

Returns an array ref of valid data formats (eg 'rmd', 'wav', 'au') the device will accept.