PRODUCTS
jScripter
Web Pipe
jCore
 
INFORMATION
Affiliate
About Us
Contact Us
 
Products . VTapi . Online Help Sign In
Table of Contents
Properties
 
 
BSTR DeviceID
Unique identifier of VTapi instance. It can be any string. Program uses this ID to save and restore instance-specific settings such as modem name, text-to-speech engine etc.

long SilenceLevel
A number that represents the minimum sound volume to be assumed as silence.

long SilenceDuration
Duration of silence in seconds before receiving OnSilence event.

OLE_COLOR BackgroundColor
Control background color.

OLE_COLOR ForegroundColor
Control foreground color.

OLE_COLOR SpotColor
Voice energy indicator color. This will appear when voice energy is found on the line.

boolean AGC
Automatic gain control option. Set it to TRUE to enable AGC.

BSTR LogFile

Log File location. Control writes there the same information OnDebug event receives.

Set LogFile to empty string to stop logging.


BSTR KeysPressed

Remembers DTMF keys pressed previously.


BSTR ComPort

This is used in PASSTHROUGH mode only. By reading/writing this property you can execute modem commands and read modem responce.

See Passthrough() function description below.

Methods
boolean Open()
Input: void
Output: TRUE if device opened successfully and FALSE otherwise

This will open telephony device selected with DeviceID property. Synchronous.

Application will receive a OnOpened notification when device is actually opened.


void Stop()
Input: void
Output: void

This will stop voice playing back or recording. Application will receive OnIdle event once it is stopped. Asynchronous.


void Close()
Input: void
Output: void

This will close telephony device (modem) and free all resources assotiated with device. Synchronous.

Application receives OnClosed event once device was closed.


boolean IsOpened()
Input: void
Output: TRUE if device is in opened state and FALSE otherwise

Checks is device is opened with Open function. Synchronous.


boolean AnswerCall()
Input: void
Output: TRUE if device the call was answered successfully

AnswerCall should be called when OnRing event is received. Once answered, modem is capable playing back files and recording. Asynchronous.

Application will receive OnConnected notification event when call is actually answered and device is ready for playing back and recording voice data.


boolean Dial(BSTR PhoneNumber)
Input: a string that represents phone number. The following.
Output: TRUE if device the call was answered successfully

AnswerCall should be called when OnRing event is received. Once answered, modem is capable playing back files and recording. Synchronous.

Remarks. Characters allowed in PhoneNumber string:

Characters corresponding to the DTMF and/or pulse digits.0-9 A-D * #
!Hex (21). Indicates that a hookflash (one-half second onhook, followed by one-half second offhook before continuing) is to be inserted in the dial string.
P pHex (50) or Hex (70). Indicates that pulse dialing is to be used for the digits following it.
T tHex (54) or Hex (74). Indicates that tone (DTMF) dialing is to be used for the digits following it.
,Hex (27). Indicates that dialing is to be paused. The duration of a pause is device specific and can be retrieved from the line's device capabilities. Multiple commas can be used to provide longer pauses.
W wHex (57) or Hex (77). An uppercase or lowercase W indicates that dialing should proceed only after a dial tone has been detected.


void HangUp()
Input: void.
Output: void

Disconnects a call, or abandons a call attempt in progress. Synchronous.


boolean PlaybackFile(BSTR FileName)
Input: file path and name.
Output: TRUE if paying back queued successfully and FALSE otherwise.

Plays back text or wave file over modem. All file format conversations are done automatically. Asynchronous.

Application will receive OnIdle event once playing back is finished or OnError if error occured.


boolean Record(BSTR FileName)
Input: file path and name.
Output: TRUE if recording queued successfully and FALSE otherwise.

Records sound to wave file. Asynchronous.

Application will receive OnIdle event once playing back is finished or OnError if error occured.


boolean IsFileOpened()
Input: void
Output: TRUE if file is opened.

This shows if file is actually opened after calling PlaybackFile, PlaybackText, GenerateDTMF, GenerateTone, PlaybackMelody, Record functions.


