TAPI Architecture

• Assisted Telephony Services
• Basic Telephony Services
  • The Basic Telephony Line Device API Set
  • The Basic Telephony Line Device Structures
  • Basic Telephony Line Device Messages
• Supplemental Telephony Services
  • Supplemental Telephony API for Line Devices
  • Supplemental Telephony API for Phone Devices
  • The Supplemental Telephony Phone Device Structures
  • The Supplemental Telephony Phone Device Messages
• Extended Telephony Services
• Summary

In this chapter, you'll learn how the Telephony API is organized and how its various function calls are used to provide TAPI services to Windows applications. You'll learn about the four different levels of TAPI services:

• Assisted Telephony-This is the simplest form of TAPI service.
• Basic Telephony-This provides basic in- and outbound telephony services for a single-line phone.
• Supplemental Telephony-This provides advanced telephone services such as hold, park, conference, and so on, to single and multiline phones.
• Extended Telephony-This provides a direct interface between Windows programs and vendor-specific TAPI services.

You'll also learn how these levels of service are implemented using API calls and how they work together to provide complete TAPI services, from a simple Dial button, through handling inbound and outbound calls, to acting as a switchboard in a multiline setting, and finally to providing access to vendor-specific features of telephony cards.

When you complete this chapter you'll understand how the Telephony API is organized and how you can use it to add telephony services to your Windows applications.

Assisted Telephony Services

The simplest form of TAPI service is Assisted Telephony. Under the Assisted Telephony interface, programmers can place outbound calls and check the current dialing location of the workstation. This type of telephony service can be used to provide a simple Dial button to existing applications or add dialing capabilities to new applications that will use telephony as an added service.

In fact, the Assisted Telephony model only provides access for programs to request the placement of an outbound call. The actual dialing of the call is handled by another Windows/TAPI application. The default application is DIALER.EXE. This application ships with the Windows TAPI SDK and is part of the Windows 95 operating system.

There are two API calls used to provide Assisted TAPI services. Table 23.1 shows the two calls, their parameters, and descriptions of what they do and how they can be used.

The TapiRequestMakeCall has four parameters. Only the DestAddess is required. The DestAddress is a string of numbers that represents the telephone number to dial. For example, "999-555-1212" is a valid DestAddress in the United States format. The AppName parameter is the name of the application that requested the TAPI service. This would be the name of your application. The CalledParty is a string that represents the name of the person you are calling. This information could be used by the DIALER.EXE application to log the person called. The Comment parameter could contain a string of text describing the reason for the call.

The TapiGetLocation function returns two parameters: the CountryCode and CityCode of the current location set by the Windows control panel TAPI applet. These two parameters are stored in the TELEPHON.INI file in the Windows folder of the workstation. The country code is a value used to place out-of-country calls. The country code for the United States is "1." The CityCode is known as the area code in the United States. The combination of the country code and the city code is used to determine how the TAPI dialer will place the requested call.

For example, if the requested call contained "1-312-555-1212" and the current workstation location indicated a country code of "1" and a city code of "312," then the TAPI DIALER.EXE program would attempt to place the call without including the country or city codes: "555-1212." If, however, the requested call contained "43-80-12 33 45" then the DIALER program would assume that the user was attempting to place an out-of-country call and would use the appropriate dialing prefixes.

Basic Telephony Services

Basic Telephony is the next level up in the TAPI service model. Basic Telephony function calls allow programmers to create applications that can provide basic in- and outbound voice and data calls over a single-line analog telephone. The analog phone line most often used for this level of service is often referred to as a POTS or Plain Old Telephone Service line. The Basic Telephony API set can also be used with more sophisticated lines such as T1, ISDN, or digital lines. However, the added features of these advanced line devices (such as call forwarding, park, hold, conference, and so on) are not available when using the Basic Telephony API set.

The Basic Telephony level of service focuses on the use of a line device as a means of transporting information from one place to the next. A line device to TAPI can be a handset, a fax board, a data modem, a telephony card, or any other physical device that can be attached to a telephone line, But it is treated as a virtual device, not a physical one.

Line devices are not associated directly with any physical telephone line. This way, TAPI can "see" multiple TAPI devices on the same machine (data modem, handset, and fax board) while there is only one physical telephone line attached to the workstation (see Figure 23.1).

Figure 23.1 : The relationship between TAPI line devices and physical phone lines

