This chapter describes the major concepts of Cisco Unified TAPI service provider (Cisco Unified TSP) implementation. It contains the following sections:
•Cisco Unified TSP Overview
•Cisco Unified TSP Concepts
Cisco Unified TSP Overview
The standard TAPI provides an unchanging programming interface for different implementations. The goal of Cisco in implementing TAPI for the Cisco Unified Communications Manager platform remains to conform as closely as possible to the TAPI specification, while providing extensions that enhance TAPI and expose the advanced features of Cisco Unified Communications Manager to applications.
As versions of Cisco Unified Communications Manager and Cisco Unified TSP are released, variances in the API should be minor and should tend in the direction of compliance. Cisco stays committed to maintaining its API extensions with the same stability and reliability, though additional extensions may be provided as new Cisco Unified Communications Manager features become available.
Figure 1-1 shows the architecture of TAPI.
Figure 1-1 Architecture of TAPI Service Process
Note The Cisco TSP is a TAPI 2.1 service provider.
Cisco Unified TSP Concepts
The following are described in this section:
•Basic TAPI Applications
•Cisco TSP Components
•Cisco Wave Drivers
•Cisco TSP Components
See "Basic TAPI Implementation" section on page 5-1 and "Cisco Device-Specific Extensions" section on page 6-1 for lists and descriptions of interfaces and extensions.
Basic TAPI Applications
Microsoft has defined some basic APIs which can be invoked/supported from application code. All Microsoft defined APIs that can be used from the TAPI applications are declared in TAPI.H file. TAPI.H file is a standard library file that is with the VC++/VS2005 Installation. For example, C:\Program Files\Microsoft Visual Studio\VC98\Include\TAPI.H.
To use any specific API which is added or provided by Cisco TSP, the application needs to invoke that API by using the LineDevSpecific API.
LINEINITIALIZEEXPARAMS mLineInitializeExParams;//was declared in TAPI.h files
DWORD dwAPIVersion = 0x20005
// Note hInstance can be NULL
// appstr - value can be given the app name "test program"
bool TapiLineApp::LineInitializeEx(HINSTANCE hInstance, std::string appStr)
unsigned long lReturn = 0;
mLineInitializeExParams.dwTotalSize = sizeof(mLineInitializeExParams);
mLineInitializeExParams.dwOptions = LINEINITIALIZEEXOPTION_USEEVENT;
lReturn = lineInitializeEx (&mhLineApp, hInstance, NULL, appStr.c_str),
return! (lineShutdown (mhLineApp));
Cisco TSP Components
The following are Cisco TSP components:
•CiscoTsp001.tsp - TAPI service implementation provided by Cisco TSP
•CTIQBE over TCP/IP - Cisco protocol used to monitor and control devices and lines
•CTI Manager Service - Manages CTI resources and connections to devices. Exposed to 3rd-party applications via Cisco TSP and/or JTAPI API
Cisco Wave Drivers
Cisco TSP can be configured to provide either first or third-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. AVAudio32.dll implements the wave interfaces for the Cisco wave drivers. In Third-Party Call control, the audio stream termination is done by the actual physical device like an IP phone or a group of IP phones for which your application is responsible.
For information about the installation of the wave drivers, see Installing the Wave Driver, page 4-13.
The TAPI browser is a TAPI debugging application. It can be downloaded from the Microsoft MSDN Web site at ftp://ftp.microsoft.com/developr/TAPI/tb20.zip. The TAPI browser can be used to initialize TAPI, for use by TAPI developers to test a TAPI implementation and to verify that the TSP is operational.
CTI Manager (Cluster Support)
The CTI Manager, along with the Cisco Unified TSP, provide an abstraction of the Cisco Unified Communications Manager cluster that allows TAPI applications to access Cisco Unified Communications Manager resources and functionality without being aware of any specific Cisco Unified Communications Manager. The Cisco Unified Communications Manager cluster abstraction also enhances the failover capability of CTI Manager resources. A failover condition occurs when a node fails, a CTI Manager fails, or a TAPI application fails, as illustrated in Figure 1-2.
Note Cisco does not support CTI device monitoring or call control with 3rd-party devices.
Figure 1-2 Cluster Support Architecture
Cisco Unified Communications Manager Failure
When a Cisco Unified Communications Manager node in a cluster fails, the CTI Manager recovers the affected CTI ports and route points by reopening these devices on another Cisco Unified Communications Manager node. When the failure is first detected, Cisco Unified TSP sends a PHONE_STATE (PHONESTATE_SUSPEND) message to the TAPI application.
When the CTI port/route point is successfully reopened on another Cisco Unified Communications Manager, Cisco Unified TSP sends a phone PHONE_STATE (PHONESTATE_RESUME) message to the TAPI application. If no Cisco Unified Communications Manager is available, the CTI Manager waits until an appropriate Cisco Unified Communications Manager 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 Cisco Unified TSP sends to the TAPI application. If for some reason the device or lines cannot be opened, even when all Cisco Unified Communications Managers come back in service, the system closes the devices or lines, and Cisco Unified TSP will send PHONE_CLOSE or LINE_CLOSE messages to the TAPI application.
When a failed Cisco Unified Communications Manager node comes back in service, CTI Manager "re-homes" the affected CTI ports or route points to their original Cisco Unified Communications Manager. 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 Unified Communications Manager node fails, phones currently re-home to another 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 Cisco Unified TSP sends a PHONE_STATE (PHONESTATE_SUSPEND) message to the TAPI application. When the phone successfully re-homes to another Cisco Unified Communications Manager node, Cisco Unified TSP 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 Unified TSP sends LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) and LINE_LINEDEVSTATE (LINEDEVSTATE_INSERVICE) messages to the TAPI application.
When a device or Cisco Unified Communications Manager 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 Unified 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 Unified 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 Unified TSP sends a PHONE_STATE (PHONESTATE_RESUME) or LINE_LINEDEVSTATE (LINEDEVSTATE_INSERVICE) message to the TAPI application. If the Cisco Unified TSP is unsuccessful in opening the device or line for a CTI port or route point, the Cisco Unified TSP closes the device or line by sending the appropriate PHONE_CLOSE or LINE_CLOSE message to the TAPI application.
After Cisco Unified TSP is connected to the backup CTIManager, Cisco Unified TSP will not reconnect to the primary CTIManager until the connection is lost between Cisco Unified TSP and the backup CTIManager.
If devices are added to or removed from the user while the CTI Manager is down, Cisco Unified TSP generates PHONE_CREATE/LINE_CREATE or PHONE_REMOVE/LINE_REMOVE events, respectively, when connection to a backup CTI Manager is established.
Cisco Unified TAPI Application Failure
When a Cisco TAPI application fails (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. The system routes new calls into CTI Ports and Route Points that are not opened by an application to their CFNA number.
Cisco Unified TSP supports the Cisco baseline for baselining of Quality of Service (QoS). Cisco Unified TSP marks the IP DSCP (Differentiated Services Code Point) for QBE control signals that flow from TSP to CTI with the value of the Service parameter "DSCP IP for CTI Applications" that CTI sends in the ProviderOpenCompletedEvent. The Cisco TAPI Wave driver marks the RTP packets with the value that CTI sends in the StartTransmissionEvent. The system stores the DSCP value received in the StartTransmissionEvent in the DevSpecific portion of the LINECALLINFO structure, and fires the LINECALLINFOSTATE_DEVSPECIFIC event with the QoS indicator.
Note QoS information is not available if you begin monitoring in the middle of a call because existing calls do not have an RTP event.
Presentation Indication (PI)
There is a need to separate the presentability aspects of a number (calling, called, and so on) from the actual number itself. For example, when the number is not to be displayed on the IP phone, the information might still be needed by another system, such as Unity VM. Hence, each number/name of the display name needs to be associated with a Presentation Indication (PI) flag, which will indicate whether the information should be displayed to the user or not.
You can set up this feature as follows:
On a Per-Call Basis
You can use Route Patterns and Translation Patterns to set or reset PI flags for various partyDNs/Names on a per-call basis. If the pattern matches the digits, the PI settings that are associated with the pattern will be applied to the call information.
On a Permanent Basis
You can configure a trunk device with "Allow" or "Restrict" options for parties. This will set the PI flags for the corresponding party information for all calls from this trunk.
Cisco Unified TSP supports this feature. If calls are made via Translation patterns with all of the flags set to Restricted, the system sends the CallerID/Name, ConnectedID/Name, and RedirectionID/Name to applications as Blank. The system also sets the LINECALLPARTYID flags to Blocked if both the Name and Party number are set to Restricted.
When developing an application, be sure only to use functions that the Cisco TAPI Service Provider supports. For example, the Cisco TAPI Service Provider supports transfer, but not fax detection. If an application requires an unsupported media or bearer mode, the application will not work as expected.
Cisco Unified TSP does not support TAPI 3.0 applications.
You can configure Cisco Unified TSP to provide first- or third-party call control.
First-Party Call Control
In first-party call control, the application terminates the audio stream. Ordinarily, this occurs by 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 Unified Communications Manager. 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.
Note Cisco does not support CTI device monitoring or call control with 3rd-party devices.
For first-party call control, a CTI port device must exist in the Cisco Unified Communications Manager. 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 who calls the directory number that is associated with that CTI port device receives a busy or reorder tone.
The IP address and UDP port number is either specified statically (the same IP address and UDP port number is used for every call) or dynamically. By default, CTI ports use static registration.
Dynamic Port Registration
Dynamic Port Registration enables applications to specify the IP address and UDP port number on a call-by-call basis. Currently, the IP address and UDP port number are specified when a CTI port registers and is static through the life of the registration of the CTI port. When media is requested to be established to the CTI port, the system uses the same static IP address and UDP port number for every call.
An application that wants to use Dynamic Port Registration must specify the IP address and UDP port number on a call before invoking any features on the call. If the feature is invoked before the IP address and UDP port number are set, the feature will fail, and the call state will be set depending on when the media time-out occurs.
CTI Route Point
You can use Cisco Unified TAPI to control CTI route points. CTI route points allow Cisco Unified 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.
Media Termination at Route Point
The Media Termination at Route Point feature lets applications terminate media at route points. This feature enables applications to pass the IP address and port number where they want the call at the route point to have media established.
The system supports the following features at route points:
•Multiple Active Calls
Monitoring Call Park Directory Numbers
The Cisco Unified TSP supports monitoring calls on lines that represent Call Park Directory Numbers (Call Park DNs). The Cisco Unified TSP 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 Cisco Unified Communications Manager User Administration for the Cisco Unified TSP user. Otherwise, the application will not perceive any of the Call Park DN lines upon initialization.
Multiple Cisco Unified TSPs
In the Cisco Unified TAPI solution, the TAPI application and Cisco Unified TSP get installed on the same machine. The Cisco Unified TAPI application and Cisco Unified TSP do not directly interface with each other. A layer written by Microsoft sits between the TAPI application and Cisco Unified TSP. This layer, known as TAPISRV, allows the installation of multiple TSPs on the same machine, and it hides that fact from the Cisco Unified 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 Cisco Unified TSP1 exposes 100 lines, and Cisco Unified TSP2 exposes 100 lines. In the single Cisco Unified TSP architecture where Cisco Unified TSP1 is the only Cisco Unified TSP that is installed, Cisco Unified TSP1 would tell TAPISRV that it supports 100 lines, and TAPISRV would tell the application that it can control 100 lines. In the multiple Cisco Unified TSP architecture, where both Cisco Unified TSPs are installed, this means that Cisco Unified TSP1 would tell TAPISRV that it supports 100 lines, and Cisco Unified TSP2 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 Cisco Unified TSP.
Ensure that each Cisco Unified TSP is configured with a different username and password that you administer in the Cisco Unified Communications Manager Directory. Configure each user in the Directory, so devices that are associated with each user do not overlap. Each Cisco Unified TSP in the multiple Cisco Unified TSP system does not communicate with the others. Each Cisco Unified TSP in the multiple Cisco Unified TSP system creates a separate CTI connection to the CTI Manager as shown in Figure 1-3. Multiple Cisco Unified TSPs help in scalability and higher performance.
Figure 1-3 Multiple Cisco Unified TSPs Connect to CTI Manager
CTI Device/Line Restriction
With CTI Device/Line restriction implementation, a CTIRestricted flag is be placed on device or line basis. When a device is restricted, it assumes that all its configured lines are restricted.
Cisco Unified TSP does not report any restricted devices and lines back to application. When a CTIRestricted flag is changed from Cisco Unified Communications Manager Administration, Cisco Unified TSP treats it as normal device/line add or removal.