etGatherDigitsWorkAround Sample Program

TeleTools

This sample program demonstrates how to use the etLine.Call.GatherDigits feature with telephony devices that do not support Gathering Digits. For example voice modems.

Gathering digits allows you to easily collect multiple digits (DTMF).  Unlike Monitoring for digits which only returns one digit at a time.

See the etGatherDigits sample program for devices that do  support gathering digits

Requirements
Using This Sample Program
Download this Sample Program 
How this Sample Program Works
Source Code
Release Notes

Development Environment Technical Information
Telephony Hardware Technical Information

 

Requirements

You can use this sample with these Editions of TeleTools v3.7

  • TeleTools Standard

  • TeleTools Professional

  • TeleTools Enterprise

  • Any TAPI telephony device that supports monitoring digits but not gathering digits. For example: voice modems or a Dialogic card if you need to play a wave file at the same time you need to gather digits.

Using This Sample Program

To use etGatherDigitsWorkAround, simply select your device with the dropdown combobox. Place settings into the edit boxes as follows:

  • Timeout:  The value in milliseconds after which to stop waiting to gather digits

  • Count: The number of digits you want to gather

  • Terminate: The string you wish to receive in order to terminate the gathering of digits

  • Hangup Delay:  The number of milliseconds delay after OnDisconnected to issue hangup

Place an incoming call to the line attached to the selected device.  The program will automatically answer the call when the OnOffering event fires and if the device is capable and the Active checkbox is checked, it will use the etLine.MonitorDigits method and some logic to emulate the etLine.GatherDigits method.  Your digits are displayed in the digits box.  When any of the conditions set in the edit boxes are reached, for example the terminate character is reached, or the digit count is reached, the digits gathered are displayed. For more detailed info on how this program works, see BELOW.

Download this Sample Program

For Use TeleTools v3.7

File

Purpose

EXE Ready to run!

Visual Basic 5,6

Source code

Delphi 5,6,7 Source code

Tell us what you need?

Click here and tell us what you need!

   

How this Sample Program Works

When a device is selected the program checks to see if the device supports monitoring digits.  If it does not then a dialog box is displayed and the Active check box is disabled.  If the device support Gathering Digits then a dialogic box appears instructing the user to use the etGatherDigits sample program.  If the device does support monitoring for digits then the device is activated with the etLine.DeviceActive property.

Since this program is designed for testing, the etLine1.TAPIREPLYTIMEOUT property is set to 15 seconds.  The default value for this property is 60 seconds.  This will allow the program to return to you faster.

The etLine.OnOffering event is the first event to fire when an inbound call is detected.  This program answers the call when this event fires.

When the call is connected the etLine.OnConnected event fires and the SetGatherDigits subroutine is called.

SetGatherDigits starts and stops the monitoring of digits depending on the value of the Active check box.  If the Timeout value is greater than zero then the TimeoutTimer interval is set and it is enabled.

If the TimeoutTimer fires, the OnDigitsGathered subroutine is called with the current digits stored in the global variable sDigits.

The etLine.OnDigitReceived event handler routine is called whenever a digit is received.  

  • New digits are stored in the sDigits global variable. 

  • The Timeout timer is disabled and will be re-enabled if gathering digits is not otherwise terminated.  

  • If the new digit received matches one in TextTerminate.Text then the OnDigitsGathered subroutine is called.  

  • If the number of digits stored in the sDigits match the number in TextCount.Text then the OnDigitsGathered subroutine is called.

When digit gathering is terminated, the OnDigitsGathered subroutine is called. The gathered digits are provided in the Digits parameter and displayed in the TextDigits box.  The reason for termination provided in the Termination parameter and is displayed in the TextStatusetLine.  The "LINEGATHERTERM" values found in the etTTConst constant file are used to identify the value.

If the remote party disconnects while gathering digits is active then a short delay must occur before executing the etLine.Call.hangup method.  If the delay is too short then the call will not be disconnected and a TAPIREPLYTIMEOUT error will occur.  The program will then exit.  Use the TextDelay to increase or decrease the number of milliseconds to delay for your system.  Our testing indicates that as few a one millisecond solves this problem however we suggest using 10 milliseconds.  That is equivalent to 1/100 of a second.

Control

Description

ComboDevice

Holds the list of TAPI line devices installed on your computer

etLine

The TeleTools etLine component

TextStatusetLine

Status reports and errors are displayed here

TimerDigitTimout

The timer component to control the delay set in the TextDelay control

CheckActive

Toggle gathering digits on and off

TextDigits

A display field to show what digits are gathered

TextTimeOut

Stores the number of milliseconds after which gathering digits will complete if any of the other conditions still have not been met, such as the terminator character or gathering the specified number of digits

TextTerminate

Holds your value for the gather digits terminator.  Whatever you place in here will stop gathering of digits when it is detected

TextCount

Holds the number of digits you wish to gather.  Gathering digits is completed when this count is reached

TextDelay

Hold the value in milliseconds to delay hangup if call is disconnected while gathering digits is still active

 

Event Handler Routine

Description

CheckActive_Click

Runs the SetGatherDigits method to activate and deactivate gathering of digits

ComboDevice_Click

Allows you to select and change the active telephony device and checks to see if it is capable of gathering and/or monitoring digits

etLine1_OnCallEnd

Fires when the call is ended.

etLine1_OnConnected

Fires when the call is connected and immediately runs SetGatherDigits to see if it should start gathering digits

etLine1_OnDigitReceived

Fires for every DTMF digit received, gathers them and checks them for the terminator character and to see if they reach the count set in the TextCount field

etLine1_OnDisconnected

Fires when the remote party disconnects the call.  Turns off etLine.MonitorDigits, waits the specified delay, and then issues the etLine.CallHangup

etLine1_OnError

Triggers when TeleTools detects an error.  Traps it and displays it in the log line

etLine1_OnOffering

Answers the call when it is offered with the etLine.CallAnswer method

Form_Load

Sets the TAPI Reply timeout and populates the device combobox

TimerDigitTimout_Timer

This event fires when the number of milliseconds to wait for input is reached and then calls the OnDigitsGathered subroutine

 

Subroutine

Description

SetGatherDigits

Activate and deactivate the gather digits method, get and set parameters

IsVoiceModem

Checks to see if the device is a voice modem or not

etLine1_OnDigitsGathered

When the conditions are met to trigger the program that the digits are gathered, this routine displays the digits and displays status, including errors.  Normally, this event is fired by the GatherDigits method, but here we call it in our subroutines manually since we are using MonitorDigits

 

Release Notes

September 11, 2003

The Delphi version was added and differs cosmetically from the VB version.  In addition, it uses a log window instead of a status line and can detect a datamodem or a voicemodem.

April 30, 2003

An error was discovered in the etLine.OnDisconnected event.  etLine.GatherDigits.Active was being set to false when etLine.MonitorDigits.Active should have been used.  This was a minor error especially since etLine.MonitorDigits.Active is automatically set to false when the call is disconnected.

April 24, 2003

Published