One of the primary functions of the TAPI interface is to handle multiple TAPI service requests from the workstation. It is possible that several applications running on the workstation may request TAPI services at some time. The call control application (DIALER.EXE) accepts each request and places them in a queue for processing in the requested order.

The Basic Telephony Line Device API Set

The Basic Telephony service model has several API calls for handling and fulfilling service requests. These calls can be collected into logical groups:

• Basic line-handling calls handle the initialization and opening and closing of TAPI lines.
• Line settings and status calls handle the reading and writing of various parameter values that control the behavior of the line device.
• Outbound and inbound functions handle the details of placing an outbound voice or data call and answering an inbound voice or data call.
• Addressing functions handle the details of recognizing, translating, and/or building telephone "addresses" or dialing strings.
• Miscellaneous features handle other TAPI-related functions, such as managing call-monitoring privileges and manipulating call handles.

Table 23.2 shows the Basic Telephony API calls, sorted by functional group, along with a short description of their use. "Creating TAPI-Enabled Applications."

The Basic Telephony Line Device Structures

Along with the extensive API set for Basic Telephony, the TAPI model defines several data structures that are used to pass information between TAPI and the requesting application. The layout of the structures contains variable as well as fixed data. This allows the API set to contain information of indeterminate length without prior knowledge of the contents of the structure.

In order to handle variable-length structures, the defined data structures contain fields that indicate the total size needed to fill in all variable data (dwNeededSize) along with the total size used by TAPI when filling in the structure (dwUsedSize). Listing 23.1 shows how this looks in the LINECALLLIST structure.

Listing 23.1. Viewing the LINECALLLIST structure.

typedef struct linecalllist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwCallsNumEntries;
  DWORD  dwCallsSize;
  DWORD  dwCallsOffset;
} LINECALLLIST, FAR *LPLINECALLLIST;

The dwTotalSize field is first set by the calling application to tell TAPI how much memory has been allocated for the structure. If TAPI cannot fill in all values without running out of allocated space, an error is returned and it is the job of the requesting application to re-allocate space and make the call again.

Along with the total size and total needed fields, each variable-length structure has a fixed portion and a variable portion. The fixed portion contains values that indicate the size of the variable-length field and the offset (from the start of the structure) at which the field is located. Note the fields dwCallsSize and dwCallsOffset in the LINECALLLIST structure shown in Listing 23.1.

Table 23.2 shows the list of data structures used by the Basic Telephony API set along with short descriptions of their use.

Basic Telephony Line Device Messages

The Telephony API uses Windows messages to communicate with the requesting application. When the requesting application first performs a LineInitialize function, a callback function address must be supplied. All messages are then sent to this callback function.

Each message returns the same set of parameters. The first is the relevant handle. Usually this is the call handle, but it may also be a line handle. The second parameter is the callback instance value. This value will always be the instance handle of the current running application. The next three values vary depending on the message. One or more of these return values will contain non-zero data. Table 23.3 contains a list of the Basic Telephony messages, their parameters, and short descriptions.

Supplemental Telephony Services

The Supplemental Telephony functions provide advanced line device handling (conference, park, hold, forward, and so on). Access to these advanced services is dependent on the type of telephone line to which the workstation is connected. In other words, even if you implement call forwarding functions within your TAPI application, these functions will only work if call forwarding services are available on the telephone line provided by the local telephone company.

The Supplemental Telephony functions also allow programmers to handle service requests for multiple-line phones. You can use Supplemental Telephony to mange a physical handset that has access to multiple physical lines (see Figure 23.2).

Figure 23.2 : Using Supplemental TAPI to manage a single handset linked to multiple physical lines.

You can also use the Supplemental Telephony functions to manage multiple handsets using one or more physical lines. Because TAPI "virtualizes" both line and phone devices, there need not be a direct one-to-one correspondence between a defined phone device and a defined line device. In this way you can use TAPI to create a switchboard application to manage telephony services (see Figure 23.3).

Figure 23.3 : Using Supplemental TAPI to provide switchboard services

Supplemental Telephony also provides access to defining and manipulating phone devices. To TAPI a phone device is any device that can accept or place calls. In effect, you can register your workstation as a phone device. Then you can use resources on your workstation to place or accept calls without the need of a handset or desktop phone. Of course, in order to act successfully as a phone device, your workstation must have audio input and output hardware.

