Cisco CallManager 3.1 TAPI Developer Guide
Cisco TAPI Overview
Downloads: This chapterpdf (PDF - 238.0KB) The complete bookPDF (PDF - 1.96MB) | Feedback

Cisco TAPI Overview

Table Of Contents

Cisco TAPI Overview

Introduction

Architecture

Changes from CiscoTSP 3.0 to CiscoTSP 3.1

Line In-Service/Out-of-Service

LINE_CALLINFO

Call Control

First-Party Call Control

Third-Party Call Control

CTI Port

CTI Route Point

Compatibility

CiscoTSP 3.1 enhancements

CTI Manager (Cluster Support)

Cisco CallManager Failure

Call Survivability

CTI Manager Failure

Cisco TAPI Application Failure

Extension Mobility Support

Directory Change Notification Handling

New or Changed Cisco TAPI Entities

Forwarding Enhancement

Multiple CiscoTSP

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

Changes from CiscoTSP 3.0 to CiscoTSP 3.1

Call Control

CTI Port

CTI Route Point

Compatibility

CiscoTSP 3.1 enhancements

TAPI Function Lists

Cisco Specific Function List

Architecture

The Cisco TAPI service provider shipped with Cisco CallManager 3.1(1) is TAPI version 2.1. 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)

Changes from CiscoTSP 3.0 to CiscoTSP 3.1

This section describes two important changes in CiscoTSP version 3.1, a change in the way CiscoTSP behaves when an application opens a device line and changes in the LINE_CALLINFO message function.

Line In-Service/Out-of-Service

In CiscoTSP 3.0, by default a line is in service when opened. With cluster abstraction (the CTI Manager) in CiscoTSP 3.1, after an application successfully opens a line or phone, the line or phone may be out-of-service. Immediately after opening the device, the application should check its status. If the device is out-of-service, the application should wait for an in-service message before initiating a TAPI request that results in Cisco CallManager interaction. If an application initiates such a request while the device is out-of-service, CiscoTSP responds with a resource unavailable message.

This is a change from the behavior in CiscoTSP 3.0. In CiscoTSP 3.0, when a device was successfully opened, it was always in-service.

This change will not be an issue for an application if the application checks the line or phone status immediately after the lineOpen or phoneOpen function call.

LINE_CALLINFO

Added complete support for the fields of the LINE_CALLINFO message in CiscoTSP 3.1.

The LINE_CALLINFO parameter dwCalledID correctly reflects the OrigincalCalledParty information.

Call Control

You can configure the Cisco TAPI Service Provider to provide either first or third-party call control.

You can also configure Cisco TSP to provide both first and 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 to control the audio stream instead of the wave driver, 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

You can use Cisco TAPI to control you CTI route points. 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 only to 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.

CiscoTSP 3.1 enhancements

This section discusses important changes made to the CiscoTSP. These changes include support for fault tolerance and using Cisco CallManager Extension Mobility.

CTI Manager (Cluster Support)

The new CTI Manager, along with the newest version of CiscoTSP, provide an abstraction of the CallManager cluster that allows TAPI applications to access CallManager resources and functionality without being aware of any specific Cisco CallManager. The Cisco CallManager cluster abstraction also enhances the fail-over capability of CTI Manager resources. A fail-over condition occurs when a Cisco CallManager node fails, a CTI Manager fails, or a TAPI application fails.

Figure 1-2 Cluster Support Architecture

Cisco CallManager Failure

When a Cisco CallManager node in a cluster fails, the CTI Manager recovers the affected CTI Ports and Route Points by re-opening these devices on another Cisco CallManager node. When the failure is first detected, CiscoTSP sends a PHONE_STATE (PHONESTATE_SUSPEND) message to the TAPI application.

When the CTI Port/Route Point is successfully re-opened on another Cisco CallManager, CiscoTSP sends a phone PHONE_STATE (PHONESTATE_RESUME) message to the TAPI application. If no Cisco CallManager is available, the CTI Manager waits until an appropriate Cisco CallManager comes back in service and tries to open the device again. The lines on the affected device also go out-of-service and in-service with the corresponding LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) and LINE_LINEDEVSTATE (LINEDEVSTATE_INSERVICE) events sent by CiscoTSP to the TAPI application. If for some reason the device or lines cannot be opened, even when all the Cisco CallManagers come back in service, the devices or lines are closed and CiscoTSP will send PHONE_CLOSE or LINE_CLOSE message to TAPI application.

When a failed Cisco CallManager node comes back in service, CTI Manager "re-homes" the affected CTI Ports or Route Points back to their original Cisco CallManager. The re-homing process is graceful in that the re-homing only starts when calls are no longer being processed or are active on the affected device. For this reason, the re-homing process may not be done for a long time, especially for Route Points, which can handle many simultaneous calls.

