Chapter 31

Third Party TAPI Tools


CONTENTS


In the previous chapters you learned how the TAPI system works and how you can use Visual Basic and Microsoft C++ to build your own TAPI-compliant applications. In this chapter you'll learn how to use two of the most popular third-party development tools for TAPI services. Each of these tools has a unique approach to building TAPI-enabled applications. At the end of the chapter, you'll also get a look at Microsoft Phone, the new application from Microsoft that combines MAPI, SAPI, and TAPI services.

The first TAPI tool you'll review is the Visual Voice Telephony Toolkit for Windows from Stylus Innovation, Inc. This system includes a handful of OCX controls that you place on your Visual Basic forms to gain access to TAPI services. By setting control properties, invoking methods, and responding to defined events, you can build solid multiline telephony applications in a very short time.

Note
The Visual Voice system comes in several versions for both 16- and 32-bit Windows operating systems. Visual Voice also sells versions for TAPI- and MWAVE-based systems. The version covered here is the 32-bit TAPI system. It runs fine on both 16- and 32-bit Windows.

The second TAPI development tool you'll test is the VBVoice system from Pronexus. The VBVoice approach to TAPI design is quite different. Instead of placing controls on your form and using them to gain access to TAPI services, the VBVoice system allows you to visually build your telephony application by linking the controls in a flow diagram. Using this method, you can build complete telephony applications without writing a single line of Visual Basic code.

Finally, you'll get a peek at Microsoft Phone-the new application from Microsoft that combines MAPI, SAPI, and TAPI services into a single communication application. You'll learn how to install and configure Microsoft Phone and see how you can combine telephony, e-mail, and speech into a single system.

The Visual Voice Telephony Toolkit for Windows

The Visual Voice Telephony Toolkit is one of the most popular TAPI systems for Visual Basic development. The kit contains eight basic Visual Voice components. Three of these components are controls:

There are also five valuable support applications you can use to build and manage your TAPI applications:

Note
You'll find a demonstration copy of the Visual Voice Toolkit on the CD-ROM that ships with this book. You can read this section of this chapter without installing the Visual Voice software, but you'll get more out of the material if you have Visual Voice up and running.

There are three Visual Voice controls. The Voice control is the main TAPI interface control. You'll use this control to gain access to TAPI services on your workstation. The Test control can be used to perform tests on your applications without the need for a live telephone line. The VLink control can be used to pass information between running Visual Basic Visual Voice applications.

The following sections review the controls and their methods, properties, and events more closely.

Note
The reviews of the methods, properties, and events of the Visual Voice components covers the OCX controls only. The Visual Voice Toolkit for Win32 also contains DLLs for use with C++ applications (or other programming languages that use DLLs). The descriptions of methods, properties, and events described for the Visual Basic controls are the same for the API calls in the DLL support files.

The Voice Control

The Voice control has 33 methods that you can invoke. Most of them correspond to methods found in the TAPILINE control and specific API functions defined within TAPI. For example, there is an AllocateLine method to open a line for voice output. There are also DeallocateLine and Stop methods for closing a line and shutting down TAPI services (see Figure 31.1).

Figure 31.1 : Viewing the Voice control properties page .

You can use the Voice control to place an outbound call by setting the Value property to "555-1212" and then invoking the Call method. When a call comes in to the line, the RingDetected event fires and you can use the PickUp method to answer the call.

The Voice control has several other unique, and very useful, methods. For example, the Voice control contains several Play... methods that can be used to play back numbers, dates, words, phrases, even complete sound files. There are also properties that identify the caller, including CallerID, ANI (Automatic Number Identification), and others.

Tip
There is also a Visual Basic BAS module called VOICETP.BAS. This module contains constant definitions and sample and helper functions and subroutines. This additional code is not required when using the Voice control, but it does come in quite handy. When you add the Voice control to your project, you should add the VOICETP.BAS module, too.

Table 31.1 lists all of the TAPI-related methods along with short descriptions of their use.