Supplemental Telephony API for Line Devices

The Supplemental API set for line devices adds advanced call control and other features to the API library. The set can be divided into the following related groups of functions:

• Digit and tone handling functions allow programmers to detect and generate digits or tones along the phone line. This capability is needed to allow some systems to perform advanced line operations such as forwarding, call holds, and so on.
• Advanced line-handling functions provide call acceptance, rejection, redirection, and other operations. These are most useful in an environment where the phone line is connected to a central switch instead of directly to the external telephone service provider.
• Advanced call features functions provide Call Hold, Transfer, Park, Forward, and Pickup capabilities. These functions only work if the telephone line supports the advanced call features.
• Miscellaneous advanced features functions provide added features specific to TAPI service requests, such as monitoring lines and setting call parameters.

Table 23.4 shows all the Supplemental Telephony API functions for the advanced line device features.

Supplemental Telephony API for Phone Devices

The Supplemental Telephony API also provides function calls for the handling of phone devices. To TAPI, any device that can place or accept calls can be a phone device. The phone device API set allows programmers to invent their own phone devices in code. In effect, you can create a virtual handset using the TAPI phone device. This allows properly equipped workstations to act as single- or multiple-line phones in an office environment. If your pc has appropriate audio input and output hardware (speakers, sound card, microphone, and so on) and is connected to the telephone service, you can create a "handset" using the phone device API set.

The Supplemental Telephony API set for phone devices can be divided into the following function groups:

• Basic phone-handling functions provide basic initialization and shutdown, opening and closing a phone device, and ringing the open device.
• Phone settings and status functions allow programmers to read and write various settings of the phone device such as volume, gain, hookswitch behavior, and so on.
• Physical display, data, button, and lamp functions can be used to read and write display information to desktop units. Since TAPI can be used to support more than just pc workstations, these functions allow a central TAPI program to monitor and update LCD displays, to flash lamps, to change buttons labels, and to store and retrieve data from desktop terminals.

Table 23.5 shows all the Supplemental Telephony phone device API calls along with short descriptions of their use.

The Supplemental Telephony Phone Device Structures

Just as the line device API set has a series of data structures, the phone device set also has related data structures. These structures are used to pass information between the desktop program and the TAPI service provider.

The phone device structures most often used are the PHONECAPS and PHONESTATUS structures. Table 23.6 shows all the phone device structures along with brief descriptions of their use.

The Supplemental Telephony Phone Device Messages

The Supplemental Telephony phone device also uses a callback function to register a function address to receive Windows messages. This callback address is established during the phoneInitialize API call.

Each message returns the same set of parameters. The first is the handle of the phone device. The second parameter is the callback instance value. This value will always be the instance handle of the current running application. The next three values vary depending on the message. One or more of these return values will contain non-zero data. Table 23.7 contains a list of the Basic Telephony messages, their parameters, and short descriptions.

Extended Telephony Services

The last level of Telephony services is Extended Telephony. Extended Telephony service allows hardware vendors to define their own device-specific functions and services and still operate under the TAPI service model. By adding a small set of extended service API functions, Microsoft allows hardware vendors to continue to provide unique services not previously defined by TAPI. The TAPI model defines both line and phone device API calls for Extended Telephony.

Table 23.8 shows the Extended Telephony API set along with short descriptions of their use.

The actual meaning and use of extended TAPI calls is defined by the service provider or hardware vendor. Extended Telephony providers define the parameters of the calls and their meaning, and publish this information to the programmer. The programmer can then check the version information with the service provider before attempting to make an extended service call.

Summary

In this chapter you learned how the TAPI service model is implemented as a set of API calls. You learned there are four levels of TAPI services:

• Assisted Telephony-The simplest form of TAPI service.
• Basic Telephony-Provides basic in- and outbound telephony services for a single-line phone.
• Supplemental Telephony-Provides advanced telephone services such as hold, park, conference, and so on, to single and multiline phones.
• Extended Telephony-Provides a direct interface between Windows programs and vendor-specific TAPI services.

You also learned that the TAPI function set defines two different devices to handle telephony services:

• A line device is used to control the connection between a data source and the physical telephone line.
• A phone device is used to control the connection between a desktop handset and a line device.

Finally, you reviewed the API calls, data structures, and Windows messages defined for each level of TAPI service.