Cisco TAPI Developer Guide for Cisco CallManager 4.0(1)
Overview
Downloads: This chapterpdf (PDF - 218.0KB) The complete bookPDF (PDF - 2.62MB) | Feedback

Overview

Table Of Contents

Overview

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

Forwarding

Extension Mobility Support

Directory Change Notification Handling

Monitoring Call Park Directory Numbers

Multiple CiscoTSP

Compatibility

XSI Object Pass Through


Overview


This chapter outlines the key concepts that are involved in using Cisco TAPI and lists all the functions that are available in the Cisco TAPI implementation for Cisco CallManager Release 4.0(1):

Architecture

Call Control

CTI Port

CTI Route Point

CTI Manager (Cluster Support)

Supported Device Types

Forwarding

Extension Mobility Support

Monitoring Call Park Directory Numbers

Multiple CiscoTSP

Compatibility

XSI Object Pass Through

Architecture

The Cisco TAPI service provider that is shipped with Cisco CallManager 4.0(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

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 application terminates the audio stream. Ordinarily, this occurs 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. Because 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 that is 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. The basis for redirection decisions can be caller ID information, time of day, or other information that is available to the program.

CTI Manager (Cluster Support)

The CTI Manager, along with the Cisco TSP, provide an abstraction of the Cisco CallManager cluster that allows TAPI applications to access Cisco CallManager resources and functionality without being aware of any specific Cisco CallManager. The Cisco CallManager cluster abstraction also enhances the failover capability of CTI Manager resources. A failover 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 reopening 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 reopened 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 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 graceful re-homing process ensures 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 finish 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 successfully re-homes 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, no call survivability exists; however, media streams that are already connected between devices will survive. Calls in the process of being set up or modified (transfer, conference, redirect) simply get 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 that the application opened. Cisco TSP then connects to a backup CTIManager. When a connection to a backup CTI Manager is established and the device or line successfully reopens, 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 CTI Manager closes the provider, calls at CTI ports and route points that have not yet been terminated get redirected to the Call Forward On Failure (CFF) number that has been configured for them.

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.)

7902

7905

7910

7912

7914

7935

7940

7960

7965

7970

CTI Route Points

CTI Ports

VG248 Analog Devices

ATA186 Analog Devices

Forwarding

CiscoTSP now provides 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 successfully complete. These events also get 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.

Extension Mobility Support

Extension Mobility, a Cisco CallManager feature, allows a user to log in and log out of a phone. Cisco CallManager Extension Mobility loads a user Device Profile (including line, speed dial numbers, and so on) 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 that are 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 get restored. For a non-controlled device, the application perceives a PHONE_REMOVE or LINE_REMOVE message. For a controlled device, it perceives 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 Cisco CallManager system administrator deletes the current user, 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 application called the phoneInitialize function 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 does not generate.


Monitoring Call Park Directory Numbers

The CiscoTSP supports monitoring calls on lines that represent Cisco 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 get reported to the application. The application cannot perform any call control functions on any calls at a Call Park DN.

To open Call Park DN lines, you must check the Monitor Call Park DNs check box in the Cisco CallManager User Administration for the TSP user. Otherwise, the application will not perceive any of the Call Park DN lines upon initialization.

Multiple CiscoTSP

In the Cisco TAPI solution, the TAPI application and the CiscoTSP get installed on the same machine. The Cisco TAPI application and the CiscoTSP do not directly interface with each other. A layer written by Microsoft sits between the TAPI application and the CiscoTSP. This layer, known as 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.

Consider an example. Assume that CiscoTSP1 exposes 100 lines, and CiscoTSP2 exposes 100 lines. In the single CiscoTSP architecture where CiscoTSP1 is the only CiscoTSP that is 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, where 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 the lines and inform the application that it now supports 200 lines. The application communicates with TAPISRV, and TAPISRV takes care of communicating with the correct CiscoTSP.

Ensure that each CiscoTSP is configured with a different username and password that you administer in the Cisco CallManager Directory. Configure each user in the Directory so devices that are associated with each user do not overlap. Each CiscoTSP in the multiple CiscoTSP system does 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 how multiple CiscoTSPs connect to a single CTI manager and use the functionality of multiple Cisco CallManagers.

Figure 1-3 CTI Manager

Compatibility

The Cisco TAPI Service Provider serves as a TAPI 2.1 service provider.

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

XSI Object Pass Through

XSI-enabled IP phones allow applications to directly communicate with the phone and access XSI features, such as manipulate display, get user input, play tone, and so on. In order to allow TAPI applications access to the XSI capabilities without having to set up and maintain an independent connection directly to the phone, TAPI provides the ability to send the device data through the CTI interface. This feature is exposed as a CiscoTSP device-specific extension.

Only PhoneDevSpecificDataPassthrough request is supported for the IP phone devices.