Nancy Winnick Cluts
Microsoft Developer Network Technology Team
November 1995
The Microsoft® Windows® Telephony Application Programming Interface (TAPI) provides a way for applications to support telephone communication. This is very important for all of you who want to jump on that band wagon (which is groaning under all of the weight) and move your applications online. In this article, I give you a brief overview of what TAPI is, how applications interact with TAPI, some telephony basics, and where you can find information and tools to help you create your telephony application. So, as Sir Dennis Eton Hogg said to the assembled throng, "And so say all of us: It's time to TAP into America!"
TAPI is an application programming interface that is used to communicate by means of telephones. Some of the abilities that TAPI facilitates are:
Microsoft® 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 Phone Dialer dialog box in the DIALER application
If you play with the DIALER application, you will see some of the things an application can do to give a user the ability to dial calls, set dialing properties, do speed dialing, and set up a connection. The DIALER application allows the user to set the dialing properties by using the dialog box shown in Figure 2.
Figure 2. The Dialing Properties dialog box
TAPI operates independently of the underlying telephone network and equipment. An application that uses TAPI doesn't have to worry about what it is hooked up to—it just needs to interact with the API itself. Figure 3 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) by means of TAPI. The telephony DLL is part of the Windows operating system and implements TAPI support. The telephony DLL interacts with service providers through the Telephony Service Provider Interface (TSPI). Service providers can be thought of much as one thinks of printer drivers—they are written by telephony hardware vendors to support operating within Windows.
To avoid some pitfalls when you develop an application that includes TAPI functionality, you must understand a couple of things about how TAPI works. These are lower-level than what I have covered above. So, if you are interested only in the overview, go ahead and skip this section. If, on the other hand, you like learning about some of the nitty-gritty details, you'll probably want to read this.
When your application supports TAPI, your application must first initialize TAPI by using the lineInitialize function. When your application 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 will not get the notifications meant for it. In short, 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.
The Win32® Software Development Kit (SDK) contains documentation, tools, and sample code to help you to 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).
Also, some tools come with the Win32 SDK that help the developer 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 your own time and pulling your hair trying to figure out why your application doesn't work). TB14.EXE also allows you to see how the different TAPI structures get filled in. This will help you to see whether your application is calling the different TAPI functions correctly. Figure 4 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 using TAPI 1.0 and in Windows 95 using TAPI 1.1.
Tucked away in the Sample Code tree of the MSDN Library, you will find the TAPICOMM sample. This sample demonstrates how to do data transmission over a telephone. Figure 5 shows the main screen of the TAPICOMM sample.
Figure 5. The TAPICOMM sample from the Win32 SDK
If you take a look at the source code for this sample, you will learn how to implement basic telephony functions such as initializing TAPI, opening a phone line, gathering line device capabilities, transmitting data by means of 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 another one of my articles, "Creating a TAPI Connection Using CTapiConnection." The article describes the details of implementing basic TAPI functionality using CTapiConnection, a Microsoft Foundation Class Library (MFC)-based class that I created.
"Developing Applications Using the Windows Telephony API" by Toby Nixon. (MSDN Library Archive, Conferences and Seminar Papers, Tech·Ed March 1994, Microsoft At Work)
Microsoft Telephony Programmer's Reference
Microsoft Telephony Service Provider Interface (TSPI) for Telephony