Table 31.1. The Voice control methods.
MethodDescription
AbortTransfer Aborts a transfer previously initiated through the AttendedTransfer method.
AllocateLine Attempts to allocate the phone line specified in the PhoneLine property that will be used for all subsequent Visual Voice actions.
AttendedTransfer Begins an attended transfer or conference to the extension specified in the Value property.
BlindTransfer Blindly transfers the call to the number specified in the Value property and then hangs up.
Call Dials the digits stored in the Value property and returns when call progress detection has completed. The ActionResult property will contain the status of the call.
CheckError Generates an error condition if one has been set by way of the SetError method.
CompleteTransfer Completes a transfer initiated through the AttendedTransfer method and disconnects from the call.
ConferenceTransfer Completes a three-way conference with the calling party and a party called through the AttendedTransfer method.
DeallocateLine Frees an allocated phone line.
Dial Blind-dials the digits stored in the Value property and then returns immediately. This action can also be used to generate other telephony signals, including pulse dialing or a flash-hook.
DisableIODevice Disables the I/O terminal device specified in the Value property. This is used to switch between headsets and desktop phones, and so on.
EnableIODevice Enables the I/O terminal device specified in the Value property. See the preceding description of DisableIODevice.
FlushDigitBuffer Unconditionally retrieves all digits in the digit buffer, places them into the Digits property, and leaves the digit buffer empty.
GetDigits Conditionally retrieves touch-tone digits from the digit buffer and places them into the Digits property. The number of digits retrieved is determined by the inputs to the action.
HangUp Puts the line "on-hook" to conclude a call.
Hold Places the current call on hold.
Park Parks the current call to the phone number specified in the Value property.
PickUp Takes the line "off-hook" to answer a ringing line or get a dial tone.
PlayCharacters Plays the string stored in the Value property as a list of characters (for example, "a, b, c").
PlayDate Plays the string stored in the Value property as a date and/or time in the format stored in the DateFormat property.
PlayFile Plays the voice file named in the Value property.
PlayMoney Plays the number stored in the Value property as money (dollars and cents).
PlayNumber Plays the number stored in the Value property as a number, to the decimal precision stored in the Precision property.
PlayOrdinal Plays the integer stored in the Value property as an ordinal number (1st, 2nd, 3rd, and so on).
PlayString Plays the voice string stored in the Value property. A voice string is a collection of one or more values using various play methods, all played smoothly together. For example, "Order number [54321] was shipped on [Tuesday, October 2]."
PlayStringQ Identical to the PlayString method but returns immediately so database or other processing can occur at the same time.
RecordFile Records a voice file, using the file format specified in the FileFormat property, and saves it with the filename stored in the Value property.
SetError Sets up an error condition so that the next Visual Voice action will return an error. The error number is specified in the Value property.
ShowConfigDialog Displays the TAPI device driver's configuration dialog box.
Stop Stops all Visual Voice activity, including all Play..., RecordFile..., Call, and GetDigits methods. It clears the entire queue of pending voice strings to be played (if any).
SwapHold Swaps the active call, specified in the appearance property, with the call in the Targetappearance property, so that the active call is put on hold and the target call is taken off hold and becomes active.
Unhold Retrieves a call on hold.
Unpark Retrieves a call that has been parked via the Park method.

The Voice control sports 46 TAPI-related properties. Many of these properties are read-only and available only at run-time. Table 31.2 shows the list of properties for the Voice control.