When a Cisco CallManager node fails, phones currently re-home to another Cisco CallManager node in the same cluster. If a TAPI application has a phone device opened and the phone goes through the re-homing process, CTI Manager automatically recovers that device and CiscoTSP sends a PHONE_STATE (PHONESTATE_SUSPEND) message to the TAPI application. When the phone has successfully re-homed to another Cisco CallManager node, CiscoTSP sends a PHONE_STATE (PHONESTATE_RESUME) message to the TAPI application. The lines on the affected device also go out-of-service and in-service and CiscoTSP sends LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) and LINE_LINEDEVSTATE (LINEDEVSTATE_INSERVICE) messages to the TAPI application.

Call Survivability

When a device or Cisco CallManager failure occurs, there is no call survivability. However, media streams already connected between devices will survive. Calls in the process of being set up or modified (transfer, conference, redirect, etc.) are simply dropped.

CTI Manager Failure

When a primary CTI Manager fails, CiscoTSP sends a PHONE_STATE (PHONESTATE_SUSPEND) message and a LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) message for every phone and line device opened by the application. CiscoTSP then connects to a backup CTIManager. When a connection to a backup CTI Manager is established and the device or line is successfully re-opened, the CiscoTSP sends a PHONE_STATE (PHONESTATE_RESUME) or LINE_LINEDEVSTATE (LINEDEVSTATE_INSERVICE) message to the TAPI application. If the CiscoTSP is unsuccessful in opening the device or line for a CTI Port or Route Point, the CiscoTSP closes the device or line by sending the appropriate PHONE_CLOSE or LINE_CLOSE message to the TAPI application.

While the CTI manager is down and devices are added to or removed from the user, CiscoTSP generates PHONE_CREATE/LINE_CREATE or PHONE_REMOVE/LINE_REMOVE events.

Cisco TAPI Application Failure

When a Cisco TAPI application fails, that is, the provider is closed by CTI Manager, calls at CTI ports and route points that have not yet been terminated are redirected to the Call Forward On Failure (CFF) number that has been configured for them. New calls into CTI Ports and Route Points that are not opened by an application are also routed to their CFF number.

Extension Mobility Support

Extension Mobility is a Cisco CallManager feature that allows a user to log in and log out of a phone. Cisco CallManager Extension Mobility loads a user's Device Profile (including line, speed dial numbers, etc...) onto the phone when the user logs in.

CiscoTSP recognizes a user who is logged into a device as the TSPUser.

Using Cisco CallManager Administration pages, you can associate a list of controlled devices with a user.

When the TSPUser logs into the device, the lines listed in the user's Extension Mobility profile are placed on the phone device and lines previously on the phone are removed. If the device is not in the controlled device list for the TSPUser, the application receives a PHONE_CREATE or LINE_CREATE message. If the device is in the controlled list, the application receives a LINE_CREATE message for the added line and a LINE_REMOVE message for the removed line.

When the user logs out, the original lines are restored. For a non-controlled device, the application sees a PHONE_REMOVE or LINE_REMOVE message. For a controlled device, it sees a LINE_CREATE message for an added line and a LINE_REMOVE message for a removed line.

Directory Change Notification Handling

The CiscoTSP sends notification events when a device has been added to or removed from the user's controlled device list in the directory. CiscoTSP sends events when the user is deleted from the Cisco CallManager Administration pages.

CiscoTSP sends a LINE_CREATE or PHONE_CREATE message when a device is added to a users' control list.

It sends a LINE_REMOVE or PHONE_REMOVE message when a device is removed from the user's controlled list or the device is removed from database.

When the current user is deleted by the Cisco CallManager system administrator, CiscoTSP generates a LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE)/PHONE_STATE (PHONESTATE_SUSPEND) message for each open line. If the line is not open, then the application will not be able to open.


Note CiscoTSP generates PHONE_REMOVE/PHONE_CREATE messages only if the phoneInitialize function was called by the application earlier.



Note Change notification is generated if the device is added to/removed from the user by using Cisco CallManager Administration pages or Bulk Administration Tool (BAT). Change notification will not be generated if you program against the LDAP directory.


New or Changed Cisco TAPI Entities

Several Cisco TAPI device structures, functions, and messages have been added or changed in this version to enhance overall functionality. This table lists each new or modified entity and its type.

Table 1-1 New or changed Cisco TAPI Structures, Functions and Messages

Entity
Type

LINE_ADDRESSSTATE, page 2-54

TAPI Line Message

LINE_REMOVE, page 2-64

TAPI Line Message

LINEADDRESSCAPS, page 2-67

TAPI Line Device Structure

LINEFORWARD, page 2-84

TAPI Line Device Structure

LINEFORWARDLIST, page 2-86

TAPI Line Device Structure

PHONE_REMOVE, page 2-117

TAPI Phone Message

lineForward, page 2-12

TAPI Line Function


Forwarding Enhancement

Cisco TSP has added support for the lineForward() request to set and clear ForwardAll information on a line. This will allow TAPI applications to set the Call Forward All setting for a particular line device. Activating this feature will allow users to set the call forwarding Unconditionally to a forward destination.

CiscoTSP sends LINE_ADDRESSSTATE messages when lineForward() requests are successfully completed. These events will also be sent when call forward indications are obtained from the CTI, indicating that a change in forward status has been received from a third-party, such as the Cisco CallManager Administration or another application setting call forward all.

