Table Of Contents

Cisco TAPI Overview

Introduction

Architecture

Call Control

First Party Call Control

Third Party Call Control

CTI Port

CTI Route Point

Compatibility

TAPI Function Lists

Cisco Specific Function List

Cisco TAPI Overview

---

Introduction

This chapter outlines the key concepts involved in using Cisco TAPI and lists all the functions available in the Cisco TAPI implementation for Cisco CallManager:

•Architecture, which illustrates how Cisco components integrate with NT telephony architecture

•Call Control, which describes how to provide first and/or third party call control

•CTI Port, which discusses CTI ports for first party call control

•CTI Route Point, which describes how CTI route points work

•Compatibility, which discusses using the Cisco TAPI service provider with other TAPI applications

•TAPI Function Lists, which lists the TAPI v2.1 functions

•Cisco Specific Function List, which lists the Cisco extension functions

Architecture

The Cisco TAPI service provider shipped with Cisco CallManager 3.0(5) is TAPI version 2.1. (Cisco also supports TAPI version 3.0.)

Figure 1-1 shows how various Cisco components fit into the Microsoft Windows NT telephony and wave architectures.

Figure 1-1 High-Level View of the Windows NT Telephony and Wave Architectures with Cisco Components (shown in gray)

Call Control

You can configure the Cisco TAPI service provider to provide first and/or third party call control.

First Party Call Control

In first party call control, the audio stream is terminated by the application. Ordinarily, this is done using the Cisco wave driver. However, if you want the application instead of the wave driver to control the audio stream, use the Cisco Device Specific extensions.

Third Party Call Control

In third party call control, the control of an audio stream-terminating device is not "local" to the Cisco CallManager. In such cases, the controller might be the physical IP phone on your desk, or a group of IP phones for which your application is responsible.

CTI Port

For first party call control, a CTI port device must exist in the Cisco CallManager. Since each port can only have one active audio stream at a time, most configurations only need one line per port.

A CTI port device does not actually exist in the system until you run a TAPI application and a line on the port device is opened requesting LINEMEDIAMODE_AUTOMATEDVOICE and LINEMEDIAMODE_INTERACTIVEVOICE. Until the port is opened, anyone calling the directory number associated with that CTI port device receives a busy or reorder tone.

CTI Route Point

Another type of device controllable with TAPI is a CTI route point. CTI route points allow Cisco TAPI applications to redirect incoming calls with an infinite queue depth. This allows incoming calls to avoid busy signals.

CTI route point devices have an address capability flag of LINEADDRCAPFLAGS_ROUTEPOINT. When your application opens a line of this type, it can handle any incoming call by disconnecting, accepting, or redirecting the call to some other directory number. Redirection decisions can be based on caller ID information, time of day, or other information available to the program.

Compatibility

The Cisco TAPI service provider is a TAPI 2.1 service provider.

When developing an application, be sure to only use functions supported by the Cisco TAPI service provider. For example, transfer is supported, but fax detection is not. If an application requires a media or bearer mode that is not supported, then it will not work as expected.

TAPI Function Lists

Table 1-1 TAPI Line Functions 

TAPI Line Functions
lineAccept, page 2-3
lineAddProvider, page 2-4
lineAddToConference, page 2-5
lineAnswer, page 2-5
lineBlindTransfer, page 2-6
lineCallbackFunc, page 2-7
lineClose, page 2-8
lineCompleteTransfer, page 2-8
lineConfigProvider, page 2-9
lineDeallocateCall, page 2-10
lineDevSpecific, page 2-10
lineDial, page 2-11
lineDrop, page 2-12
lineGenerateDigits, page 2-12
lineGenerateTone, page 2-13
lineGetAddressCaps, page 2-15
lineGetAddressID, page 2-16
lineGetAddressStatus, page 2-17
lineGetCallInfo, page 2-17
lineGetCallStatus, page 2-18
lineGetConfRelatedCalls, page 2-18
lineGetDevCaps, page 2-19
lineGetID, page 2-20
lineGetLineDevStatus, page 2-21
lineGetMessage, page 2-22
lineGetNewCalls, page 2-23
lineGetNumRings, page 2-24
lineGetProviderList, page 2-24
lineGetRequest, page 2-25
lineGetStatusMessages, page 2-26
lineGetTranslateCaps, page 2-27
lineHandoff, page 2-28
lineHold, page 2-29
lineInitialize, page 2-29
IlineInitializeEx, page 2-30
lineMakeCall, page 2-31
lineMonitorDigits, page 2-32
lineMonitorTones, page 2-33
lineNegotiateAPIVersion, page 2-34
lineNegotiateExtVersion, page 2-35
lineOpen, page 2-36
linePrepareAddToConference, page 2-37
lineRedirect, page 2-39
lineRegisterRequestRecipient, page 2-39
lineRemoveProvider, page 2-40
lineSetAppPriority, page 2-41
lineSetCallPrivilege, page 2-42
lineSetNumRings, page 2-43
lineSetStatusMessages, page 2-44
lineSetTollList, page 2-45
lineSetupConference, page 2-46
lineSetupTransfer, page 2-47
lineShutdown, page 2-48
lineTranslateAddress, page 2-48
lineTranslateDialog, page 2-50
lineUnhold, page 2-51

Table 1-2 TAPI Line Messages Functions 

TAPI Line Messages Functions
LINE_APPNEWCALL, page 2-52
LINE_CALLINFO, page 2-53
LINE_CALLSTATE, page 2-53
LINE_CLOSE, page 2-56
LINE_CREATE, page 2-57
LINE_DEVSPECIFIC, page 2-57
LINE_GENERATE, page 2-58
LINE_LINEDEVSTATE, page 2-59
LINE_MONITORDIGITS, page 2-60
LINE_REPLY, page 2-61
LINE_REQUEST, page 2-62

Table 1-3 TAPI Line Device Structures Functions

TAPI Line Device Structures Functions
LINEADDRESSCAPS, page 2-64
LINEADDRESSSTATUS, page 2-67
LINEAPPINFO, page 2-67
LINECALLINFO, page 2-68
LINECALLLIST, page 2-70
LINECALLPARAMS, page 2-71
LINECALLSTATUS, page 2-75
LINECARDENTRY, page 2-75
LINECOUNTRYENTRY, page 2-76
LINECOUNTRYLIST, page 2-78
LINEDEVCAPS, page 2-78
LINEDEVSTATUS, page 2-80
LINEEXTENSIONID, page 2-80
LINEGENERATETONE, page 2-81
LINEINITIALIZEEXPARAMS, page 2-82
LINELOCATIONENTRY, page 2-83
LINEMESSAGE, page 2-85
LINEMONITORTONE, page 2-86
LINEPROVIDERENTRY, page 2-87
LINEPROVIDERLIST, page 2-87
LINEREQMAKECALL, page 2-88
LINETRANSLATECAPS, page 2-89
LINETRANSLATEOUTPUT, page 2-91

Table 1-4 TAPI Phone Functions

TAPI Phone Functions
phoneCallbackFunc, page 2-93
phoneClose, page 2-94
phoneGetDevCaps, page 2-94
phoneGetDisplay, page 2-95
phoneGetLamp, page 2-95
phoneGetMessage, page 2-96
phoneGetRing, page 2-97
phoneGetStatusMessages, page 2-98
phoneInitialize, page 2-99
phoneInitializeEx, page 2-100
phoneNegotiateAPIVersion, page 2-102
phoneOpen, page 2-103
phoneSetDisplay, page 2-104
phoneSetLamp, page 2-105
phoneSetStatusMessages, page 2-106
phoneShutdown, page 2-108

Table 1-5 TAPI Phone Messages Functions

TAPI Phone Messages Functions
PHONE_BUTTON, page 2-109
PHONE_CLOSE, page 2-111
PHONE_CREATE, page 2-112
PHONE_REPLY, page 2-113
PHONE_STATE, page 2-113

Table 1-6 TAPI Phone Structure Functions

TAPI Phone Structure Functions
PHONECAPS, page 2-115
PHONEINITIALIZEEXPARAMS, page 2-116
PHONEMESSAGE, page 2-117
VARSTRING, page 2-118

Table 1-7 Wave Functions

Wave Functions
waveOutOpen, page 2-120
waveOutClose, page 2-121
waveOutGetDevCaps, page 2-122
waveOutGetID, page 2-122
waveOutPrepareHeader, page 2-123
waveOutUnprepareHeader, page 2-123
waveOutGetPosition, page 2-124
waveOutWrite, page 2-125
waveOutReset, page 2-125
waveInOpen, page 2-126
waveInClose, page 2-127
waveInGetID, page 2-127
waveInPrepareHeader, page 2-128
waveInUnprepareHeader, page 2-129
waveInGetPosition, page 2-129
waveInAddBuffer, page 2-130
waveInStart, page 2-130
waveInReset, page 2-131

Cisco Specific Function List

Table 1-8 Cisco Specific TAPI function list

Cisco Functions	Synopsis
CiscoLineDevSpecific, page 3-2	The CiscoLineDevSpecific class is the parent class to the following four classes.
Message Waiting, page 3-3	The CiscoLineDevSpecificMsgWaiting class is used to turn on or off the message waiting lamp for the line specified by the hLine parameter.
Message Waiting Dirn, page 3-3	The CiscoLineDevSpecificMsgWaiting class is used to turn on or off the message waiting lamp for the line specified by a parameter and is independent of the hLine parameter.
Audio Stream Control, page 3-4	The CiscoLineDevSpecificUserControlRTPStream class is used to control the audio stream of a line.
Messages, page 3-7	The application receives LINE_DEVSPECIFIC messages to signal when to stop and start streaming RTP audio.