Table 31.2. The Voice control properties.
PropertyDescription
Action Initiates the specified Voice control action. This is a carryover from the 16-bit control and is not recommended. Instead, use the methods described in Table 31.1.
ActionResult Stores status information about the result of the previous action. The default is VV_R_OK.
appearance Specifies the appearance on which subsequent Visual Voice actions will take effect. The default is 0 (for PBX systems).
appearanceName Returns, in an array, the names of the appearances at the current extension, specified in the PhoneLine property. This property is read-only. (PBX)
appearanceTotal Returns the total number of appearances at the current extension, specified in the PhoneLine property. This property is read-only. (PBX)
AutoClearDigits If this property is set to False, the digit buffer will not be cleared before each Play... or RecordFile method is initiated. The default is True.
CallTimeOut Sets the maximum number of seconds to wait for a connection during the Call method. The default value is 20 seconds.
DateFormat Specifies how a date and/or time is spoken when the Play... method is executed. The default is mm/dd/yyyy.
Debug If this property is set to True, the Debug event executes at the start and finish of every Visual Voice action. The default is False.
Digits Contains any touch-tone digits returned by the GetDigits or FlushDigitBuffer methods. This property is read-only. The default is "".
DigitsTimeOut Sets the maximum number of seconds that the GetDigits method will wait for the specified digits before timing out. If this property is set to 0, there is no time-out. The default is 15 seconds.
DtermDigits Specifies one or more touch-tone digits that will terminate the GetDigits method. The default is "#".
EndPosition Returns the current position, in seconds, of the voice file specified in the Value property. This property is read-only.
ErrorLogString Specifies a string to send to the Visual Voice errorlog text file. The default is "". (This is the error message body!)
FileFormat The file format used when recording voice files. The default is the last file format specified at design time, or 0.
FileLength Returns the length, in seconds, of the voice file specified in the Value property.
hCall Returns the TAPI call handle of the current Visual Voice connection. This property is read-only.
hLine Returns the TAPI line handle of the current Visual Voice connection. This property is read-only.
hPhone Returns the TAPI phone handle of the current Visual Voice connection. This property is read-only.
InterDigitTimeOut Specifies the maximum number of seconds the GetDigits method will wait between digits before timing out. The default is 0.
IODeviceName() Returns the names of the I/O devices, if any, attached to terminals on the TAPI device. This property is read-only.
IODeviceTotal Returns the total number of I/O devices attached to terminals on the TAPI device. This property is read-only.
LanguageDLL Specifies the language DLL to use for speaking variable information. The default is VVLUSA16.DLL.
LanguageParams Specifies any optional parameters to change the behavior of custom language DLLs. The default is "".
LinePassThrough Specifies whether every low-level TAPI device event will be exposed through the LinePassThrough event. The default is False.
MaxDigits Specifies the maximum number of digits to receive from the digit buffer before the GetDigits method returns. The default is 1.
PhoneLine Sets the telephone line (port or channel) on which all of Visual Voice's actions will execute. The default is 1.
PhoneLineTotal The total number of telephone lines (ports or channels) available to Visual Voice. This property is read-only.
PhonePassThrough Specifies whether every low-level TAPI device phone event will be exposed through the PhonePassThrough event. The default is False.
Precision The decimal precision to which any number or money value is played. The default is 6, general precision.
ProductInfo Returns a string that contains version information for the Visual Voice for TAPI VBX, Visual Voice TAPI engine DLL, the TAPI API, and the TAPI drivers being used. This property is read-only.
Rate Sets the speed voice files are played by any Play... method. The default is 0.
RecordBeep Specifies whether a beep will be played before the RecordFile method records a voice file. The default is True.
RecordTimeOut Sets the maximum length of any recording created by the RecordFile method. The default is 60 seconds.
Rings Number of incoming rings before the RingDetected event is executed. The default is 1.
StartPosition Specifies the starting position, in seconds, at which subsequent Play... and RecordFile methods will play or record, respectively. The default is 0.
Status Stores a value describing what is occurring over the line at any given time. This property is read-only.
StringItemSeparator Specifies the character to be used to separate items in voice strings. The default is , (comma).
StringTokenSeparator Specifies the character to be used to separate tokens in voice strings. The default is | (vertical bar).
SystemError The SystemError property contains additional information when an internal error occurs. This property is read-only.
SystemVoiceFile Specifies the system file listing the voice files to use for speaking variable information. The default is VVSYSTEM.TXT. This file is the source of the most common words and phrases.
Targetappearance The second appearance that must be specified for the SwapHold and AttendedTransfer methods. The default is 0.
Value Sets the value used for the RecordFile, Dial, Call, or any Play... method. The default is "".
Volume Sets the volume at which voice files are played by any Play... method. The default is 0.
VtermDigits Sets the terminating touch-tone digits that will stop any playing or recording (Play... and RecordFile methods).

Finally, there are eight TAPI-related events for the Voice control. Table 31.3 shows the events, along with descriptions of their use.

Table 31.3. The Voice control events.
EventDescription
CalledIDDetected Triggers after DID (Direct Inward Dialing) or DNIS (Dialed Number ID Service) information is detected on the line. This is used to identify the exact line the caller used to enter your switch (PBX).
LineDropped If the line is idle, this event executes whenever the line drops or the user hangs up.
PlayQueueDone Triggers when all voice strings on the queue have completed playing. Place voice strings on the queue by way of the PlayStringQ method.
CallerIDDetected Triggers after CallerID or ANI (Automatic Number Identification) information is detected on the line.
LinePassThrough If the LinePassThrough property is set to True, this event triggers once for every line event returned by the TAPI device.
RingDetected Executes after the number of rings in the Rings property have been detected on the line. The line must be allocated.
Debug If the Debug property is set to True, this event triggers before every Voice control action starts and after every Voice control action finishes.
PhonePassThrough If the PhonePassThrough property is set to True, this event triggers once for every phone event returned by the TAPI device.

The Test Control

The Test control simulates the existence of a live telephone line for your Visual Voice applications. When you are building and testing telephony applications, one of the hardest parts of the process is testing the application's response to inbound calls. The Test control solves this problem. Now, as you build your TAPI applications, you can test them without having to actually link your workstation to a live telephone line (see Figure 31.2).

Figure 31.2 : Viewing the Test control properties page.

The control works by communicating directly with the Voice control. Whenever the Voice control invokes a Call method, the Test control's VoiceCallInitiated event occurs. This simulates the receipt of an outbound call initiated by your application. You can also use the VoiceConnect method of the Test control to simulate the appearance of an inbound call for your TAPI application.

Tip
When you load the Test control into your Visual Basic projects, load the VVTEST.BAS module, too. This contains predefined constants that you can use to make it easier to program with the Test control.

Table 31.4 shows the four methods of the Test control along with short descriptions of their use.