boolean PlaybackText(BSTR Text)
Input: text string to be converted to speech and played back over phone line.
Output: TRUE if test was sussessfully queued for playing back.

Plays back any text and numbers ober modem. You should have Text-To-Speech engine installed in order to use this option.


boolean Pickup()
Input: void
Output: TRUE if call was picked up successfully

The linePickup function picks up the line. Asynchronous.

Aplication will receive OnConnected event when line is actually picked up. Application can playback and record files once the line was picked up.


void Preferences()
Input: void
Output: void

Shows preferences dialog. Synchronous.

The settings will be saved in VTAPI.INI file.


boolean AnalyseInput()
Input: void
Output: TRUE if function succeeded and FALSE otherwise.

Starts frequency monitoring. Application will receive OnFrequency, OnBusy, OnDialtone, OnAnswered events. Asynchronous.


boolean GenerateDTMF(BSTR Keys)
Input: a list of DTMF keys to be played back over modem. The following characters are accepted: 1 2 3 4 5 6 7 8 9 * # A B C D
Output: TRUE if function succeeded and FALSE otherwise.

Generates DTMF tones. Application will receive OnIdle once the tones were generated. Asynchronous.


boolean GenerateTones(long Freq1, long Freq2, long Duration)
Input: Freq1, Freq2 - frequencies to be generated. Duration - tone duration in milliseconds
Output: TRUE if function succeeded and FALSE otherwise.

Generates a tone with specified frequency and duration. Application will receive OnIdle once the tone was generated. Asynchronous.

Set Freq2 to zero to generate single frequency tone.


boolean PlaybackMelody(BSTR MelodyString)
Input: string that represents a melody
Output: TRUE if function succeeded and FALSE otherwise.

This will playback a melody over phone line. Application will receive OnIdle once playing back is finished. Asynchronous.

MelodyString must have the following format:

Allowed symbols:Description:
C, D, E, F, G, A, Hnotes
#, $dies and flat
Vnnvolume (nn=1...9)
Onnoctave (nn=0...5, nn=3 - main octave)
-one octave down
+one octave up
nnnduration (nnn=0...1000 ms)
,(comma) - very short pause
\nnnmakes a beep with frequency nn
;divides two numbers in the string.
any other symbolpause

Some examples:

NAMEMELODY
Elise
Lambada
Djo Dassen
Happy Birthday
Jingle Bell
Popcorn

boolean WaitForIdle(long TimeToWait)
Input: Time to wait for idle state in milliseconds. Set TimeToWait to -1 for infinite waiting
Output: TRUE if control is in idle state or FALSE otherwise.

Waits for OnIdle event. Synchronous.

Application should use this function for waiting while playback or recording is done.


boolean AssumeConnected()
Input: void
Output: TRUE if function succeeded and FALSE otherwise.

Assumes that telephony device is in CONNECTED state. Asynchronous.

Some soft-modem drivers never send CONNECTED event to application. So, application will never get OnConnected event. In this case you should call AssumeConnected once OnHardwareDialtone event received.


boolean PassThrough()
Input: void
Output: TRUE if function succeeded and FALSE otherwise.

Switches the driver into PASSTHROUGH mode. You can execute modem commands and read modem replies using ComPort property. Asynchronous.

Call Stop function to quit PASSTHROUGH mode. You can use WaitForIdle function to wait while program exits passthrough mode.

Events

void OnDebug(BSTR Message)
Input: a string that represents debug message
Output: void

This allows to understand why program does not work as expected. OnDebug receives all TAPI messages, shows [un]successful calls to TAPI functions as well as other useful for debugging information.


void OnRing(long Number)
Input: ring number. (1, 2, 3 and so on)
Output: void

Application receives this event when incomming call is detected


void OnOpened(BSTR Device)
Input: device name
Output: void

Application receives this event when device is successfully opened with Open function.


void OnClosed(BSTR Device)
Input: device name
Output: void

Application receives this event when device was closed with Close function.


