Cisco TAPI Developer Guide for Cisco CallManager 3.3(2), TAPI version 2.1
Overview
Downloads: This chapterpdf (PDF - 213.0KB) The complete bookPDF (PDF - 2.14MB) | Feedback

Overview

Table Of Contents

Overview

Forwarding Enhancement

Multiple CiscoTSP

Compatibility

Architecture

Call Control

First-Party Call Control

Third-Party Call Control

CTI Port

CTI Route Point

CTI Manager (Cluster Support)

Cisco CallManager Failure

Call Survivability

CTI Manager Failure

Cisco TAPI Application Failure

Supported Device Types

Extension Mobility Support

Directory Change Notification Handling

Monitoring Call Park Directory Numbers


Overview


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 Release 3.3(2):

CTI Manager

Architecture

Call Control

CTI Port

CTI Route Point

CTI Manager (Cluster Support)

Supported Device Types

Extension Mobility Support

Directory Change Notification Handling

Monitoring Call Park Directory Numbers

Forwarding Enhancement

CiscoTSP 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 Cisco 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 Cisco 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 CiscoTSPs 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 Cisco TSP 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-1 CTI Manager

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.

Architecture

The Cisco TAPI service provider shipped with Cisco CallManager 3.3(2) is TAPI version 2.1. Figure 1-2 shows how various Cisco components fit into the Microsoft Windows NT telephony and wave architectures.

Figure 1-2 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 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 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.

CTI Manager (Cluster Support)

The CTI Manager, along with the Cisco TSP, 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-3 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, Cisco TSP 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 Cisco TSP to the TAPI application. If for some reason the device or lines cannot be opened, even when all the Cisco CallManagers come back are 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 Cisco TSP 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, Cisco TSP sends a PHONE_STATE (PHONESTATE_SUSPEND) message and a LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) message for every phone and line device opened by the application. Cisco TSP 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 Cisco TSP sends a PHONE_STATE (PHONESTATE_RESUME) or LINE_LINEDEVSTATE (LINEDEVSTATE_INSERVICE) message to the TAPI application. If the Cisco TSP is unsuccessful in opening the device or line for a CTI Port or Route Point, the Cisco TSP closes the device or line by sending the appropriate PHONE_CLOSE or LINE_CLOSE message to the TAPI application.

If devices are added to or removed from the user while the CTI manager is down, Cisco TSP generates PHONE_CREATE/LINE_CREATE or PHONE_REMOVE/LINE_REMOVE events respectively when connection to a backup CTI Manager is established.

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.

Supported Device Types

CiscoTSP supports the following device types:

30 SP+ (this device has spurious offhook problems, not recommended)

12 SP+ (this device has spurious offhook problems, not recommended)

12 SP (this device has spurious offhook problems, not recommended)

7910

7960

7940

CTI Route Points

CTI Ports

VG248 Analog Devices

ATA186 Analog Devices

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.

Cisco TSP 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 TSP user 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 Cisco TSP sends notification events when a device has been added to or removed from the user's controlled device list in the directory. Cisco TSP sends events when the user is deleted from the Cisco CallManager Administration pages.

Cisco TSP 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, Cisco TSP generates a LINE_CLOSE and PHONE_CLOSE message for each open line and open phone. After doing this, it sends a LINE_REMOVE and PHONE_REMOVE message for all lines and phones.


Note Cisco TSP 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). If you program against the LDAP directory, change notification is not generated.


Monitoring Call Park Directory Numbers

The CiscoTSP supports monitoring calls on lines that represent CallManager Call Park Directory Numbers (Call Park DNs). The CiscoTSP uses a device-specific extension in the LINEDEVCAPS structure that allows TAPI applications to differentiate Call Park DN lines from other lines. If an application opens a Call Park DN line, all calls that are parked to the Call Park DN are reported to the application. The application cannot perform any call control functions on any of the calls at a Call Park DN.

In order to open Call Park DN lines, the Monitor Call Park DNs checkbox in the CallManager User Administration for the TSP user must be checked. Otherwise, the application will not see any of the Call Park DN lines upon initialization.