Table 31.4. Methods of the Test control.
MethodDescription
Disconnect Causes a line-dropped condition in the Voice control. This action simulates the caller hanging up.
SendLineDigits Sends the string of digits specified in the Value property to the Voice control. This action simulates touch-tone digits being sent over the line, as though the digits were pressed on a telephone's keypad.
TimeOut Immediately forces the current Visual Voice action to time out and terminate (if applicable). This action simulates a time-out.
VoiceConnect Connects to the Voice control (if any) that has allocated the phone line. This action simulates a caller calling the Visual Voice application.

Note
There are five other methods listed in the Test control documentation, but they have no effect in the current version of Visual Voice for TAPI. These methods are FaxConnect, HangUpHandset, PickUpHandset, SendCallProgress, and SendHandsetDigits. These methods appear for backward compatibility with earlier versions of Visual Voice.

There are nine valid properties of the Test control. These properties are listed in Table 31.5 along with descriptions of their use.

Table 31.5. The Test control properties.
PropertyDescription
Action Initiates the corresponding Test control action.
CalledID Simulates a CalledID string sent to the Voice control.
CallerID Simulates a CallerID string sent to the Voice control.
NumberDialed Contains the number dialed after the Voice control's Dial or Call methods are initiated.
SoundEffects Specifies whether sound effects are played over the speakers when Test control actions are initiated. The default is True.
Status Indicates the status of the Voice control at any time.
TestRecordingFile Specifies a WAV file that simulates a voice speaking over the phone line when the Voice control's RecordFile method is initiated. The default is "".
Value Specifies the string used for the SendLineDigits method.
tVVEnvironment Returns a value identifying the Visual Voice control with which the test control is working. This property is read-only. Possible values are

VISUAL_VOICE_PRO
VISUAL_VOICE_MWAVE
VISUAL_VOICE_TAPI

Note
There are three properties of the Test control that are no longer valid: FaxPageTotal, TestFaxFile, and TestStationID. These are included for backward compatibility with other versions of Visual Voice, but have no effect in this version of the product.

It is important to comment on the CalledID and CallerID properties-don't confuse them. The CalledID value indicates the telephone number that the inbound caller dialed to reach you. In some PBX systems, this information is used to sort incoming calls for customized greetings (for example, calls coming in on line 1 might be answered "Welcome to Customer Service" and calls coming in on line 2 might be answered "Administration. May I help you?"). The CallerID value indicates the telephone number of the person who is placing the call. This can be used to automatically associate a name, address, or other account information with the calling party.

The Test control has three events. Table 31.6 lists these events along with a description.

Table 31.6. The Test control events.
EventDescription
ElapsedTime Triggers periodically to keep track of how long a phone connection lasts and how long the current voice action has been executing. The counter starts for each VoiceConnect, Dial, or Call method of the Voice control event and is set to zero when the triggering method has completed.
VoiceCallInitiated Triggers whenever the Voice control places a call with the Call method. Place code in this event to specify what type of response (for example, dial tone, busy, and so on) the Voice control will receive.
VoiceDialInitiated Executes when the Voice control dials a number with the Dial method.

Note
There is also a FaxSendInitiated event that is no longer operable, but that is included for backward compatibility.

The Vlink Control

The Vlink control is used to send data between two Visual Basic programs running on the same workstation. This control was developed before Visual Basic 4 offered easy OLE server construction. Although you could accomplish the same tasks using OLE servers, the Vlink control is geared toward supporting Visual Voice services and should be used whenever you need to share telephony data between Visual Voice TAPI applications (see Figure 31.3).

Figure 31.3 : Viewing the Vlink properties page.

Tip
When you use the Vlink control, add the VLINK.BAS and VLVOICE.BAS modules to your project. These modules contain useful constants and helper functions that you can use to manipulate Vlink control events and data.

The Vlink control has only two methods. Table 31.7 lists and describes the methods.

Table 31.7. The methods of the Vlink control.
MethodDescription
Request Sends the contents of the SendData() property array to the node specified in the SendToNode property. This action waits for the target node to complete processing (and optionally return data) before returning.
Send Sends the contents of the SendData() property array to the node specified in the SendToNode property, and returns immediately.

The Vlink control has 14 TAPI-related properties. Table 31.8 lists these properties and describes them.

Table 31.8. The properties of the Vlink control.
PropertyDescription
Action Initiates the specified Visual Link action.
ClearSendData Specifies whether the SendData() property array and the SendDataTotal property will be cleared after a Send or Request method is complete. Default is True.
Debug If this property is set to True, the Debug event executes at the start and finish of every Vlink control action. The default is False.
NodeDescription A string that describes the node. The default is null.
NodeDescriptionList Returns the descriptions of all active nodes.
NodeName Specifies the name of the node.
NodeNameList Returns a list of node names for all active nodes.
NodeTotal Returns the total number of active nodes in the system.
ReceivedData Returns an array of strings sent from another node.
ReceivedDataTotal Returns the number of items in the ReceivedData() property array when another node sends or returns data. This property is read-only.
SendData Specifies an array of strings to send to another node.
SendDataTotal Specifies the number of elements in the SendData() property array to send during a Send or Request method or when returning data in a RequestReceived event.
SendSubject Specifies the subject of the data being sent.
SendToNode Specifies which node will be the target of any subsequent Send or Request method.

