## TAPI - Microsoft Telephony

Contents:

- Kermit 95 and TAPI
- TAPI versus Kermit Modem Dialing
- TAPI versus Kermit Phone Number Conversion
- TAPI Actions
- TAPI and Incoming Calls
- TAPI Examples

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:

- The ability to use Plug-n-Play modems without any special procedures.
- The ability to dial out on a modem that is "owned" by (e.g.) a fax program.
- The ability to use modem models that Kermit 95 doesn't know about.
- The ability to use TAPI dialing rules instead of Kermit's.
- Built-in knowledge of hundreds of modem makes and models and easy installation of new types.

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:

- TAPI might understand your modem when Kermit doesn't.
- TAPI has better support for calling cards
- TAPI does not support non-Hayes-compatible modems
- Kermit supports non-Hayes-compatible modems (Rolm, CCITT, etc)
- Kermit has better support for PBXs
- Kermit supports "10-digit" and other novel forms of dialing
- Kermit is more informative about dialing results
- Kermit's modem controls are easier to configure and customize

Kermit 95 lets you choose any combination of:

- TAPI device versus traditional COM port / modem combination
- TAPI versus Kermit modem control and dialing
- TAPI versus Kermit phone number conversion

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.