|
|
|
|
TAPI FAQ Table of Contents
What is TAPI?TAPI is the Telephony API. Oh, you want more? TAPI is a Microsoft and Intel venture to simplify and standardize telephony interfaces. TAPI consists of the TAPI Service Provider (TSP), TAPI modem drivers, and some other things of little consequence to APRO. TAPI is available for Win9x/ME/NT4/2K/XP. The TSP for Win9x/ME is Unimodem/V, for NT4 is Unimodem, and for 2K/XP is Unimodem/5. Back to TopWhat is the TSP?The TSP is the TAPI Service Provider. Quite simply, the TSP is the interface between the API and the hardware. All versions of Windows since 95 and NT have some form of TSP installed by default, but with different capabilities. For data calls, those differences are generally trivial enough not to worry about. The differences really come into play with voice calls. Microsoft did a really nice thing for telephony developers, they made the TSPs backwards compatible with the original TSP. Back to TopWhat is Unimodem?Unimodem is the default TSP used by Windows. Unimodem comes in a few different flavors:
Back to TopWhat is a modem driver?A modem driver is the modem's .INF file, hardware drivers and wave drivers. For a data modem, the driver is usually just the INF file that describes the commands and responses used by TAPI. If you have a software modem (Winmodem, LT modem, HCF or RCP), then the driver will usually include a hardware device driver to simulate a physical serial port. Voice modems will also include a wave driver that can translate to and from the raw wave data used by the modem. The number one thing to remember about modem drivers is to update them. The INFs files seem to be written by semi-literate alpacas, and are very frequently inadequate. One major modem manufacturer (who will remain nameless, but usrs of those modems know who they are) has been known to ship INF files for obsolete modems inside the box with the new modems. Check the manufacturer's web site often for updates to the drivers. Do that now, we'll wait. www.modemhelp.org has links to most manufacturers web sites. The hardware drivers are also something to watch out for. Lucent LT modems use a replacement port driver, replacing the Windows driver. That's why you can only have one of those modems installed. Other modems installed on a system with a LT modem can also be affected, since those modems will now use the Lucent driver. Modems generally use just the raw wave chunks, with the wave headers stripped out. When playing a wave, the wave drivers will take the wave data, convert it to something that the natively understands, then sends the raw wave chunks to the modem. When recording, the wave drivers take the raw wave chunks from the modem, converts them to the desired format, adds wave headers and sends them to the application (through the TSP). Back to TopWhy use TAPI?Well, you'd want to use TAPI because it is already the default modem control API for Windows. TAPI is by no means perfect, it has many flaws, shortcomings, and some rather interesting design compromises. The biggest reason for using TAPI is that TAPI is the way most Windows users expect to access modems. When they sign up for their AOL account, they tell the wizard to use the modem installed and managed by TAPI. Without TAPI, they'd have to specify which com port to use, find their modem in a modem database managed by AOL, and then tweak the modem settings for their use. Can you image the problems that would arise when an AOL user starts configuring their modem manually? Back to TopWhat do I need to do voice?You'll need a computer, a voice-capable TSP, and a voice modem. Microsoft includes a voice-capable TSP in Windows 9x/ME/2K/XP. The initial release of Windows 95 did not include a voice-capable TSP, but it could be downloaded from Microsoft's site. At the time of this writing, all of the links that we had are dead but they're up there somewhere. The voice modem needs to have modem drivers that install wave drivers, and correctly configure the modem for voice operations. Different modems have different voice capabilities, see here for reviews of modems that can help decide which modems to get (and which modems to run away from) Back to TopWhat are the limitations of TAPI voice?APRO implements TAPI voice via the TAPI AutomatedVoice media mode, and that has some limitations. Lets' start off at the beginning and talk about establishing the connection. TAPI notifies the application (via the TApdTapiDevice) when a connection is established, but how does it determine that a connection is there? With data, it's easy, just watch for the DCD signal to go high, or wait for the modem to return "CONNECT". With voice, it's completely different. When you answer a call in voice mode, the modem (and TAPI) know exactly when you're connected, it's right after the modem goes off-hook. When you dial it gets tricky. Consider what happens when you call someone on the phone, how do you tell when they answer? Well, you wait for them to say "Hello", or you wait until the ringback stops ringing back. (the ringback signal is when the remote phone rings and you hear it on your local phone). The modem can't tell the difference between the audible ringback and someone saying "Hello", so it will usually just fake it and say that it's connected a few seconds after dialing. All of this is with the modem, we haven't touched on the TAPI side yet. TAPI (I'm talking about the Unimodem/V and Unimodem/5 TSPs) AutomatedVoice was designed by Microsoft to answer calls, for answering-machine-type calls; TAPI was not designed for outbound/dialed calls. Even if your device can tell when the call is actually answered, TAPI isn't looking for the connection response. TAPI will arbitrarily generate the connect notification shortly after dialing, regardless of whether the called party actually answered. In some versions of Unimodem, you'll get a connect notification even if the modem couldn't dial, or if the remote line was busy. If this happens, you'll usually get an OnTapiFail event *after* the OnTapiConnect. On a related note, let's discuss determining when the remote disconnects. In a data call, the modem will detect when the carrier is lost and drop the DCD signal, which TAPI will pick up and determine that the remote hung up. In a voice call, TAPI/Unimodem can't tell when voice energy has left the line, so it also can't tell when the remote hangs up. Working around the limitations The best way to work around these limitations is to use hardware that can actually tell when a called party answers and when they hangup. Dialogic is the most popular (based on an exhaustive survey..., actually that's the only one that has been mentioned in the APRO newsgroups in the past few months). The extra features have an extra cost, the voice telephony boards are usually several hundred dollars. In lieu of a
voice board, it may be possible to handle this with a regular
voice modem. -Detecting the disconnect really can't be done, but you can check for inactivity by using a timer and resetting it from the TApdTapiDevice events. Back to TopHow do I select which modem to use with the TApdTapiDevice?When the TApdTapiDevice is created, it enumerates all of the installed TAPI devices. The TApdTapiDevice.SelectDevice property will display a dialog presenting the user with a list of those devices that they can select from. If they select a device, the TApdTapiDevice.SelectedDevice property is updated to reflect the name of that device. The TApdTapiDevice.TapiDevices property (a TStrings, public property) contains all of the enumerated devices, so you can pick from there programmatically if you so desire. The .SelectedDevice is the device that we'll use. If SelectedDevice is empty, and only one TAPI device is installed, APRO will select that device automatically when you try to do something that requires a device. If you have more than one TAPI device installed, we'll pop up the SelectDevice dialog for you. With some setups, the list of devices will include things that APRO can't use, use the .FilterUnsupportedDevices property to filter out the devices that don't match our requirements. FilterUnsupportedDevices will exclude devices that don't support TAPI 1.4, and don't support the datamodem media mode (can't handle data connections). Some devices, such as a few of the Dialogic voice boards, are compatible with the APRO voice stuff, but can't do data, so they are excluded from the filtered list. A future version of APRO will have a more finely tuned filtering mechanism. Back to TopHow do I answer a call?After selecting a device, call the TApdTapiDevice.AutoAnswer method. AutoAnswer will tell the TApdTapiDevice to start monitoring the device for status callbacks, and we'll tell TAPI to answer the call once TAPI tells us that the desired number of RING signals has been received. (the AnswerOnRing property determines what that number is). Once TAPI has established the connection, the OnTapiPortOpen event will be generated (if you're in a data call), and you can commence communicating. If you're in a voice call, only the OnTapiConnect event will be generated. OnTapiConnect will also fire for a data call, but you're not guaranteed that the port is actually open then. Back to TopHow do I dial?After selecting a device, call the TApdTapiDevice.Dial method, passing in the phone number that you want to dial as the parameter to that method. Use the OnTapiConnect event to determine when a voice call is answered; and OnTapiPortOpen to determine when a data call is answered and the connection has been established. Back to TopWhat do I do with the connection?OK, so you've dialed or answered, and now have a connection...what next? Well, that's really up to you and the type of connection you have established. If you have a data connection, then treat it just like any other data connection. Use the TApdComPort to transmit characters to the other side, the TAdTerminal to provide an interactive terminal, TApdProtocol to transfer files, TApdDataPacket to watch for incoming text, etc, etc, ad nauseum. If you have a voice connection then you use the TApdTapiDevice to play/record waves and send/detect DTMF tones. Back to TopWhat about terminating the connection?Terminating the connection with TAPI is easy, call the TApdTapiDevice.CancelCall method. When that is called, the OnTapiPortClose event will fire shortly afterwards if you're in data mode. If you're in either data or voice mode, the OnTapiFail event will fire when CancelCall completes (TAPI considers terminating a call a failure, so we pass that along to you). You can tell the difference between a real failure and a CancelCall-induced failure by looking at the TApdTapiDevice.Cancelled property from within the OnTapiFail event, that will be True if CancelCall was called. TAPI can cancel the call and terminate the session on it's own also. It will do this if the other side disconnects and if TAPI can detect that disconnect. See the limitations of TAPI voice for a brief discussion of how TAPI handles remote voice disconnects. For data, TAPI monitors the DCD line, and cancels the call when DCD is dropped. Back to Top |