There are three events defined for the Vlink control. Table 31.9 shows the three events and their meaning.

Table 31.9. The events of the Vlink control.
EventDescription
DataReceived This event is triggered when another node has sent data by way of the Send method and the data is now available at this node.
Debug If the Debug property is set to True, this event is triggered before every Visual Link action starts and after every Visual Link action finishes.
RequestReceived This event is triggered when another node has sent a request by way of the Request method.

That completes the tour of the Visual Voice controls. Next you'll learn about the various support programs and development tools that are supplied with the Visual Voice Telephony TAPI Toolkit for Win32.

The Voice Workbench

The Voice Workbench is an essential tool for building Visual Voice TAPI applications. The Workbench allows you to create and maintain four key Visual Voice objects:

Voice files are the actual WAV format recordings of human speech. The Voice Workbench allows you to record and catalog voice files for later reference in your Visual Basic project. Typical voice file objects would be "Welcome to Visual Voice," or "Press one to continue," and so on. Figure 31.4 shows the Voice Workbench while reviewing a set of voice files.

Figure 31.4 : Reviewing voice files with the Voice Workbench .

Voice strings are a collection of one or more voice files plus literal or variable values. The Workbench lets you link several prerecorded phrases along with fixed or variable data retrieved from a database or computed by your Visual Basic program. For example, you might create a voice string object that returns the total number of messages in your voice-mail inbox:

"There are" MsgTable[MsgCount] "new messages"

The phrase above links two voice files (possibly named ThereAre.WAV and NewMsgs.WAV) with a pointer to a field (MsgCount) in a database table (MsgTable). This is one of the most powerful aspects of the Workbench. You can very easily link your voice output to variables in your program or to data stored in a shared database. Figure 31.5 shows the Workbench building a voice string using a database link.

Figure 31.5 : Building a voice string using Voice Workbench .

You can also build and maintain voice query objects with the Voice Workbench. Voice queries are just like voice strings except that they ask the user for a predetermined response in the form of keypad selections. You can build your queries to expect a set amount of input before continuing with your TAPI application. Figure 31.6 shows the Workbench editing an existing voice query.

Figure 31.6 : Generating Visual Basic code using a Workbench template.

Lastly, the Workbench also lets you create and store your own subroutine templates. These templates can link voice strings, voice queries, and pure Visual Basic code into a single unit. Once the template is completed, you can ask the Workbench to generate Visual Basic code for you to place into your application. In this way you can build complex telephony logic without spending a great deal of time writing Visual Basic code. Figure 31.7 shows an example of Workbench-generated code using a Visual Voice template object.

Figure 31.7 : Generating Visual Basic code using a Workbench template .

The Voice Monitor

The Voice Monitor is a Visual Basic application that can monitor activity on multiline phone installations (see Figure 31.8).

Figure31.8 : Using Voice Monitor to track line activity .

This is very useful when you have a multiline telephony card in your TAPI workstation and are running one or more Visual Basic applications on each line.

The Virtual Phone

The Virtual Phone is a very handy testing tool. This tool simulates the appearance of a live telephone line for your Visual Voice applications (see Figure 31.9).

Figure 31.9 : Running the Virtual Phone .

The program is actually written in Visual Basic using Visual Voice's Test control, and the source code is included in the complete toolkit. The program works by talking directly to the Voice control rather than to a telephone line. For this reason, you cannot use the Virtual Phone for any other TAPI applications that do not use the Voice control.

You can set values for the CallerID and CalledID in the Virtual Phone and have these values passed into your Visual Basic application that uses the Voice control. In this way you can even test applications that require advanced telephony service features without having to use a live telephone line.

The TAPI Examiner and the Stylus Trace Applications

The TAPI Examiner is an excellent tool for testing your hardware's compatibility with TAPI services. The examiner runs through all the major service requests, including selecting and opening lines, placing outbound calls, receiving inbound calls, even testing advanced features such as transfer, park, and hold (see Figure 31.10).

Figure 31.10 : Using the TAPI Examiner

You also get the ability to log your test results to a text file for later reference. This is a very handy tool for testing new workstations and is a useful general diagnostic tool as well.

The Stylus Trace application provides an easy way to log and trace all activity involving Stylus controls. Listing 31.1 shows a sample of trace output.


