TAPI - Microsoft Telephony

Contents:

Reference: Using C-Kermit, Chapters 4 and 5, Appendix II.

TAPI is Microsoft's Telephony Application Programming Interface for Windows 95 (all versions) and for Windows NT 4.0 or later. It is not available on Windows NT 3.51 or earlier, nor on any version of OS/2. TAPI is supposed to free the application (such as Kermit 95) from the necessity of knowing the specific details required to control different makes and models of modems and other communication devices, and it is supposed to let multiple applications share the same communication device.

The benefits of TAPI include:

Sometimes you might want to use Kermit's built-in modem and dialing facilities, sometimes you might prefer to use TAPI's, and sometimes you might want to mix and match. Each system has its advantages and drawbacks:

Kermit 95 lets you choose any combination of:

Regardless of which combination you choose, all of Kermit 95's dialing directory features are still available: phone number lookup, multiple phone numbers per entry name, and cheapest-first dialing.

Kermit's TAPI support is in Kermit 95 itself, in the K95 Dialer, and in the SETUP program.


Kermit 95 and TAPI

Links: [Next] [Index]

The procedure for using TAPI modems in Kermit 95 is only slightly different from what you are accustomed to.

Previously, Kermit 95 treated the communications port (e.g. COM1) and the modem type (e.g. US Robotics Sportster) separately. To make a dialout call, you had to tell Kermit which port to use and which kind of modem was on it, and the interface speed between them:

  set modem type usr
  set port com1
  set speed 57600
  dial 7654321

TAPI, however, is not concerned with COM ports. Instead it uses descriptive names, like "Sportster 28800 External", to denote a particular COM-port/modem combination. These names can contain spaces and mixed-case words. In Kermit 95, TAPI names have their spaces converted to underscores:

  TAPI Name:  Sportster 28800 External
  K-95 Name:  Sportster_28800_External

The new command for choosing a TAPI device rather than a COM-port / modem combination is:

  SET TAPI LINE [ k95-tapi-name ]

for example:

  set tapi line Sportster_28800_External

You can use ?, completion, and abbreviation on the name, since it is a Kermit keyword. You can also use the synonym SET TAPI PORT. If you have more than one TAPI device defined, you can type "set tapi line ?" to see a list. You can select the desired device by typing enough characters to distinguish from from any other one in the list. If you only have one TAPI device, "set tapi line" (by itself) selects that device. If you have more than one TAPI device, "set tapi line" (by itself) selects the lowest-numbered TAPI device.

As noted below, you can choose whether you want Kermit or TAPI to dial the modem. Should you want Kermit to dial the modem, you can choose whether Kermit uses its own built-in knowledge of the modem's commands, or uses the commands that TAPI has defined for this modem. Use:

  SET MODEM TYPE TAPI            ...to import TAPI's commands for this modem
  SET MODEM TYPE built-in-type   ...to select Kermit's modem commands

Kermit 95 loads the TAPI commands automatically whenever you give a SET TAPI LINE command. To demonstrate, give a "show modem" command before and after "set tapi line" and to see the values that were loaded. You can use SET MODEM TYPE specific-type to replace TAPI's modem commands with Kermit's built-in ones, or you can use SET MODEM COMMAND to replace or modify specific commands.

Also when you give a SET TAPI LINE command, the interface speed is copied from the Control Panel. SHOW COMMUNICATIONS will tell you the speed that was chosen. So you don't have to give a SET SPEED command either, unless you want to change the speed that was picked up from TAPI.

The most common configuration includes only one TAPI device, and so the sequence of commands would be, very simply:

  set tapi line
  dial +1 (212) 7654321

For compatibility with previous releases and existing scripts, you can also use the regular SET PORT (or SET LINE) command as follows:

SET PORT TAPI [ k95-tapi-name ]
This command is equivalent to SET TAPI LINE.

So, for example, if you use K95 Host Mode to allow other people to dial in to your PC, and you want to specify a TAPI device, simply specify the port name as "TAPI Sportster_28800_External" (substitute the name of your TAPI device), rather than COM1 or whatever you were using before, and the modem type as TAPI. NOTE: you can't define "TAPI xxx" as the value of a variable and then "set port \m(variablename)", because you can't put a variable in a command field that expands to multiple words, as noted on 347-348 of Using C-Kermit.

SET TAPI USE-WINDOWS-CONFIGURATION { ON, OFF }
This command determines whether the TAPI device uses the settings in the Control Panel for dialing (ON) or Kermit's built-in values (OFF, the default). When ON, K95 does not touch the Windows port configuration, so use this setting to accomplish combinations that K95 might not support intrinsically, such as 8 data bits with parity (in this case, also tell K95 to "set tapi modem-dialing on" and "set parity none").

SET TAPI MODEM-LIGHTS { ON, OFF }
If you set this one to ON, TAPI puts little modem Receive and Transmit Data lights in your Windows 95 status bar. You can view the lights whenever you have chosen a TAPI device. (SET TAPI MODEM-DIALING ON required)


TAPI versus Kermit Modem Dialing

Links: [Next] [Previous] [Index]

You can choose whether Kermit interacts with the modem directly, sending it all its setup and dialing commands and responding to its result codes, or all this is to be handled by TAPI.

SET TAPI MODEM-DIALING { ON, OFF }
When TAPI MODEM-DIALING is OFF, which is the default setting, Kermit obtains the TAPI device from TAPI, but dials the modem itself rather than having TAPI do it. To let TAPI control the modem, SET TAPI MODEM-DIALING ON. You must use TAPI MODEM-DIALING is OFF (the default) to make direct connections. Use TAPI MODEM-DIALING ON if you want the modem to be shared by other TAPI applications, e.g. when waiting for an incoming call.