void OnDtmf(long KeyCode)
Input: ASCII code of key pressed (0-9, A-D, *, #)
Output: void

Application receives this event when remote party puched a key on his keypad.


void OnBusy(long Source)
Input: rasen for calling (see below)
Output: void

Application receives this event when phone line is Busy.

SourceDescription
0Hardware busy. Telephony device reported that phone line is busy.
1Software busy detector has detected single-frequency busy tone. Single-frequency busy tones are common in the Europe
2Software busy detector has detected bual-frequency busy tone. Dual-frequency busy tones are common in the USA/Canada

It's essential to call AnalyseInput fuction in order to receive OnBusy(1) and OnBusy(2).

Some voice modems incorrectly detect busy signal. If you faced this problem - just ignore OnBusy(0) notification.


void OnDialtone(long Source)
Input: reason for call
Output: void

Application receives this event when dialtone is found on phone line.

SourceDescription
1Software dialtone detector has detected single-frequency dial tone.
2Software dialtone detector has detected dual-frequency dial tone.


void OnHardwareDialtone()
Input: void
Output: void

Hardware dial tone. Telephony device reported dial tone presence.

Please note - some modems report dial tone presence even if phone line is silent.


void OnCallerID(BSTR Number, BSTR Name)
Input: Number - caller's number. Name - caller's name
Output: void

Application receives this event when Caller ID is available.


void OnDataModem(BSTR Device)
Input: device name
Output: void

Application receives this notification if modem does not support voice features.


void OnSilence()
Input: void
Output: void

Application receives this notification when voice energy in phone line was less than SilenceLevel for SilenceDuration seconds.


void OnAnswered()
Input: void
Output: void

Application receives this event when remote party answered the call.

Important This is very basic implementation of pickup detector. It will not 100% guarantee that remote party actually picked up the phone.


void OnFrequency(long Freq, long Freq1, long Freq2)
Input: Freq - main frequency, Freq1 and Freg2 are dual frequencies that are present in phone line
Output: void

Application receives this event about 10 times per second.

The following rules are always valid:

Freq == Freq1 OR Freq == Freq2
Freq1 > Freq2 OR Freq1 == Freq2


void OnConnected()
Input: void
Output: void

Application receives this event when device is in CONNECTED state. Application may start playing back and recording voice once it received OnConnected event.


void OnError(long ErrCode)
Input: error code
Output: void

Application receives this event in case of the following errors:

ErrCodeReason
1Error picking up the call
Error answering a call
Dialing error
2Error Playing back the file or text
3Recording error


void OnIdle()
Input: void
Output: void

Application receives this event when playing back or recording is done.

It's better to use WaitForIdle function to wait for idle state rather than starting playback of new file in OnIdle procedure.

Pseudocode

Answering machine
Open

OnRing
  -->  Answer

OnConnected
  -->  PlaybackFile ( c:\greeting.wav )
  -->  WaitForIdle(-1)
  -->  Record ( c:\record.wav )

OnBusy
  -->  HangUp

Recording a call
Open

Pickup

Record ( c:\record.wav )

OnBusy
  -->  HangUp

IVR (Interactive Voice Response System)
This sample code pronounces key name pressed on keypad.
Open

OnRing
  -->  Answer

OnBusy
  -->  HangUp

OnDtmf ( Key )
  -->  Stop  // Stop currently played sound (if any)
  -->  WaitForIdle ( -1 )
  -->  PlaybackText ( "you pressed" + Key + "button" )

OnConnected
  -->  PlaybackText ( "Welcome to our IVR system" )

Predictive Dialer
Open

Dial "p2223344" // Force pulse dialing of 2223344

OnBusy
  -->  HangUp

OnConnected
  -->  AnalyseInput

OnAnswered
  -->  PlaybackText ( "Hello, world" )
  -->  WaitForIdle
  -->  HangUp


Affiliates · Features · Download · Online help · Order online
mobile version Copyright © 1999-2024 SoftCab, Inc. All Rights Reserved ·