Listing 31.1. Sample output from the Stylus Trace application.
Executing VV_VoiceInit
VVE ?: TAPI initialized 6 lines, 6 phones
VV_VoiceInit returned 0x00000000
VVE ?: 1 line license detected
Using profile C:\WINDOWS\VVOICETP.INI
Executing VV_SetSystemFileExtension(wav)
VV_SetSystemFileExtension returned 1
Executing VV_SetBeepFileName(C:\VVOICETP\TESTSNDS\BEEP.WAV, 0)
VV_SetBeepFileName returned 1
Executing VV_AllocateLine(PhoneLine = 1 Rings = 1)
VVE ?: Mapping VV PhoneLine 1 to TAPI device 5 [Windows Telephony Service Provider for Universal Modem Driver - TeleCommander 2500 Voice]
VVE ?: line 5 - total appearances = 1
VVE 5: appearance 0: [´]
VVE ?: lineOpen (OWNER, AUTOMATEDVOICE)
VVE ?: Allocated line ed0084. Line handle = 372f1e3e
VV_AllocateLine returned 0
Allocated line 1. 1 appearances

Note
Since this product works by monitoring activity within the Stylus components, not within the Windows Telephony API, you cannot use the Stylus Trace to monitor non-Visual Voice telephony programs.

Pronexus' VBVoice Development Kit

The Pronexus VBVoice telephony development system is quite different from the Visual Voice toolkit. Each provides the same basic services, but in a very different way. While the Visual Voice toolkit emphasizes the use of custom controls linked together with Visual Basic code, the VBVoice system emphasizes the use of visual programming instead of Visual Basic code. In fact, you can build an entire VBVoice application without writing any Visual Basic code at all.

The VBVoice system is made up of 20 different OCX controls. These 20 controls represent all the major actions that can occur during a telephony session. You place these controls on your Visual Basic form and set their properties at design time. You then link them together in a call-flow diagram that visually defines your program.

After completing your call-flow diagram and setting the desired properties, you can test your VBVoice application by starting the application in TestMode. TestMode is similar to the Visual Voice Virtual Phone. VBVoice TestMode simulates call activity without the use of a live telephone line.

In the next few sections, you'll learn how the VBVoice controls work and how they can be used to develop Windows telephony programs.

Note
There is a demonstration version of the VBVoice development system on the CD-ROM that accompanies this book. You do not need a telephony card to use the demonstration version of the system. However, you do need a sound card to run the system in TestMode.

The VBFrame Control

Every VBVoice project contains at least one VBFrame control. This control is the "host" control for all other VBVoice controls in the project. The VBFrame acts as a visual workspace for your telephony project. Figure 31.11 shows a VBFrame control hosting several other VBVoice controls.

Figure 31.11 : Using VBFrame to host other VBVoice controls

The VBVoice Controls

After you have placed a VBFrame control on a form, you are ready to add other VBVoice controls. Each VBVoice control handles a single typical event in a telephony application (playing a greeting, collecting digits, transferring a call, and so on). Along with the VBFrame control, there are another 19 VBVoice controls that you can use to build your telephony applications. Table 31.10 lists and describes the 19 VBVoice controls.