In general it is better to let TAPI do the dialing if you need to share the port with another application such as a FAX program. Otherwise it is usually better to let Kermit handle the dialing because it is easier to find and fix any problems. You should also use Kermit dialing your modem does not use the AT command set.

The following commands apply only when TAPI MODEM-DIALING is ON; that is, when TAPI is to handle the dialing:

SET TAPI MANUAL-DIALING { ON, OFF }
If you set this one to ON, TAPI pops up a little window to let you dial the modem yourself by typing the appropriate modem command.

SET TAPI PRE-DIAL-TERMINAL { ON, OFF }
If you set this ON, TAPI pops up a little "dumb terminal" window to let you interact directly with the modem prior to dialing.

SET TAPI POST-DIAL-TERMINAL { ON, OFF }
If you set this ON, TAPI pops up a little "dumb terminal" window to let you interact directly with the modem just after dialing.

SET TAPI WAIT-FOR-CREDIT-CARD-TONE { ON, OFF }
This tells TAPI whether to use its normal method of dealing with credit card tones ("bong") when using a TAPI device.


TAPI versus Kermit Phone Number Conversion

Links: [Next] [Previous] [Index]

As described in Chapter 5 of Using C-Kermit, Kermit can figure out how to dial almost any portable-format phone number from any location as long as you have specified the necessary location information, usually just the local country code and area code, plus the long distance and international dialing prefixes used in that location. TAPI can do the same, more or less -- sometimes more, sometimes less.

If a phone number does not begin with "+", it is dialed as given with no conversions, in which case it doesn't matter whether TAPI or Kermit is responsible for conversions.

SET TAPI PHONE-NUMBER-CONVERSIONS { ON, OFF, AUTO }
ON means to let TAPI convert the phone number. OFF means Kermit should convert the phone number as described in Chapter 5 of Using C-Kermit. AUTO (the default) means TAPI should convert the phone number if a TAPI line is in use, and Kermit should do it if a regular COM-port/modem ("set port") device is selected. AUTO is available only at K95 command level, not in the Dialer

SET TAPI LOCATION name
This lets you pick any of the defined TAPI locations (from the Dialing Preferences section of Modems [sic] Properties in the Control Panel). Type "set tapi location ?" for a list. The Kermit name for a location is the same as the TAPI name, except spaces are replaced by underscores. When you pick a TAPI location, its country code, area code, and long-distance and international dialing prefixes are imported by Kermit, just as if you had given the corresponding group of SET DIAL commands.


TAPI Actions

Links: [Next] [Previous] [Index]

Kermit 95 includes the following commands that call up TAPI dialog boxes:

TAPI CONFIGURE-LINE k95-tapi-name
This lets you change the configuration of the given TAPI device without having to leave Kermit, go through the control panel, etc. Any changes that you make here become global and permanent after you click on OK, and of course they are ignored and forgotten if you click on Cancel.

TAPI DIALING-PROPERTIES
This lets you change information related to your current TAPI location, to add a new one, or remove an existing one. Changes here, too, are global and permanent.


TAPI and Incoming Calls

Links: [Next] [Previous] [Index]

Some people think TAPI is supposed to provide a way for multiple applications to wait for incoming calls, with TAPI handing the call off to the right application, such as a fax program, a voice mail or call-processing system for voice calls, and a data communications program for data calls.

In fact, this is only possible if the phone system provides this information to TAPI when the phone rings, as does ISDN and some PBXs and cable modems. It is also possible on analog systems when features such as Distinctive Ring are available. Otherwise, it is each application's responsibility to determine if an incoming call is for it in a non-destructive manner, and if not, hand it off to the next waiting application. On an analog phone system this is nearly impossible. If you want Kermit to answer a call (e.g. in host mode), it is generally best to shut down all other applications that might also be waiting for calls.


TAPI Examples

Links: [Previous] [Index]

set modem type usrobotics
set port com1
set speed 57600
dial +1 (212) 555 1234
This is the traditional Kermit procedure, that does not use or depend on TAPI in any way. This will not work if (a) it's Plug-n-Play modem that has not been previously initialized, or (b) the device is currently owned by TAPI. On the other hand, this method is portable to non-Windows platforms.

set tapi line Sportster_28800_External
dial +1 (212) 555 1234
This is the easiest way to use TAPI. Kermit gets the modem from TAPI, imports the modem's dialing commands and the interface speed from the control panel, and, using TAPI's phone-number conversions, dials the number.

set tapi line
dial +1 (212) 555 1234
Same as the previous example. You can leave out the TAPI device name if it is the default or only TAPI modem device.

set tapi line Sportster_28800_External
set modem type usrobotics
set tapi phone-number-conversions off
set speed 57600
dial +1 (212) 555 1234
Kermit gets the modem from TAPI but controls the modem and the telephone number itself.

set tapi line Sportster_28800_External
set tapi modem-dialing on
dial +1 (212) 555 1234
Kermit gets the modem from TAPI, but lets TAPI do everything.

set tapi line Sportster_28800_External
set tapi phone-number-conversion off
set tapi modem-dialing on
dial +1 (212) 555 1234
Kermit gets the modem from TAPI, but lets TAPI do everything except convert the phone number.

set tapi modem-dialing off
set tapi line
set carrier-watch off
connect
This allows you to CONNECT to a TAPI modem and type AT commands at its command processor.

Click Back on your Browser's Toolbar to return.