Dialogic Dial Sample Program

DialogicDial.jpg (20204 bytes)

This sample program illustrates how to work with Dialogic cards to make outbound telephone calls. The following common telephony operations are demonstrated in this program:

Dialogic cards and drivers are stable! Therefore we believe them to be very useful and a good choice for your automated telephony needs. We will explain some of the eccentricities that you will need to be aware of and that this sample program illustrates how to overcome.

Requirements & Download

The sample program contained in this download was created with Visual Basic 5.

ExceleTel TeleTools v3.7, Visual Basic 5 or 6 and a Dialogic are required to use this sample program.

Click here for help with installing your Dialogic board to work with Microsoft's TAPI.

Using this Sample Program

  1. Select your Dialogic device from the list component
  2. Click the "Active" check box
  3. Enter a phone number in the edit box
  4. Click the "Dial" check box

This program will dial the same number again and again until the "Dial" check box is unchecked. You may change the phone number at any time even while the "Dial" check box is checked!

NOTE: Your Dialogic card must be properly configured.  Please see the technical notes on Dialogic cards.  Symptoms that your card is not properly configured for you line can be:

  • Connects before the line is answered
  • Hangs up in the middle of a call
  • Does not report the connected state when hearing voice energy
  • Does not detect the remote party hangup
  • Does not play wave files properly

 

Features

Repeated dialing (one call after another)

The etLine.OnIdle event is used to make the next call. (See etLine1_OnIdle where it calls the routine CheckDial_Click).

Making one outbound call after another can be a problem with virtually any TAPI line device. The idea is to know when the call is complete and when to dial the next call. The etLine.OnIdle event indicates when the call is idle meaning that the call no longer exists. However that does not mean that the TAPI line device is ready to make the next call. For this reason you may need to set etLine.Device.IdleDelay property. (See the Form_Load routine). This will cause the etLine.OnIdle event to delay firing for the given number of milliseconds allowing the TAPI line device time to prepare itself (reset) to make the next call.

Detection of bad phone numbers (special information tones)

The Dialogic card is one of the few telephony devices capable of detecting Special Information Tones also known as SIT tones. The etLine1_OnSpecialInfo event will fire when a SIT tone is detected. In most cases this tone indicates that the phone number dialed is invalid or dialed incorrectly.

Dialtone detection

You would expect the etLine.OnDialtone event to fire when a dialtone is detected. However this is not the way Dailogic cards work. The etLine.OnDialtone event will fire even when a dialtone is not present.

To get around this problem you can dial a blank phone number (See CheckDial_Click) then in the etLine.OnDialtone event dial the real number with an "L" added to the beginning. This will instruct the Dialogic card to detect a local dialtone (See etLine1_OnDialtone). If a dialtone is not detected then the etLine.OnDisconnected event will fire and the etLine.Call.DisconnectMode will have the value LINEDISCONNECTMODE_NODIALTONE.  This method can tie up resources on a multi-threaded application that uses multiple lines.

An easier way, depending on your application is to dial a call and use the TeleTools OnSpecialInfo event and read the etLine.CallSpecialInfo property.  Dialogic will report no dialtone as LINESPECIALINFO_NOCIRCUIT.  Technically, this is not correct since the TAPI spec designed this to report a NO_CIRCUIT SIT tone which is received when you call a number and there is no circuit on that end.  If you need to know the difference between these events, you could use a timer, or check other call progress identifiers like "ringback" to see if it occurred before you got the message.

No Answer

The Dialogic Telephony Service Provider (TSP) offers a way to cause the etLine.OnDisconnected event to fire when the remote party does not answer after a given number of rings (See etLine1_OnDisconnected). The etLine.Call.DisconnectMode will have the value LINEDISCONNECTMODE_NOANSWER.

Human and Answering Machine Detection

Dialogic does have a feature known as Positive Answering Machine Detection however we have not had success using this through TAPI. In fact we have heard a Dialogic technician say that this feature does not work properly! But you are not out of luck. With a little cleverness, a timer, a global variable and silence detection your application can make a good guess at detecting if an automated answering device has picked up.

