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 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 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.
Method | Description |
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.
Property | Description |
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.
Event | Description |
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 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.
Method | Description |
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.
Property | Description |
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 |
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.
Event | Description |
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 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.
Method | Description |
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.
Property | Description |
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.
Event | Description |
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 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 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 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 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. |
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. |
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
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.
Control | Description |
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. |
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 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.
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 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.
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.
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:
In this chapter you got a chance to review three tools that can help you develop end-user TAPI applications: