The DialAnswer sample application demonstrates how the etLine, etPhone, etPlay, and etRecord controls can be used together. It allows the user to both call out (Dial) and receive incoming calls (Answer) , and track the various events fired in the process by the output in the log box. The user can:
Select from all available telephony devices,
Test the selected device for a dial tone,
Play files when a call is connected,
Cause those files to loop continuously or to only play once,
Modify the volume and gain on the speakerphone, if attached, and
Record all or part of a call to a wave file.
Note about detecting automated answering devices:
This application also demonstrates how the etLine.Silence detection feature along with a timer can be used to detect if an outbound call is answered by an automated answering device (an answering machine or voice mail system). Please note that your telephony device must support SilenceDetection (voice modems DO NOT support SilenceDetection due to limitations in the UnimodemV TSP and/or the modem hardware).
The etLine1.OnConnected event for this application shows the TimerAutomatedAnsweringDevice and etLine.Call.MonitorSilence properties are enabled for outbound calls. If the TimerAutomatedAnsweringDevice.OnTimer event (3 seconds after OnConnected) fires prior to the etLine.OnSilence event (after 1.5 seconds of silence) then it is assumed that an automated device has answered the call otherwise it is assumed that a human has answered.
The idea is to measure the time that the greeting (initial continuous voice energy) takes before a period of silence occurs. In this example application, etLine1.Call.MonitorSilenceDuration is set to 1500 milliseconds and TimerAutoamatedAnsweringDevice.Duration is set to 3000 milliseconds. When a person answers the phone they would say something like "Good morning, thank you for calling ExceleTel" or simply "Hello" which take about 2 seconds or less to say. Our voice mail system says "Hello, thank you for calling ExceleTel. All of our lines are busy please leave a message after the tone", this takes about 6 seconds to say. Answering machine detection in this manner can be reliable but naturally has some limitations. Also, you may have to modify the properties etLine1.MonitorSilence.Duration and TimerAutomatedansweringDevice.Duration to achieve effective results for your application.
The following compoments are used:
|
Controls |
Purpose |
|
CheckBoxActive |
Used to activate the TAPI Line device. |
|
ComboBoxDevice |
Used to select the TAPI line device. |
|
ButtonTeleScopes |
When clicked the TeleScope.Visible property for the etLine, etPhone, etPlay and etRecord controls are toggled to True or False causing the TeleScopes to be displayed or hidden. |
|
ButtonDial |
For dialing out bound calls. |
|
EditPhoneNumber |
Holds the phone number to be dialed. |
|
ButtonAnswer |
For answering in bound calls. |
|
ButtonHangup |
For hanging up all calls. |
|
ButtonDialtone |
Testing for dial tone. |
|
CheckBoxPlayOnConnect |
For indicating if the wave files is played when the etLine.OnConnected event fires. |
|
EditWaveFile |
The wave file to be played. See CheckBoxPlayOnConnect |
|
CheckBoxLoop |
Indicates if the wave file should loop. |
|
CheckBoxPhone |
Indicates if the etPhone device should be used. |
|
ImageHandsetOffHook ImageHandsetOnHook |
Displays the status of the handset hookswitch for the etPhone.Device.ID. |
|
GroupBoxSpeakerphone |
Contains the controls for working with the etPhone speakerphone features. |
|
RadioButtonSPOffHook RadioButtonSPOnHook |
Show the status and allows the state to be set for the etPhone.SpeakerphoneHookswitch |
|
LabelSPVolume |
Displays "Volume" |
|
EditSPVolume |
Holds the value of the etPhone.Speakerphone.Volume |
|
ButtonSPVolumeApply |
Updates the property etPhone.Speakerphone.Volume when pressed. |
|
LabelSPGain |
Displays "Gain" |
|
EditSPGain |
Holds the value of the etPhone.Speakerphone.Gain |
|
ButtonSPGainApply |
Updates the property etPhone.Speakerphone.Gain when pressed. |
|
ButtonRecord |
Records a wave file using the etRecord control while the button is held down. |
|
ButtonClear |
Clears the information in the Memo1 control |
|
Memo1 |
Displays the log information. |
|
etLine1 |
The etLine control |
|
etPhone1 |
The etPhone control |
|
etPlay1 |
The etPlay record |
|
etRecord1 |
The etRecord control |
|
TimerAutomatedAnsweringDevice |
Timer used along with etLine.MonitorSilence to detect answering machines. |
The following properties' values are different from the default values:
|
Controls |
Property |
Setting |
|
ComboBoxDevice |
Style |
csDropDown |
|
TimerAutomatedAnsweringDevice |
Interval |
300 |
|
|
Enabled |
False |
The following subroutines are used (most of which are Event Handlers, some of which are not):
Event Handler Routine for: creation of the form
It fills the combo box with available TAPI line devices and initializes the line device and the combo box to the first device available.
Event Handler Routine for: the CheckBoxActive.OnClick event for the CheckBoxActive controls
The “Active” checkbox is used to turn the selected line device on, when checked, or off, when not checked. If the control is checked, then the line device is activated by setting the property etLine1.Device.Active = TRUE; if not checked, then the line device is deactivated by setting the property etLine1.Device.Active = FALSE.
When deactivating the line device, the TAPI phone device is first deactivated by setting the property etPhone1.Device.Active = FALSE. When the line device is inactive, the ButtonDial and ButtonDialTone controls are disabled.
If there error LINEERR_INVALIDMEDIAMODE is returned when activating the line device, the device is probably not 100% TAPI-compliant. The etLine1.Device.MediaModesActive is set to LINEMEDIAMODE_DATAMODEM and etLine1.Device.Active is once again set to TRUE. We assume that the device is a modem that does not support the voice features, so we attempt to activate the modem in data mode.
After successfully activating the line device, the ButtonDial and ButtonDialTone controls are enabled. If the CheckBoxPhone is checked and etLine1.Phone.Available = True, indicating that a TAPI phone device is available, then the TAPI phone device is activated by setting the property etPhone1.Device.Active = TRUE. If the property etLine1.TAPI.TSP contains the string "Universal Modem Driver", then the property etPlay1.Volume.Enabled is set to false because voice modems do not support the volume features.
If the the TAPI line device supports playing wave files (etLine1.WavePlay.Available = True), then controls CheckBoxPlayOnConnect, EditWaveFile, and CheckBoxLoop are enabled; otherwise they are disabled.
The UpdatePhoneDisplay routine is called to enable or disable controls having to do with the speakerphone settings.
Event Handler Routine for: the ButtonAnswer.OnClick event of the ButtonAnswer control
The etLine1.Call.Answer method is called then the etLine1.Error properties are tested for errors. Any error information is appended to the log edit box.
Event Handler Routine for: the ButtonSPGainApply.OnClick event of the ButtonSPGainApply control
The the property etPhone.Speakerphone.Gain is set to the value in the EditSPGain control. The event queue is allowed to be emptied allowing time for the speakerphone to adjust. The EditSPGain control is updated to match the speakerphone’s new gain setting.
Event Handler Routine for: the ButtonSPVolumeApply.OnClick event of the ButtonSPVolumeApply control
The the property etPhone.Speakerphone.Volume is set to the value in the EditSPVolume control. The event queue is allowed to be emptied, allowing time for the speakerphone to adjust. The EditSPVolume control is updated to match the speakerphone’s new volume setting.
Event Handler Routine for: the ButtonClear.OnClick event of the ButtonClear control
The information in the Memo1 control is cleared.
Event Handler Routine for: the ButtonDial.OnClick event for the ButtonDial button
The etLine1.Call.PhoneNumber property is set to the value in the EditPhoneNumber control then the etLine1.Call.Dial method is then called. If no errors occurred then the ButtonDial and ButtonDialtone controls are disabled and the ButtonHangup control is enabled.
Event Handler Routine for: the ButtonDialtone.OnClick event for the ButtonDialtone control
The property is set to etLine1.Call.PhoneNumber = “;W” which indicates to the telephony device to begin the dialing process although wait for a dial tone. The etLine1.Privilege.None and etLine1.Device.MediaModesActive properties are then tested to see if this device has the ability to make a voice call. The etLine1.Call.Dial method is then called. If successful, then then the etLine1.OnDialtone event fires.
This method of checking for a dial tone may not work with all telephony devices. Not all Telephony Service Providers (TSP) and/or telephony devices support the "W" as a valid "dial-able" character. See the etLine.Call.PhoneNumber property for the list of dial-able characters.
Event Handler Routine for: the ButtonHangup.OnClick event for the ButtonHangup control
Prior to calling the etLine1.Call.Hangup method etPlay1.Device.Active is checked to see if a wave file is currently playing, if it is then it is stopped by setting etPlay1.Device.Active = False. etRecord1.Device.Active is also checked and stopped if necessary.
Event Handler Routine for: the ComboBoxDevice.OnChange event of the ComboBoxDevice control
The etLine1.Device.Active property is checked to see if the current device is active. If so, then CheckBoxActive is set to false causing the device to be deactivated. The etLine1.Device.ID is set to the index value of the device chosen in the combo box. If no errors occurred, then the properties etLine1.Privilege.Monitor and etLine1.Privilege.Owner are set to true.
Event Handler Routine for: the CheckBoxLoop.OnClick event of the CheckBoxLoop control
The etPlay1.Device.Loop property is set to the value this check box.
Event Handler Routine for: the RadioButtonSPOffHook.OnClick event of the RadioButtonSPOffHook control
The etPhone1.Speakerphone.MicrophoneAndSpeaker property is set to the value of this radio button.
Event Handler Routine for: the RadioButtonSPOnHook.OnClick event of the RadioButtonSPOnHook control
The etPhone1.Speakerphone.OnHook property is set to the value of this radio button.
Event Handler Routine for: the CheckBoxPhone.OnClick event of the CheckBoxPhone control
If this is unchecked and etPhone1.Device.Active = True, then etPhone1.Device.Active is set to False. If it is checked and etLine1.Device.Active = True and etPhone1.Device.Active = False, then etPhone1.Device.Active is set to True. If an error occurs, then etPhone1.Device.Active remains False and this check box remains unchecked.
Event Handler Routine for: the ButtonRecord.MouseDown event of the ButtonRecord control
As long as this button is held down, etRecord1 will record a wave file. etLine1.TAPI.TSP is checked to see if a Dialogic board is being used. If so, then the etRecord1.Source.Format.ID is set to use the wave format "uLaw8000 Hz, 8 bit, Mono". Otherwise, the default "PCM 8000 Hz, 16 bit, Mono" is used. etRecord.Source.Format.FileName is set to a valid path and file name. The correct wave audio device is selected by setting etRecord1.Device.ID to the value of the property etLine1.WaveRecord.ID. Recording is started by setting etRecord1.Device.Active to True.
Event Handler Routine for: the ButtonRecord.MouseUp event of the ButtonRecord control
When this button is released, etRecord1 will stop recording and etPlay1 will play the wave file that was just recorded. Recording is stopped by setting etRecord1.Device.Active = False. If etPlay1 is currently playing a wave file, then it is stopped. etPlay1.Source.FileName is set to the file that was just recorded. The correct wave audio device is selected by setting etPlay1.Device.ID to the value of the property etLine1.WavePlay.ID. Playing is started by setting etPlay1.Device.Active = True.
Event Handler Routine for: the ButtonTeleScopes.OnCLick event of the ButtonTeleScopes control
This button causes the TeleScope.Visibile properties to be toggled for the etLine1, etPhone1, etPlay1 and etRecord1 controls. This causes the TeleScopes to be displayed or hidden.
Event Handler Routine for: etLine.OnBusy event of the etLine control
When this occurs, the etLine1.Call.Hangup method is called.
Event Handler Routine for: etLine.OnCallBegin event of the etLine control
This event is appended to the log edit box on-screen.
Event Handler Routine for: etLine.OnCalledID event of the etLine control
When the etLine.OnCalledID event fires the etLine1.Call.CalledID.Name and etLine1.Call.CalledID.Number property values are appended to the log..
Event Handler Routine for: etLine.OnCallEnd event of the etLine control
This event is appended to the log edit box on-screen.
Event Handler Routine for: etLine.OnCallerID event of the etLine control
When the etLine1.OnCallerID event fires, the etLine1.Call.CallerID.Name and etLine1.Call.CallerID.Number property values are appended to the log..
Event Handler Routine for: etLine.OnConnected event of the etLine control
The etLine1.Call.Origin is checked to see if the call is inbound or outbound.
The Enabled property for several buttons is modified.
Event Handler Routine for: etLine.OnConnectedID event of the etLine control
When the etLine.OnConnectedID event fires, the etLine1.Call.ConnectedID.Name and etLine1.Call.ConnectedID.Number property values are appended to the log..
Event Handler Routine for: etLine.OnDialing event of the etLine control
This event is appended to the log edit box on-screen.
Event Handler Routine for: etLine.OnDialtone event of the etLine control
When the etLine1.OnDialtone fires, the global State variable is checked to see if the ButtonDialtone button was clicked. If it was, then it is indicated in the log that the dial tone test was successful. Otherwise, it is simply indicated in that log that this event has fired.
Event Handler Routine for: etLine.OnDigitReceived event of the etLine control
If a wave file is currently playing, then it is stopped by setting etPlay1.Device.Active = False. If a wave play device is available, the wave file for the digit will be played. For example, if "1" is received, then etPlay1.Source.FileName will be set to "1" causing the wave file 1.wav to be played by setting etPlay1.Device.Active = True. There are no wave files for the following DTMF tones "*", "#", "A", "B", "C" or "D".
For an example of how to use the Tag parameter, see the IVR4Line sample program.
Event Handler Routine for: etLine.OnDisconnected event of the etLine control
If ButtonDialtone had been clicked and this event occurs, then the etLine1.Call.DisconnectMode property is tested to see if the dial tone was detected. This may not work with some telephony devices because not all Telephony Service Providers (TSP) and/or telephony devices are capable of reporting a disconnect mode.
If the etPlay1.Device.Active property is True then a wave file is currently playing and must be stopped by setting etPlay1.Device.Active = False. If the etRecord1.Device.Active property is True then a wave file is currently recording and must be stopped by setting etRecord1.Device.Active = False.
The etLine1.Call.Hangup method is called to hang up the call.
Event Handler Routine for: etLine.OnError event of the etLine control
The log is updated to indicate that this event has fired.
Event Handler Routine for: etLine.OnIdle event of the etLine control
The ButtonDialtone and ButtonDial controls are enabled. The ButtonRecord, ButtonAnswer and ButtonHangup are disabled. If the etPlay1.Device.Active property is True then a wave file is currently playing and must be stopped by setting etPlay1.Device.Active = False. If the etRecord1.Device.Active property is True then a wave file is currently recording and must be stopped by setting etRecord1.Device.Active = False.
Event Handler Routine for: etLine.OnOffering event of the etLine control
The ButtonAnswer control is enabled. The ButtonDialtone control is disabled.
Event Handler Routine for: etLine.OnRedirectingID event of the etLine control
The etLine1.Call.RedirectingID.Name and etLine1.Call.RedirectingID.Number property values are appended to the log.
Event Handler Routine for: etLine.OnRedirectionID event of the etLine control
The etLine1.Call.RedirectionID.Name and etLine1.Call.RedirectionID.Number property values are appended to the log.
Event Handler Routine for: etLine.OnRing event of the etLine control
The log edit box is updated with a message.
Event Handler Routine for: etLine.OnRingBack event of the etLine control
The log edit box is updated with a message.
Event Handler Routine for: etLine.OnSilence event of the etLine control
If the property etLine.Call.Origin indicates that this is an outbound call, then TimerAutomatedAnsweringDevice is disabled. Monitoring for silence is stopped by setting etLine1.Call.MonitorSilence.Active to False. The current time and the stored time are used to see if 2 seconds have passed since silence detection has been initiated. If silence was detected in less than 2 seconds then the call was probably answered by a human and not an answering machine.
Answering machine detection in this manner can be reliable although you may have to modify the properties etLine1.MonitorSilence.Duration and TimerAutomatedansweringDevice.Duration.
Event Handler Routine for: etLine.OnSpecialInfo event of the etLine control
The log edit box is updated with a message.
Event Handler Routine for: etPhone.OnDigitDown event of the etPhone control
The log edit box is updated with a message.
Event Handler Routine for: etPhone.OnDigitUp event of the etPhone control
The log edit box is updated with a message.
Event Handler Routine for: etPhone.OnError event of the etPhone control
The log is updated to indicate that this event has fired.
Event Handler Routine for: etPhone.OnHandsetHookSwitch event of the etPhone control
The current state for the etPhone1.HandsetHookSwitch properties are displayed in the log and the UpdatePhoneDisplay routine is called.
Event Handler Routine for: etPhone.OnPhoneState event of the etPhone control
The etPhone1.OnPhoneState event is fired when the current state of the TAPI Phone device changes. The etPhone1.Device.State and etPhone1.Device.StateDetails property values are displayed in the log.
Event Handler Routine for: etPhone.OnSpeakerphoneGain event of the etPhone control
The etPhone1.OnSpeakerphoneGain event is fired when the gain for the speakerphone is adjusted. The etPhone1.Speakerphone.Gain property is displayed in the log. The EditSPGain control is updated with the new value of etPhone1.Speakerphone.Gain.
Event Handler Routine for: etPhone.OnSpeakerphoneHookSwitch event of the etPhone control
The etPhone1.OnSpeakerphoneHookSwitch event is fired when the SpeakerphoneHookSwitch state changes. The current state for the etPhone1.Speakerphone HookSwitch properties are displayed in the log and the RadioButtonSPOffHook and RadioButtonSPOffHook controls are updated.
Event Handler Routine for: etPhone.OnSpeakerphoneVolume event of the etPhone control
The etPhone1.OnSpeakerphoneVolume event is fired when the volume for the speakerphone is adjusted. The etPhone1.Speakerphone.Volume property is displayed in the log. The EditSPVolume control is updated with the new value of etPhone1.Speakerphone.Volume.
Event Handler Routine for: etPlay.OnDone event of the etPlay control
The etPlay1.OnDone event is fired when the wave file has completed playing. The log is updated to indicate that this event has fired.
Event Handler Routine for: etPlay.OnError event of the etPlay control
The etPlay1.OnError event is fired when an error has occurred while using this control. The log is updated to indicate that this event has fired.
Event Handler Routine for: etPlay.OnLoaded event of the etPlay control
The etPlay1.OnLoaded event is fired when the entire wave file has finished loading into memory. The log is updated to indicate that this event has fired.
Event Handler Routine for: etPlay.OnLoop event of the etPlay control
The etPlay1.OnLoop event is fired when the wave file has completed playing and it is about to begin playing again. The log is updated to indicate that this event has fired.
Event Handler Routine for: etPlay.OnWarning event of the etPlay control
The etPlay1.OnWarning event fires when a non-fatal error occurs while playing a .WAV file. A message box is popped up to tell the user about it. If the user presses the “Cancel” button, the value of the Continue variable is set to false which causes the file to stop playing.
Event Handler Routine for: etRecord.OnError event of the etRecord control
The etRecord1.OnError event is fired when an error as occurred while using this control. The log is updated to indicate that this event has fired.
Event Handler Routine for: etRecord.OnWarning event of the etRecord control
The etRecord1.OnWarning event fires when a non-fatal error occurs while recording a .WAV file. A message box is popped up to tell the user about it. If the user presses the “Cancel” button, the value of the Continue variable is set to false which causes the file to stop recording.
Event Handler Routine for: closing of the form
If the etPlay1.Device.Active property is True then a wave file is currently playing and must be stopped by setting etPlay1.Device.Active = False. If the etRecord1.Device.Active property is True then a wave file is currently recording and must be stopped by setting etRecord1.Device.Active = False. The line device is closed by setting the etLine1.Device.Active property to False.
Event Handler Routine for: the EditSPGain.OnExit event of the EditSPGain control
If the value is outside the valid range for the etPhone.Speakerphone.Gain property, the value is reset.
Event Handler Routine for: the EditSPVolume.OnExit event of the EditSPVolume control
If the value is outside the valid range for the etPhone.Speakerphone.Volume property the the value is reset.
Event Handler Routine for: the TimerAutomatedAnsweringDevice.OnTimer event of the TimerAutomatedAnsweringDevice control
The time is disabled so it will not fire again. Monitoring for silence is stopped by setting etLine1.Call.MonitorSilence.Active = False. Since more than 3 seconds has passed since the etLine.OnConnected event has fired and silence was not detected then it is assumed that this calls was answered by an automated answering device. The log is updated to indicated this.
Answering machine detection in this manner can be reliable, but you may have to modify the properties etLine1.Call.MonitorSilence.Duration and TimerAutomatedansweringDevice.Duration
This is not an event handler routine. It updates the controls to match the state of the TAPI phone device. If there is no phone connected to the line (etLine.Phone.Available = False), the buttons that have to do with a phone are disabled and the bitmaps showing the phone’s state are hidden.