Table 31.10. The VBVoice controls.
ControlDescription
Conference The Conference control is used for merging individual voice lines together into a conference. This control is available as an option with VBVoice. Callers in a conference have the ability to verbally communicate to all other callers in the conference. Each instance of this control represents one unique conference.
Count This control maintains an internal counter which can be reset and incremented by call flow. It is useful for simple loops similar to the Visual Basic for .. to .. step .. construct.
DataChange Changes one or more fields in a database record. The database and record to be changed are selected by a previous DataFind control. The field values of the record in the database selected by the DataFind control will be changed to the new values. If Add New Record is set, a new record is added and the fields in that record updated instead. The data to be inserted can contain control names.
DataFind This control can select a record from a database for input validation and for subsequent data selection and update operations by DataSwitch, DataChange, and Dial controls.
DataSwitch When a call enters the DataSwitch control, the control reads a field from the database record found by a previous DataFind control and stores the result in the Result property. The call is then passed to the control connected to one of the output nodes, based on a comparison operation performed on the field value obtained.
Delay Implements a wait period. A Delay control can be used if your VB code has to perform a lengthy activity, and you want the caller to wait until it is complete, for instance to wait for a busy line to be free before re-attempting a transfer.
Dial The Dial control can be used to go off-hook and start a call, or, on an existing call, it can perform a transfer to another extension or dial some digits to an automated system at the far end. If the number to dial is prefixed with the letter "S," call supervision is enabled to monitor the progress of the call until the result is determined-one of the outcomes listed in the Supervised Dial box. It does this by listening and analyzing the tones being returned from the telephone system after dialing. A built-in call-logging facility using a database is also provided.
GetDigits The GetDigits control plays a greeting and waits for digits from the caller for a predetermined amount of time. Pattern matching is performed on the collected digits using as many exit conditions as required. GetDigits provides built-in invalid digit and time-out handling.
InConn Used for connection from an output on one control to the input of another on a different form. Other controls cannot be connected across forms.
IniSwitch Searches for an entry in a Windows initialization (.INI) file, and routes the call depending on the result found. You can set the filename, section name, and field name of the entry you wish to test. The Result property is set from the data found.
Language The Language control is an optional control that performs several functions, including setting the language for each call using the graphical controls; overriding default phrase concatenation rules for the built-in system phrases with your own rules; and accepting a user-definable system phrase type.
LineGroup This control "owns" a group of telephone lines, and can receive calls and initiate calls on these lines. The channels can be set using the property page at design time, or channels can be allocated at run-time by way of the AddChannel and RemoveChannel methods. LineGroup also contains handlers for global conditions on a channel: invalid and silence time-outs, call termination due to maximum call time or by the StopCall function, and global digit handlers.
Onhook Plays a greeting, and hangs up the phone. Control of the line is returned to the LineGroup control that owns this channel, where a Disconnect event will occur. This event will allow termination code to run for this call.
OutConn Used for connection from an output on one control to the input of another on a different form. Other controls cannot be connected across forms.
PlayGreeting The PlayGreeting control plays a greeting and then passes the call to the next control. If the greeting plays to completion without any digits, the call will exit out of the Done node. The PlayGreeting control can also accept digits from the caller to pause, skip forward and backward in the greeting, or change the volume and speed of the playback. The volume and speed adjustments are reset to the default on entry and exit of the control.
PlayMsgs Two types of messages are supported: New and Old. New messages are those that have not yet been heard, or have been saved as New. New messages are converted to Old once they have been heard. When a call enters a PlayMsgs control, the control first plays the number of each type of message. (configurable in the EntryGreeting). It then plays the messages in sequence, starting with the new messages (oldest messages first), using the configurable MsgGreeting. The action after each message is configurable to either start playing the next message immediately, or to play the OptionsGreeting, allowing the caller to save, delete, forward, or skip the message, or exit. After both new and old messages have been played, the call exits the control.
Record Records a wave file into the filename specified by either creating a new file or appending an existing one. Each message can be stored in a unique file name generated by the control. An options menu is provided to provide message review, re-record, and deletion.
TimeSwitch Transfers the call to another control according to time of day and day of week. Several time zones can be set for each control. If the current time and day of week do not match any of the fields specified, the call continues by way of the default connection.
User This control has no predetermined action. It allows Visual Basic to define all operations and provides complete control over the voice card.

The Process of Building a VBVoice Application

As mentioned earlier, you build VBVoice telephony applications by placing the various VBVoice controls into a VBFrame and then linking them together in a call diagram. Once they are linked together, you can set the properties of each control to alter the behavior of the system. Figure 31.12 shows the process of setting properties for the GetDigits control.

Figure 31.12 : Setting the properties of the GetDigits control.

VBVoice and Voice Files

VBVoice allows you to build voice files using its own library of phrases or by recording your own phrases. You access the voice files through the VBVoice controls that use voice files. For example, you can call up the properties page of the PlayGreeting control, select Properties from the context menu (alternate mouse button), and then select the Greetings tab to gain access to the recorded voice library (see Figure 13.13).

Figure 31.13 : Accessing the Voice library files

VBVoice allows you to record, playback, and store messages in a variety of file formats including the Windows standard WAV format.

VBVoice Test Mode

Once you have built your VBVoice project, you can test it by selecting the Start Test option from the context menu (alternate mouse button) of the control. All VBVoice controls can be started in this way. This makes it very easy to debug a telephony application. You can start your testing from anywhere in the call flow.

Once you start your application, you'll see a small dialog box appear asking you to start the test mode. While test mode is running, you'll also see a log window of all activity in the VBVoice application (see Figure 31.14).

Figure 31.14 : Running a VBVoice application in test mode

You can view the trace logs onscreen, send them to a printer, or save them to a disk file. Listing 31.2 shows sample output from a VBVoice log.


Listing 31.2. Sample output from a VBVoice log.
10:49:39-> Test Call
10:49:39-> Test Call Setup

