TAPI ARCHITECTURE:

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:

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  shows the two calls, their parameters, and descriptions of what they do and how they can be used.

The Assisted Telephony API.

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

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:

Table shows the Basic Telephony API calls, sorted by functional group, along with a short description of their use.

The Basic Telephony line device API set.

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    shows how this looks in the LINECALLLIST structure.

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 shows the list of data structures used by the Basic Telephony API set along with short descriptions of their use.

The Basic Telephony API line device structures.

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.

Basic Telephony line device messages.

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

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

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:

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

The Supplemental Telephony API set for line devices.

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:

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

Table 23.5. The Supplemental Telephony API for phone devices.

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.

Table 23.6. The Supplemental Telephony phone device structures.

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.

Table 23.7. The Supplemental Telephony phone device messages.

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.

Table 23. 8. The Extended Telephony API set.