Tapping into TAPI

Nancy Winnick Cluts

September 22, 1995

The Microsoft Windows Telephony Application Programming Interface (TAPI) provides a way for applications to support telephone communication. TAPI is vitally important for developers who want to jump on that band wagon (which is groaning under all of the weight) and move their applications online.

The following is a brief overview of TAPI, including how applications interact with TAPI, some telephony basics, and where to find information and tools to help create telephony apps.

What is TAPI?

TAPI is used to communicate via telephones. Among the abilities that TAPI facilitates are:

• Connecting directly to a telephone network.

• Automatic phone dialing.

• Transmission of data (files, faxes, electronic mail).

• Access to data (news, information services).

• Conference calling.

• Voice mail.

• Caller identification.

• Control of a remote computer.

• Collaborative computing over telephone lines.

Windows 95 comes with a telephony application, DIALER.EXE, that can dial voice calls, act as a proxy for applications making simple telephony requests, and maintain a call log. Figure 1 shows the main screen for the phone dialer application.

Figure 1. The DIALER.EXE application

If you play with the DIALER application, you'll see some of the things that an application can do to give a user the ability to dial calls, set dialing properties, do speed dialing, and set up a connection. A user sets the dialing properties in the DIALER application by using the dialog box shown below.

Figure 2. The dialing properties dialog box

TAPI operates independently of the underlying telephone network and equipment. An application that uses T API doesn't have to worry about which kind of equipment it is hooked up to—it just needs to interact with the API itself. The following figure shows the relationship among the application, TAPI, and the telephony service provider.

Figure 3. TAPI and applications

As Figure 3 shows, the application interacts with the telephony dynamic-link library (DLL) via TAPI. The telephony DLL is part of the Windows operating system and implements TAPI support. The telephony DLL interacts with service providers via the Telephony Service Provider Interface (TSPI). Service providers can be thought of as akin to printer drivers; they are written by telephony hardware vendors to support operating within Windows.

Some technical issues

To avoid some pitfalls when you develop an application that includes TAPI functionality, there are a couple of things you must understand about how TAPI works. These are lower-level than what is covered above.

When an application supports TAPI, it must first initialize TAPI via the lineInitialize function. When your app makes this call, the telephony DLL creates a hidden window on behalf of your application. This hidden window is used as a method to send notifications and messages. These messages are posted to the hidden window for the different asynchronous events, completion notifications, and state messages (whether the line is connected, proceeding, dialing, and so on). If your application is multithreaded, you need to ensure that the thread that made the call to lineInitialize has a message loop and that the thread services this message loop. If the thread does not service the message loop or if it doesn't have a message loop, your application won't get the notifications meant for it. To put it a little more harshly, your application won't work.

When you make calls into TAPI that require a structure to be filled in, you will need to check the amount of space needed for the structure and re-allocate memory until you have a memory block that is large enough to hold the structure. The reason for this is that each service provider, much like a printer driver, supports different capabilities and holds different amounts of information. As a result, if you pass a pointer to a structure that is not large enough and you don't check to be sure that you have allocated enough space (by checking the dwNeededSize versus dwTotalSize members of the structure that is returned), the structure will be filled in with zeros and your application won't work.

Documentation and development tools

The Win32 Software Development Kit (SDK) contains documentation, tools, and sample code to help you learn about TAPI. Two documents, the Microsoft Telephony Programmer's Reference and the Microsoft Telephony Service Provider Interface (TSPI) for Telephony, are provided to give you some reference material and development guidance. The programmer's reference is intended to document the functionality that an application using TAPI will need. The service provider documentation is for developers who are going to write their own TAPI services (that is, vendors of telephony equipment).

There are also some tools that come with the Win32 SDK to help developers understand TAPI and incorporate TAPI functionality into an application. TB14.EXE is a 32-bit telephony browser that allows you to play around with the different TAPI calls and your COM ports. You will be able to test whether your COM port and modem are set up correctly to begin with (if they aren't, you'll be wasting a lot of time and pulling out your hair trying to figure out why your application doesn't work). It also allows you to see how the different TAPI structures are filled in. This will help you see whether your application is calling the different TAPI functions correctly. The figure below shows the main screen displayed by TB14.EXE.

Figure 4. The TAPI browser: TB14.EXE

Another tool that you can use is the service provider tool, ESPEXE.EXE. This tool is a TAPI service provider that supports multiple virtual line and phone devices. You can configure it for your application. It doesn't require any special hardware, and it supports the entire Telephony Service Provider Interface (including the Windows 95 TAPI extensions). You can use this tool in both Windows 3.1 with TAPI 1.0 and in Windows 95 with TAPI 1.1.

The TAPICOMM sample

Tucked away in the Win32 SDK sample tree, you will find the TAPICOMM sample. This sample demonstrates how to do data transmission over a telephone.

If you take a look at the source code for this sample, you can learn how to implement basic telephony functions such as initializing TAPI: opening a phone line, gathering line device capabilities, transmitting data via the COMM (Communications) API, closing a line, and shutting down TAPI.

If you would like more detailed information, take a look at some of the references listed in the bibliography or read my next article, "Creating a TAPI Connection Using CTapiConnection," which is scheduled for the January release of the Microsoft Development Library. The article describes the details of implementing basic TAPI functionality using CTapiConnection, a Microsoft Foundation Class Library (MFC)-based class that I created.

For Further Reading

"Developing Applications Using the Windows Telephony API," Toby Nixon, MSDN Conferences/Tech*Ed 1994/Microsoft At Work.
Microsoft Telephony Programmer's Reference, Win32 SDK.
Microsoft Telephony Service Provider Interface (TSPI) for Telephony, Win32 SDK.

Nancy Winnick Cluts is a writer for the Microsoft Developer Network. When not trying to further her book-writing career through shameless self-promotion—Programming the Windows 95 User Interface (Microsoft Press, August 1995)—she can be found in her rose garden attempting to eradicate black spot and aphids by chanting.