The idea is simple. When a human answers the phone their greeting is generally short. For example: "Hello" or "Thank you for calling ExceleTel, may I help you?" An answering machine is usually much longer, for example: "Thank you for calling the Jones residence, we are unable to take your call at this time, please leave a message after the beep." Human greetings are general between 1 and 3 seconds, answering machine greetings are usually between 5 and 15 seconds or longer. Furthermore humans can be interrupted during a long greeting causing silence unlike an answering machine. The Microsoft TAPI documentation drops a few hints indicating that this is the way to do it!

Here is how it works:

When the etLine.OnConnected event fires:

  • The variable gdtConnected is set to the current date and time.
  • The TimerAutomatedAnsweringDevice timer is activated with an interval of 5 seconds
  • Silence monitoring is activated with a 2 second duration.
  • It is assumed that a human has answered so the WAV_ANSWER_HUMAN wave file is played.

When the etLine.OnSilence event fires:

  • Silence monitoring is deactivated.
  • The TimerAutomatedAnsweringDevice timer is deactivated.
  • If less than 5 seconds have passed then chances are a human has answered.
  • Else changes are an answering machine has answered.

When the TimerAutomatedAnsweringDevice.OnTimer event fires:

  • Silence monitoring is deactivated.
  • The TimerAutomatedAnsweringDevice timer is deactivated.
  • Changes are an answering machine has answered.

The actual code in the sample program is a little more complex.  We have added the ability to detect the end of the beep when an answering machine is detected.  This is useful for playing a message to be recorded on the answering machine.

Busy Signal Detection

The etLine.OnBusy event will fire when a busy signal is detected (See etLine1_OnBusy).

Remote Hang-up (Disconnects)

The etLine.OnDisconnected event will fire when the remote party hangs up (See etLine1_OnDisconnected). This event will not fire when the application hangs up.

Components

  Controls Purpose
ActiveCheck Used to activate the TAPI Line device.
ComboDevice Used to select the TAPI line device.
etLine1 The etLine control.
etPlay The etPlay control.
TimerAutomatedAnsweringDevice Timer used along with etLine.MonitorSilence to detect answering machines.
CheckDial Used to begin and end dialing.
TextPhoneNumber Holds the phone number to be dialed.
CommandClear Clears the information in the TextStatus control.
TextStatus Displays the log information.

Event Handlers & Subroutines

CheckActive_Click

This event handler routine fires when the user clicks the CheckActive component. It is used to activate and deactivate the selected TAPI line device.

CheckDial_Click

This event handler routine fires when the user clicks the CheckDial component. When checked a call will be dialed.

ComboDevice_Click

This event handler routine is called when the user clicks on the ComboDevice component to select a TAPI line device.

CommandClear_Click

This event handler routine fires when the user clicks the CommandClear component. It is used to clear the status information.

etLine1_OnBusy

This event handler routine fires when the etLine component detects a busy signal.

etLine1_OnConnected

This event handler routine fires when the etLine component detects the remote party has answered.

etLine1_OnDialtone

This event handler routine fires when the etLine component detects a dialtone. When working with Dialogic cards this event will always fire, even when a dialtone is not present. This is used to finish dialing the phone number.

etLine1_OnDisconnected

This event handler routine fires when the etLine component detects the remote party has ended the call (disconnected).

etLine1_OnIdle

This event handler routine fires when the etLine component detects the call no longer exists.

etLine1_OnSilence

This event handler routine fires when the etLine component detects silence for the given interval. Silence detection is used to detect answering machines and the silence following the beep.

etLine1_OnSpecialInfo

This event handler routine fires when the etLine component detects the special information tone delivered by the phone company. In most cases this tone indicates that the phone number dialed is invalid or dialed incorrectly.

etPlay1_OnDone

This event handler routine fires when the etPlay component detects the wave file is finished playing.

Form_Load

This event handler routine fires when the form is created. It fills the combo box with available TAPI line devices and initializes the line device and the combo box to the first device available.

Form_Resize

This event handler routine fires when the form size is changed. It modifies the size of the components to fix the size of the window.

Form_Unload

This event handler routine fires when the form is closed. It makes sure that the wave play device is deactivated. This code can be found in 4 location: CommandHangup_Click, etLine1_OnDisconnected, etLine1_OnIdle and Form_Unload

TimerAutomatedAnsweringDevice_Timer

This event handler routine fires when the timer is active and the interval is reached. It is used in conjunction with the TeleTools silence-monitoring feature to detect when human and answering machines answer an outbound call.