10:49:39-> 'PhoneAns' (LineGroup)
10:49:40-> Call In 10:50:16-> call complete
10:49:40-> 'PhoneAns' (Linegroup) 10:49:40-> exit via node 1 <'Ring'> value ''
10:49:40-> exit via node 1 <'Ring'> value ''
10:49:41-> 'PlayGreet' (PlayGreeting) 10:49:47-> exit via node 0 <Played>
playing 'Entry' greeting
10:49:47-> exit via node 0 <Played>
10:49:47-> 'GetCustInfo' (GetDigits) 10:49:50-> exit via node 0 <'Company Info
info dtmf termination mask 1006 max keys 1 sil time 3
playing 'Entry' greeting
waiting for digits, max 1, mask 1006
10:49:50-> exit via node 0 <'Company Info - 1'> value '1'
10:49:50-> 'PlayInfo1' (PlayGreeting) 10:49:59-> exit via node 0 <Played>
playing 'Entry' greeting
10:49:59-> exit via node 0 <Played>
10:49:59-> 'GetCustInfo' (GetDigits) 10:50:02-> exit via node 2 <'Cust. Support
playing 'Entry' greeting
waiting for digits, max 1, mask 1006
10:50:02-> exit via node 2 <'Cust. Support - 2'> value '2'
10:50:02-> 'PlayInfo2' (PlayGreeting) 10:50:14-> exit via node 0 <Played>
playing 'Entry' greeting
10:50:14-> exit via node 0 <Played>
10:50:14-> 'GetCustInfo' (GetDigits) 10:50:15-> exit via node 1 <'Exit - #'> va
playing 'Entry' greeting
waiting for digits, max 1, mask 1006
10:50:15-> exit via node 1 <'Exit - #'> value '#'
10:50:15-> 'Onhook1' (OnHook) 10:50:16-> transfer to linegroup control (onhook)
playing 'Entry' greeting
10:50:16-> transfer to linegroup control (onhook)

Even though you can build complete telephony applications using only the VBFrame control and the visual call diagrams, you can also use the controls to build programs using traditional Visual Basic coding techniques. Each control has its own series of events, methods, and properties that can be accessed at run-time. You can read and set properties, invoke methods, and add code to the events just as you do with any other Visual Basic controls.

Microsoft Phone

Microsoft Phone is the first application released by Microsoft that combines the Messaging, Telephony, and Speech APIs into a single program (see Figure 31.15).

Figure 31.15 : Starting Microsoft Phone

While Microsoft Phone is a very good pc phone and answering machine, it offers several other valuable features. First, you can use Microsoft Phone to designate several fax mailboxes. These mailboxes will send a selected fax back to the caller based on a telephone number left by the caller. You can also set up multiple message boxes that the caller can use to leave messages. Finally, you can build announcement-only mailboxes that can give the caller valuable information such as office hours, delivery directions, and so on.

The best part of all this is that you can link these three types of mailbox objects into a set of menu-driven options that provide callers with a full-featured auto-attendant system. All without writing a single line of code!

Note
As of this writing, Microsoft Phone is not available as a stand-alone product. Microsoft Phone is to be included as the default telephony application for several voice-data modem products sold in stores. You cannot get a copy of Microsoft Phone unless you buy the voice-data modem hardware. The list of hardware vendors committed to shipping Microsoft Phone is constantly changing. To get the latest information, check the TAPI vendors list in appendix C, "TAPI Resources." You can also check the Communications Developer's Guide Web site for more information on MAPI, SAPI, and TAPI tools.

Microsoft Phone can answer your telephone for you, record incoming messages, and send these recorded messages to your Microsoft Exchange inbox for your review at another time. You can call into Microsoft Phone from a remote location and have the program play your e-mail messages back to you. You can even ask Microsoft Phone to "read" your text e-mail to you over the phone!

You can also use Microsoft Phone to place outbound calls. You can dial calls directly using the Microsoft Phone keypad, you can use one of the speed dial buttons, or you can call up the Microsoft Exchange address book and select a user's phone number from the address book. Microsoft Phone even checks incoming caller ID information against your Exchange address book to see if you already have that person on file.

When you first install Microsoft Phone, you can configure it to record messages and place them in your Exchange mailbox. This is done using the Greeting Wizard (see Figure 31.16).

Figure 31.16 : Using the Microsoft Phone Greeting Wizard.

Adding Announcement, Message, and AutoFax Mailboxes

Microsoft Phone allows users to add several different mailboxes to handle incoming calls. Microsoft Phone recognizes three types of mailboxes:

You can set up your Microsoft Phone application to accept an incoming call, play a general message, and then allow the user to navigate between announcement, message, and fax mailboxes using his telephone keypad (see Figure 31.17).

Figure 31.17 : Building addtional Microsoft Phone mailboxes.

Each message-type mailbox can be associated with a Microsoft Exchange mailbox. All messages sent to this Microsoft Phone mailbox will be delivered to the Microsoft Exchange box, too.

Each announcement-type mailbox can give the caller a complete message (for example, directions to the retail location, office hours, and so on) or can give the caller instructions on how to select a message box or receive a fax document.

Each AutoFax-type mailbox can send one (and only one) selected document to the user. The AutoFax box will ask the user for a telephone number as a destination address for the document and then send the document when the line is free.

Configuring the Microsoft Phone Answering Machine

Once you install all the mailboxes, greetings, and fax documents you need, you can configure the answering machine parameters (see Figure 31.18).

Figure 31.18 : Configuring Microsoft Phone.

You can set parameters for several related groups of data:

Summary

In this chapter you got a chance to review three tools that can help you develop end-user TAPI applications: