Telephony is a technology that allows your computer to work directly with the telephone network. The Windows Telephony Application Programming Interface (TAPI) allows you, the programmer, to easily develop applications that provide telephony services to
Microsoft Windows users.
To encompass all of the capabilities of telephony, TAPI supports speech and data transmission as well as a variety of terminal devices, complex connection types, conference calls, call waiting, and voice mail. Because TAPI isolates applications from the
morass of operations required on the telephone network, you can easily develop network-independent applications. For the user, the API is hardware/connection-independent, thus allowing configuration to be very flexible.
This chapter explores a wide range of functionality available to business users and developers through the integration of the desktop computer with the telephone. Understanding telephony under Windows is important because the availability of Windows
Telephony support will soon become a key factor in the selection of telephony hardware. By using Visual Basic, you will learn how to use TAPI to explore Windows Telephony for new applications that will improve services and productivity.
The advantages of using TAPI are as follows:
With many of the existing telephone connections in the world, the Plain Old Telephone Service (POTS) handles the connection and transmission of voice and data while in the local portion of a phone system. This local portion, or loop, exists between the
user's telephone and the central office (CO). Within this loop, voice is transmitted in analog format and a modem must convert the digital computer data to analog. Digital networks are gradually replacing analog in the local loop to conform with the
existing digital connections between the different COs (see Figure 26.1).
Figure 26.1. Central offices connect your telephone to the larger telephone system for communications with other telephone users.
TAPI provides a means of application development that supports POTS and other communications mediums. Using TAPI for communications over POTS is straightforward because POTS is a simple technology. Other mediums for communications supported by TAPI
allow you to take advantage of advanced types of data transmission. One such medium is called ISDN (Integrated Services Digital Network), which is expected to grow significantly in availability over the next few years.
Tip
ISDN has the following advantages over POTS:
In addition to ISDN, you can use TAPI to develop applications that utilize the services of T1/E1 and Switched 56. Switched 56 provides 56 Kbps throughput over dial-up telephone lines and is becoming available throughout the U.S. and in many other
countries. This medium requires special equipment, and though its connection capabilities are limited to calls to other specially equipped facilities, its high speed and low pricing make it a good choice for data communications. T1/E1 service is similar to
Switched 56 in that it is a digital transmission medium; however, it runs at much higher speeds in the range of 1.5 Mbps (megabytes per second). T1/E1 service is provided generally as dedicated lines over which digital data is transmitted (see Figure
26.2).
Figure 26.2. TAPI allows transparent, medium-independent communications over analog POTS as well as any of the existing digital networks available.
Switched 56 and T1/E1 are data-only services and are transparent to TAPI-enabled applications. Applications use standard methods for placing calls and let the service provider handle the transfer of the phone number to the telephone network. To the
application, the Switched 56 line appears as a channel that supports digital service at the 56 Kbps rate because the medium over which calls are made only carries digital data.
In addition to standard POTS and digital services, you can use TAPI with services such as CENTREX, which provides for centralized network services, such as conferencing, without requiring specialized communications equipment. You also can use TAPI with
digital Private Branch Exchanges (PBXs), which provide communications for small areas, such as office buildings or organizations. Because TAPI is network-independent, development of a PBX application is the same as that of a POTS application, which means
you can use an application that was developed for POTS within a PBX environment without any code changes.
The emergence of local-area networks (LANs) expanded the role of the desktop computer from just a personal productivity tool to a means of sharing information and resources within workgroups and departments. With LANs came e-mail, which made the desktop
computer an important business communications medium.
The next logical step in the expansion of desktop computers is to integrate them with the telephone. To make this step, Intel, Microsoft, and several major telecommunications, PC, and software companies created TAPI. This API brings the function of the
telephone to the desktop computer and, with the availability of cellular telephone technology, provides a means of implementing the portable office.
Everyone involved with the telephony and computing industries will benefit from the widespread distribution and use of TAPI. Application developers will have access to a standard API, which provides telephony network and hardware independence on the
most popular operating system platform. Developers can now focus on the end product, not the intricacies of low-level communications, and need not be concerned with being tied to a particular hardware platform. Telephony network, switch, and hardware
vendors can focus on the area of their expertise, hardware, and switching without having to come up to speed on Windows application development. With TAPI, third parties can develop a full range of applications, thus expanding the market for telephony
hardware for PC platforms and PCs with integrated telephony capabilities.
End users, the main targets of any development, will benefit because their investments in software and telephony hardware are protected by the interchangeability of components. Competition in telephony application software means that a wide variety of
programs will be available at competitive prices, and commercial developers will continue to create new features in order to meet growing user needs.
The idea of integrating communications and data is to make things more efficient for the end user. With TAPI, users can efficiently manage their voice calls and control their data-transfer operations. The following are just some of the possibilities:
Tip
Note
Of course, TAPI is not the first telephony application programming interface in the industry. In developing TAPI, its creators tried to address some of the issues raised by other similar applications. These issues include the following:
In contrast to previous telephony APIs, TAPI provides the basis for the widespread integration of telephony and personal computers by including the following characteristics:
TAPI's standard application programming interface enables users and application developers to take advantage of the many capabilities and services of the underlying network without having to worry about how that network is structured. TAPI allows
application programs to control telephony functions such as establishing, answering, and terminating a call. The API also allows applications to take advantage of supplementary functions, such as hold, transfer, conference, and call park, found in PBXs and
other phone systems. In addition to standard telephone functionality, the API provides access to features specific to certain telephone systems and can accommodate future telephony features and networks as they become available.
In conjunction with its network independence, TAPI also functions independently of the connection method used between the computer and the telephone. This independence provides maximum flexibility in the integration of the PC with the telephone system.
For example, you can connect a PC to the telephone network, as shown in Figure 26.3, to provide a means of directly communicating over the telephone network or to act as a call center for third-party call routing.
Figure 26.3. TAPI allows you to connect a PC directly to a telephone network to act as a call center controller to handle third-party call routing.
You can also connect the PC through a programmable telephone handset, as shown in Figure 26.4, in order to utilize the services of the phone to connect to the telephone network. Such phones may contain the capability of allowing you to record memos on
the answering device incorporated in the handset body, for example. Applications that control such devices communicate with them using the phone functions that allow you to set the switchhook, control ringing, control volume, and so forth directly in the
phone device itself.
Figure 26.4. TAPI allows you to connect a PC directly to a telephone to use the services of the telephone network.
Multiple PCs can also share telephony resources through a LAN-based voice server, as shown in Figure 26.5, in order to maximize the use of telephony and existing network resources. This voice server distributes data to appropriate PCs from the telephone
network. Device sharing for voice digitizers, fax machines, and data modems is also available if such devices are installed on the server.
Finally, you can connect a server through a telephone network switch, as shown in Figure 26.6, as another method of resource sharing and call routing. In this model, multiple PCs are connected to the server to access information retrieved from the
telephone network. TAPI operations invoked at any of the client computers are forwarded over the LAN to the host, which uses a third-party switch-to-host link protocol to implement the client's call-control requests. The switch provides the interface to
the telephone network, and the LAN server provides the interface for all the PC client operations.
Figure 26.5. TAPI allows you to use your PC as a voice server to answer incoming voice calls.
Figure 26.6. TAPI allows you to connect a PC as a server across the telephone network.
Each implementation may require a different connection model in order to take advantage of the different capabilities. For example, conferencing applications require a connection such as the one shown in either Figure 26.3 or Figure 26.5 in order for
the PC to gain access to the information transmitted over the phone line. In this way, TAPI can access and distribute the information to all connecting devices.
To provide seamless integration into the Microsoft Windows operating system, the Windows Telephony API was incorporated as part of the Windows Open Services Architecture (WOSA). This architecture provides a single set of interfaces to implement
computing services that are accessed through Windows APIs. As a full enterprise-oriented implementation, WOSA includes services for data access, messaging, software licensing, connectivity, and financial services.
The WOSA model provides an abstraction layer to computing resources as a back-end for the front-end application. The front-end application accesses the services of the primary API while the back-end service accesses the computing resources.
Services such as the Windows Telephony API consist of two interfaces. The primary interface is the developer API that allows you to develop applications that utilize the services of TAPI. The second interface is an abstraction layer known as a service
provider interface (SPI). The SPI is used to establish the connection and communicate with a specific telephone network. TAPI supplies a Telephony DLL component, called TAPI.DLL, which resides between the Telephony API and the Telephony SPI. TAPI-compliant
applications call TAPI functions managed by TAPI.DLL, which in turn route the calls to the appropriate service provider for execution. Figure 26.7 shows the relationship between the Windows Telephony API (TAPI) and the Windows Telephony SPI (TSPI).
Figure 26.7. TAPI seamlessly integrates Windows applications and available telephone networks. The architecture allows you to access a generic API that uses the service provider interface for communications
over a specific network.
Multiple TAPI-enabled applications can operate simultaneously to use one or more service providers. In addition, multiple service providers can be used, as long as they access different hardware devices. When the service provider is installed, you can
specify the mapping between each service provider and its hardware using the Windows Telephony Control Panel applet. Some service providers may contain a device-driver component, but, in general, service providers are separate and above the drivers, as
shown in Figure 26.7.
The functional interfaces for the TAPI and the service providers combine to provide a generic view of the underlying telephone networks to all TAPI-enabled applications. This generic view is known as virtualizing the environment for both applications
and service providers. TAPI-enabled applications can send requests to what appears to be a single large service provider that supports a wide selection of devices. In reality, the service provider can be multiple service providers that provide different
types of services.
When multiple service providers interact with a single application, each service provider is only aware of its own interactions with an application. TAPI.DLL hides the interactions that occur between an application and other service providers, which
makes each service provider think it is the only service provider in the system. TAPI.DLL also hides the interactions between applications and service providers from other applications, which makes each application think that it is the sole user of the
system.
In Figure 26.8, TAPI.DLL resides as the interface between applications and the Telephony infrastructure. TAPI.DLL handles all transactions that occur with regard to requests and incoming events between applications and service providers.
Figure 26.8. The TAPI architecture.
The solid arrows in the figure show that several different applications can use a device controlled by one service provider at the same time. TAPI.DLL allows both applications to open the device without concern for contention. These applications can
also elect to become aware of one another if necessary so that they can cooperate and communicate with one another through TAPI.DLL. The service providers are not concerned with communication between multiple applications because they think only one
application is using their services.
The dashed arrows in Figure 26.8 show that multiple service providers can interact with the same application. Each service provider only interacts with TAPI.DLL so that TAPI.DLL can merge the event streams from both service providers into a single
stream for the application. Service providers do not need to be concerned about the details of cooperating with one another or even the existence of other service providers.
To simplify the underlying network, the TAPI programming model abstracts heterogeneous real-world objects such as telephones, modems, and telephone lines into device classes. Device classes allow developers to present devices as a uniform set that TAPI
can access in a consistent manner. The abstraction of devices into classes also increases the longevity of TAPI by providing a framework of device classes that can support future equipment.
TSPI defines two device classes for device abstraction—the line device class and the phone device class. A line device is any device that appears as a telephone network to TSPI, and a phone device is any device that appears as a telephone to TSPI.
TSPI defines a collection of functions and messages for each of these device classes and manages the mapping of this abstraction layer into the real-world device.
In addition to the line and phone device classes, Telephony includes call objects. Line and phone objects are statically defined, but call objects are dynamically created based on call activities. A call object represents an actual communication
instance or call as the endpoint of a connection to one or more remote parties. A call object is bound to a line and is created as required for outbound or inbound calls (see Figure 26.9).
Figure 26.9. Call objects are instances of inbound or outbound calls connected to a line or phone.
Service levels provide different kinds of access to TAPI. Figure 26.10 gives you a idea of how the three available service levels, basic, supplementary, and extended, overlap.
Figure 26.10. Telephony service levels provide different types of functionality for TAPI-enabled applications.
The elementary level of service is called Basic Telephony; it provides the minimum set of functions for POTS. Because all service providers support the basic Telephony functionality, applications that access this service level will work with any TAPI
service provider. You use Basic Telephony for simple access to a telephone network. If you plan on writing PBX phone systems or ISDN connectivity solutions, you need to look at the Supplementary Telephony service level.
Note
Supplementary Telephony services are the services defined by the API above Basic Telephony. These services include features found on modern PBXs, such as hold, transfer, conference, and park. Applications can access a device using TAPI for the set of
supplementary services provided. Service providers provide a Supplementary Telephony service only if it can implement the function as defined by TAPI; otherwise, the feature is provided as an Extended Telephony service.
The third service level is called Extended Telephony, and it provides special purpose API extensions for access to service provider functions not defined by TAPI. Extended services include all extensions to the API defined by a particular service
provider. TAPI's extension mechanism allows service-provider vendors to define new values for some data types and bit flags and to add fields to most data structures. TAPI interprets these extensions by using the service provider's Extension ID. The
Extension ID identifies the set of supported extensions; these extensions may cross several manufacturers.
A TAPI address is the complete telephone number of a telephone, fax machine, or other device that can receive calls. These addresses are assigned to a TAPI-controlled line in the setup operation for a service provider. In the simplest scenario, each
line has only one address. However, it's not unusual for a line to have several addresses as with ISDN (see Figure 26.11).
Figure 26.11. Line addressing allows identification of line devices for TAPI.
Telephony-enabled applications use Telephony services as a first-party call control model. This model requires that service providers allow applications to control telephone calls as the initiator or the recipient of a call. Following this model,
applications can make calls to an address, be notified about inbound calls from an address, answer inbound calls, invoke switch features such as hold, transfer, conference, pickup, and park, and can detect and generate DTMF (Dual Tone Multiple Frequency)
tones for signaling remote equipment (see Figure 26.12).
Figure 26.12. TAPI uses the first-party call control model for establishing calls.
Note
The format of the phone number used to initiate a call depends on where the call comes from. To make calls from a portable computer, you can use a single address book, even when calling from different locations or telephony environments. Corporations
can keep master address books available to all employees even though they might be in different area codes because TAPI's address translation capabilities determine how to contact a specific number based on the current location designated by the user. TAPI
handles the dialing differences of different phone regions without requiring changes to the user's address book. The Windows Telephony applet in the Windows Control Panel manages all of the information regarding location and address translation. This
applet can also manage telephone calling card information and dialing procedures.
TAPI provides control for the media mode of line and phone devices only and does not have support for handling the actual data transferred in a call. To handle this data, known as a media stream, you must incorporate functions from other APIs into
telephony applications. To perform the information management operations, TAPI works in conjunction with other Windows-based services such as the Media Control Interface (MCI) or other data APIs. This division of control enables TAPI to work with existing
audio or data applications (see Figure 26.13).
Figure 26.13. TAPI works in conjunction with other APIs to manage the data transferred in a media stream.
To determine the type of media stream, the Telephony SPI defines a function that allows the caller to retrieve the appropriate media device to be opened and used through the associated media API. For example, for line devices, TAPI.DLL uses the
Telephony SPI to establish a connection to another station. Once the connection is established, TAPI.DLL can retrieve the MCI device associated with the call device and can then use the MCI device to play back and record audio data over the connection.
Similarly, if the media stream is from a fax or data modem, the TAPI client would retrieve a fax or data modem device associated with the call and then use a fax API or a data modem API to manage the media stream.
To properly manage media stream types, the Telephony SPI reports media stream type changes to TAPI.DLL. This process is referred to as call classification. To determine the type of media stream, a service provider may filter the media stream for energy
or tones that characterize the media type. Alternatively, the service provider may determine the media type by using information exchanged in messages over the network, such as the use of distinctive ringing, the caller's identification number, or the
identification number of the party being called.
To minimize the work involved in managing TAPI-enabled applications, Assisted Telephony provides an easy-to-use mechanism for making phone calls without requiring the developer to become a telephony expert. The remainder of this chapter explains how to
access TAPI resources from Visual Basic applications using Assisted Telephony.
Figure 26.14 illustrates the way an Assisted Telephony application, a call manager, and a Full Telephony application relate to TAPI.DLL and the service provider. As you will notice, Assisted Telephony applications require a call manager because they
cannot directly control calls. Once the call manager has established the connection, the call manager turns control of the connection over to the original application. In the case of a Full Telephony application, the application has total control over call
requests and connection management and does not require intervention by an intermediate call manager.
Figure 26.14. Full telephony applications directly manage the media stream while assisted telephony applications require an intermediate call manager.
An example of how you can use Assisted Telephony is the integration of a spreadsheet application with an online database service. The spreadsheet application could contain a button or menu selection that would contact the online service and download
information from a stock quote service into the cells of the spreadsheet. Using Assisted Telephony, the spreadsheet application passes the phone number to the call manager, which in turn places the call to the stock quote service (see Figure 26.15).
Figure 26.15. Using Assisted Telephony, a spreadsheet application can call an online service and download information.
Assisted Telephony is responsible for establishing the line and, via the call manager, completing the call. The call manager then sends a return code to the spreadsheet about the status of the call request. Once the call manager connects to the online
service, the spreadsheet application takes control and manages the incoming data. After all the data has been transferred, the call is terminated.
Now that you know some of the basics of Windows Telephony, you can use Visual Basic to develop an application capable of initiating calls. The examples in this section use Assisted Telephony to develop such an application, but you can also use the
procedures outlined here to develop an application that can receive calls using the Full Telephony API.
The first point to note when developing Visual Basic TAPI applications is that there are no immediate include files created to allow you to access TAPI.DLL. In order to incorporate an external function located in TAPI.DLL into your Visual Basic
application, you must define the function internally. The next few sections take you step-by-step through two examples, and then examine some of the other functions available to you via TAPI.
The simplest Assisted Telephony operation is tapiRequestMakeCall(). This TAPI function allows you to establish a connection by passing a phone number (otherwise known as a TAPI address) to a call manager for dialing purposes. The sample code for this
function uses a phone number entered by the user on the command line and dials that number.
To begin this development endeavor, you must first declare the function and constants used by that function. You should place these declarations in a module containing global declarations for the entire application, as shown in Listing 26.1.
Declare Function tapiRequestMakeCall Lib "TAPI32.DLL" _ (ByVal lpszDestAddress As String, ByVal lpszAppName As String, _ ByVal lpszCalledParty As String, ByVal lpszComment As String) _ As Long Global Const TAPIERR_NOREQUESTRECIPIENT = -2& Global Const TAPIERR_REQUESTQUEUEFULL = -3& Global Const TAPIERR_INVALDESTADDRESS = -4&
The declarations in Listing 26.1 inform Visual Basic that a function that you require resides externally in the library called TAPI32.DLL—the 32-bit version of TAPI.DLL. The parameters that are to be passed to the function are to be passed by
value, meaning that the value passed to the function in Visual Basic is the value passed to the TAPI.DLL function. In contrast, ByRef informs Visual Basic to pass arguments as pointers, or references, to values.
From the declaration of tapiRequestMakeCall(), the lpszDestAddress parameter specifies a destination address of the call request and contains the phone number. The lpszAppName specifies the name of the application originating the call. The
lpszCalledParty specifies the called party's name. The lpszComment parameter specifies a comment about the call.
The reason for declarations is to provide an association between a Visual Basic internal call and a function residing in an external library. This association allows you to call external functions within Visual Basic as though they were native to Visual
Basic. Once you create these associations, you can write the code required to perform the desired TAPI operations.
Tip
Listing 26.2 first extracts the phone number entered on the application's command line, phone_num$ = Command$. The program then verifies that a number has been provided on the command line by checking the length of the string in phone_num$. If a phone
number is provided in phone_num$, the tapiRequestMakeCall(phone_num$, "", phone_num$, "") function is called to access the call manager and make the call. The first parameter, as shown in the declaration of Listing 26.1, is the address
to be assigned to a line. This address is the number that will be dialed when the function executes. The third parameter, as you will notice, is the same variable. In this case, you are merely assigning the phone number as the called party's identification
for tracking and notification purposes.
Sub Form_Load ()
phone_num$ = Command$
i = Len(phone_num$)
If i = 0 Then End
retval& = tapiRequestMakeCall(phone_num$, "", phone_num$, "")
If retval& = 0& Then End
infostr$ = "Unable to dial " + phone_num$ + "because"
Select Case retval&
Case TAPIERR_NOREQUESTRECIPIENT
infostr$ = infostr$ + "a call-manager is unavailable."
Case TAPIERR_REQUESTQUEUEFULL
infostr$ = infostr$ + "the Windows Telephony dialing queue is full."
Case TAPIERR_INVALDESTADDRESS
infostr$ = infostr$ + "the phone number is invalid."
Case Else
infostr$ = infostr$ + "of an unknown problem."
End Select
MsgBox infostr$
End Sub
Once the function is called, the TAPI.DLL is initialized and the function is called internal to TAPI. At this point, TAPI initializes the call manager in order to make the call and establish a connection for use by the Visual Basic application (see
Figure 26.16). If an error should occur, as represented by a non-zero result, a message box, using MsgBox, is displayed to comment about the error.
Figure 26.16. The Windows Telephony Dialer is the default call manager available to call on behalf of applications utilizing Assisted Telephony.
With Assisted Telephony, the tapiRequestMakeCall() function takes into account a number of operations that would otherwise have to be performed by a Full Telephony application at the lower level of the TAPI. Assisted Telephony performs the following
operations for you in order to minimize the amount of work required to establish and perform a call:
As you can see from the list, Full Telephony applications are a bit more complex than Assisted Telephony applications. For most applications you create with Visual Basic, Assisted Telephony will provide you with the basic requirements for a TAPI-enabled
application.
Occasionally, you will have to extract country- and city-specific information in order to allow your application to assist in properly formatting telephone numbers and offering these as defaults when new numbers are entered in a phone book entry or
database record. The function that gets this information is called tapiGetLocationInfo() and is declared within Visual Basic as follows :
Declare Function tapiGetLocationInfo Lib "TAPI32.DLL" _(ByVal lpszCountryCode As _String, ByVal lpszCityCode As String) As Long
The lpszCountryCode parameter contains a string variable where the country code for the current location will be returned. You should allocate at least eight bytes to hold the string. The call will place an empty string (\0) in the argument variable if
the country code has not been set.
The lpszCityCode parameter contains a string variable where the city area code for the current location will be returned. As with the country code, you should allocate at least eight bytes to store the values. The call will place an empty string (\0) in
the argument variable if the city code has not been set.
In Listing 26.3, you see that two string variables are declared statically for 10 bytes. These variables are passed as arguments to the tapiGetLocationInfo() function in order to retrieve the country and city codes from TAPI. Once retrieved, the
information is displayed in a simple message box as a result of the call to MsgBox.
Private Sub Form_Load()
Dim lpszCountryCode, lpszCityCode As String * 10
retval& = tapiGetLocationInfo(lpszCountryCode, lpszCityCode)
MsgBox lpszCountryCode + "/" + lpszCityCode
End Sub
On the disk included with this book, you will find a file called vbtapi32.txt. This file contains the declarations required to access TAPI from Visual Basic so that you can immediately begin developing state-of-the-art TAPI-enabled applications. The
functions are separated into Assisted Telephony and Full Telephony functions and also include global definitions for use within your applications. To use this file, add it to your project list by selecting the File | Add File menu selection.
Of the methods declared in the included file, pay close attention to those shown in Listing 26.4. You will use these primary functions whenever you implement the Assisted Telephony you were exposed to in Listings 26.1 through 26.3.
Declare Function tapiRequestMakeCall Lib "TAPI32.DLL" _ (ByVal lpszDestAddress As String, ByVal lpszAppName As String, _ ByVal lpszCalledParty As String, ByVal lpszComment As String) As Long Declare Function tapiRequestMediaCall Lib "TAPI32.DLL" _ (ByVal hWnd As Integer, ByVal wRequestID As Integer, _ ByVal lpszDeviceClass As String, ByVal lpDeviceID As String, _ ByVal dwSize As Long, ByVal dwSecure As Long, _ ByVal lpszDestAddress As String, ByVal lpszAppName As String, _ ByVal lpszCalledParty As String, ByVal lpszComment As String) As Long Declare Function tapiRequestDrop Lib "TAPI32.DLL" _ (ByVal hWnd As Integer, ByVal wRequestID As Integer) As Long Declare Function tapiGetLocationInfo Lib "TAPI32.DLL" _(ByVal lpszCountryCode As String, ByVal lpszCityCode As String) As Long
The code in Listing 26.4 uses the tapiRequestMakeCall() and the tapiGetLocationInfo() functions described in the previous sections, as well as the tapiRequestMediaCall() function. The tapiRequestMediaCall() function requests a media call for accessing
one of the media streams (such as voice, fax, or data). The request is passed to an application that has been registered with the API as a recipient of such requests. The TAPI_REPLY Windows message informs the application about the success or failure of
the request. Once the call is established, the media stream becomes active and control is turned over to the application through the media control API.
Note
The hWnd parameter of the function specifies the window handle of the application. From Visual Basic, this handle can be the hWnd property of the form in which the function is being called (for example, Form1.hWnd). The wRequestID parameter provides an
identifier, which you provided during development, that identifies the current call request. The value supplied for this argument is used in a later call to the tapiRequestDrop() function to disconnect the line. As shown in Listing 26.4, this function
takes the same hWnd argument and the wRequestID used to establish the call.
The lpszDeviceClass is the name of the device class that identifies the media type for the requested call. Table 26.1 lists the most common device classes. The first portion of a name identifies the API used to manage the device class, and the second
portion is typically used to identify a specific device type extension or subset of the overall API (such as mci/wave or mci/midi). For those classes that do not have a second portion, such as comm, the entire API is used for the desired operation.
Device Class Name |
Description |
|
comm |
Serial Device API or Comm Port |
|
wave |
Wave Audio |
|
mci/midi |
Midi Sequencer |
|
mci/wave |
Wave Device Control |
|
tapi/line |
TAPI Line Device |
|
tapi/phone |
TAPI Phone Device |
|
ndis |
Network Driver Interface |
The lpDeviceID parameter specifies the name of the media device that corresponds to the media stream of the requested call. This device is associated with the device class specified in lpszDeviceClass. Such devices include the Windows Media Player,
which allows you to manipulate the wave and midi class media streams. The dwSize parameter is the length of the lpDeviceID string in bytes.
The dwSecure parameter specifies the security of the media call. If the value is set to 0, the call is not required to be secure, and features such as call waiting are not disabled and are allowed to interfere with the media stream on the call. If
dwSecure is set to 1, the call is required to be secure, which causes all features that could interrupt the media stream to be disabled.
As with the tapiRequestMakeCall() function, the lpszDestAddress, lpszAppName, lpsz-CalledParty, and lpszComment specify the phone number and associated identifiers that identify the line address and the call. Of these arguments, only lpszDestAddress is
required in order to establish a call.
Windows Telephony is a simple but powerful technology that allows you to easily develop applications that link your computer directly with the telephone network. The Windows Telephony Application Programming Interface (TAPI) contains all of the functions available for you to transparently access the underlying network and easily develop applications that provide telephony services to Microsoft Windows users. The examples in this chapter discussed the Assisted Telephony functions of tapiRequestMakeCall() and tapiGetLocationInfo(),which provide an excellent foundation for accessing and utilizing the other Windows Telephony from Visual Basic.