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 p | Hex (50) or Hex (70). Indicates that pulse dialing is to be used for the digits following it. |
| T t | Hex (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 w | Hex (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, H | notes |
| #, $ | dies and flat |
| Vnn | volume (nn=1...9) |
| Onn | octave (nn=0...5, nn=3 - main octave) |
| - | one octave down |
| + | one octave up |
| nnn | duration (nnn=0...1000 ms) |
| , | (comma) - very short pause |
| \nnn | makes a beep with frequency nn |
| ; | divides two numbers in the string. |
| any other symbol | pause |
Some examples:
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.
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.
| Source | Description |
| 0 | Hardware busy. Telephony device reported that phone line is busy. |
| 1 | Software busy detector has detected single-frequency busy tone. Single-frequency busy tones are common in the Europe |
| 2 | Software 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.
| Source | Description |
| 1 | Software dialtone detector has detected single-frequency dial tone. |
| 2 | Software 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:
| ErrCode | Reason |
| 1 | Error picking up the call
Error answering a call
Dialing error |
| 2 | Error Playing back the file or text |
| 3 | Recording 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.