Multiple CiscoTSP

In the Cisco TAPI solution, the TAPI application and the CiscoTSP are installed on the same machine. The TAPI application and the CiscoTSP do not directly interface with each other. There is a layer written by Microsoft that sits between the TAPI application and the CiscoTSP. This layer is known as TAPISRV. TAPISRV allows the installation of multiple TSPs on the same machine and it hides that fact from the TAPI application. The only difference to the TAPI application is that it is now informed that there are more lines that it can control.

Let's look at an example. Let's assume that CiscoTSP1 exposes 100 lines and CiscoTSP2 exposes 100 lines. In the single CiscoTSP architecture where CiscoTSP1 is the only CiscoTSP installed, CiscoTSP1 would tell TAPISRV that it supports 100 lines and TAPISRV would tell the application that it can control 100 lines. In the multiple CiscoTSP architecture, both Cisco TSPs are installed. This means that CiscoTSP1 would tell TAPISRV that it supports 100 lines, and CiscoTSP2 would tell TAPISRV that it supports 100 lines. TAPISRV would add up the lines and tell the application that it now supports 200 lines. Remember, the application communicates with TAPISRV and TAPISRV takes care of communicating with the correct CiscoTSP.

Each CiscoTSP should be configured with a different username and password that you administer in the Cisco CallManager Directory. Each user in the Directory should be configured so that devices associated with each user do not overlap. Each CiscoTSP in the multiple CiscoTSP system do not communicate with each other. Each CiscoTSP in the multiple CiscoTSP system creates a separate CTI connection to the CTI Manager.

Multiple CiscoTSP helps in scalability and higher performance.

The following figure shows that how multiple CiscoTSPs connect to a single CTI manager and use the functionality of multiple Cisco CallManagers.

Figure 1-3 CTI Manager

TAPI Function Lists

This section contains a listing of the TAPI 2.1 functions, messages, and structures supported by the Cisco TAPI Service Provider.

Table 1-2 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

lineForward, page 2-12

lineGenerateDigits, page 2-14

lineGenerateTone, page 2-15

lineGetAddressCaps, page 2-17

lineGetAddressID, page 2-18

lineGetAddressStatus, page 2-19

lineGetCallInfo, page 2-19

lineGetCallStatus, page 2-20

lineGetConfRelatedCalls, page 2-20

lineGetDevCaps, page 2-21

lineGetID, page 2-22

lineGetLineDevStatus, page 2-23

lineGetMessage, page 2-24

lineGetNewCalls, page 2-25

lineGetNumRings, page 2-26

lineGetProviderList, page 2-26

lineGetRequest, page 2-27

lineGetStatusMessages, page 2-28

lineGetTranslateCaps, page 2-29

lineHandoff, page 2-30

lineHold, page 2-31

lineInitialize, page 2-31

IlineInitializeEx, page 2-32

lineMakeCall, page 2-33

lineMonitorDigits, page 2-34

lineMonitorTones, page 2-35

lineNegotiateAPIVersion, page 2-36

lineNegotiateExtVersion, page 2-37

lineOpen, page 2-38

linePrepareAddToConference, page 2-39

lineRedirect, page 2-41

lineRegisterRequestRecipient, page 2-41

lineRemoveProvider, page 2-42

lineSetAppPriority, page 2-43

lineSetCallPrivilege, page 2-44

lineSetNumRings, page 2-45

lineSetStatusMessages, page 2-46

lineSetTollList, page 2-47

lineSetupConference, page 2-48

lineSetupTransfer, page 2-49

lineShutdown, page 2-50

lineTranslateAddress, page 2-50

lineTranslateDialog, page 2-52

lineUnhold, page 2-53






Table 1-7 TAPI Phone Structures

TAPI Phone Structure Functions

PHONECAPS, page 2-121

PHONEINITIALIZEEXPARAMS, page 2-122

PHONEMESSAGE, page 2-123

VARSTRING, page 2-124



Cisco Specific Function List

Table 1-9 outlines the functions that are specific to Cisco TAPI, along with a short description of each function.

Table 1-9 Cisco Specific TAPI Functions

Cisco Functions
Synopsis

CCiscoLineDevSpecific, page 3-2

The CCiscoLineDevSpecific class is the parent class to the following four classes.

Message Waiting, page 3-3

The CCiscoLineDevSpecificMsgWaiting class is used to turn the message waiting lamp on or off for the line specified by the hLine parameter.

Message Waiting Dirn, page 3-3

The CCiscoLineDevSpecificMsgWaiting class is used to turn the message waiting lamp on or off for the line specified by a parameter and is independent of the hLine parameter.

Audio Stream Control, page 3-4

The CCiscoLineDevSpecificUserControlRTPStream class is used to control the audio stream for a line.

Set Status Messages, page 3-7

The application receives LINE_DEVSPECIFIC messages to signal when to stop and start streaming Real Time Protocol (RTP) audio.