Cisco TAPI Developer Guide for Cisco CallManager 4.1(2)
Preface
Downloads: This chapterpdf (PDF - 345.0KB) The complete bookPDF (PDF - 2.65MB) | Feedback

Preface

Table Of Contents

Preface

Introduction

Purpose

Audience

New and Changed Information

CiscoTSP 4.1(2) Enhancements

FAC and CMC Support

CTI Port Third-Party Monitoring

QSIG Path Replacement

Progressing Call State

Transfer/Conference Destination DN in Setup Request Support

Modified CiscoTSP 4.1(2) Entities

CiscoTSP 4.0 Enhancements

Dynamic Port Registration

Media Termination at Route Point

Redirect Support for Blind Transfer

Redirect Set Original Called ID

Multiple Calls per Line Appearance

Shared Line Appearance

Select Calls

Transfer Changes

Direct Transfer

Conference Changes

Call Join

Privacy Release

Barge and cBarge

TSP Auto Update Functionality

QoS Support

Forwarding Changes

Presentation Indication Flag

Modified CiscoTSP 4.0 Entities

Changes From CiscoTSP 3.3 to CiscoTSP 4.0

Line In-Service or Out-of-Service

LINE_CALLINFO

User Deletion from Directory

Removal of lineDevSpecific() - Swap Hold Setup Transfer

Call Reason Enhancements

Changes to phoneSetDisplay()

CiscoTSP 3.3 Enhancements

Reporting TSP Initialization Problems or Errors to the Application

New or Changed CiscoTSP 3.3 Entities

Changes From CiscoTSP 3.2 to CiscoTSP 3.3

User Deletion From Directory

Opening Two Lines on One CTI Port Device

CiscoTSP 3.2 Enhancements

Changes From CiscoTSP 3.1 to CiscoTSP 3.2

CiscoTSP 3.1 Enhancements

Changes From CiscoTSP 3.0 to CiscoTSP 3.1

Line In Service or Out of Service

LINE_CALLINFO

New or Changed CiscoTSP 3.1 Entities

Organization

Related Documentation

Required Software

Supported Windows Platforms

Conventions

Obtaining Documentation

Cisco.com

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Cisco Technical Support Website

Submitting a Service Request

Definitions of Service Request Severity

Obtaining Additional Publications and Information


Preface


This chapter introduces Cisco Telephony Application Programmer's Interface (TAPI) implementation, describes the purpose of this document, and outlines the required software. The chapter includes the following topics:

Introduction

Purpose

Audience

New and Changed Information

Organization

Related Documentation

Required Software

Supported Windows Platforms

Conventions

Obtaining Documentation

Documentation Feedback

Obtaining Technical Assistance

Obtaining Additional Publications and Information

Introduction

Telephony Application Programmer's Interface (TAPI) comprises the set of classes and principles of operation that constitute a telephony application programming interface. TAPI implementations provide the interface between computer telephony applications and telephony services. The Cisco CallManager includes a TAPI Service Provider (Cisco TSP). The Cisco TAPI Service Provider allows developers to create customized IP telephony applications for Cisco users; for example, voice mail with other TAPI compliant systems, automatic call distribution (ACD), and caller ID screen pops. Cisco TSP enables the Cisco IP Telephony system to understand commands from the user-level application such as Cisco SoftPhone via the operating system.

The Cisco TAPI implementation uses the Microsoft TAPI v2.1 specification and supplies extension functions to support Cisco IP Telephony Solutions. To enable a Cisco TAPI-based solution, you must have the following:

TAPI support/service running on the operating system

A TAPI-based software application

A Cisco IP Telephony phone system


Note Using Cisco TAPI 2.1 TSP via the TAPI 3.x compatibility layer is not supported.


Purpose

This document describes the Cisco TAPI implementation by detailing the functions that comprise the implementation software and illustrating how to use these functions to create applications that support the Cisco IP Telephony hardware, software, and processes. Use this document with the Cisco CallManager manuals to develop applications.

A primary goal of a standard Application Programming Interface (API) such as TAPI specifies providing an unchanging programming interface under which varied implementations may stand. Cisco's goal in implementing TAPI for the Cisco CallManager 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 CallManager to applications.

As new versions of Cisco CallManager and the Cisco TSP are released, variances in the API should be very 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 CallManager features become available

Audience

Cisco intends this document to be for use by telephony software engineers who are developing Cisco telephony applications that require TAPI. This document assumes that the engineer is familiar with both the C or C++ languages and the Microsoft TAPI specification.

New and Changed Information

This section describes any new features and or changes for Cisco TAPI that are pertinent to the specified release of Cisco CallManager.

CiscoTSP 4.1(2) Enhancements

The following describe the CiscoTSP enhancements for Cisco CallManager 4.1(2).

FAC and CMC Support

There are two CallManager features, Forced Authorization Code (FAC) and Client Matter Code (CMC), that the CiscoTSP has been enhanced to support and interact with. The FAC feature allows the System Administrator the ability to require users to enter an authorization code in order to reach certain dialed numbers. The CMC feature allows the System Administrator the ability to require users to enter a client matter code in order to reach certain dialed numbers.

The CallManager alerts a user of a phone that a FAC or CMC must be entered by sending a "ZipZip" tone to the phone which the phone in turn plays to the user. The CiscoTSP will send a new LINE_DEVSPECIFIC event to the application whenever a "ZipZip" tone is to be played by the application. This can be used by the application to indicate when a FAC or CMC is required. In order for an application to start receiving the new LINE_DEVSPECIFIC event, it must perform the following steps:

lineOpen with dwExtVersion set to 0x00050000 or higher

lineDevSpecific - Set Status Messages to turn on the Call Tone Changed device specific events

The FAC or CMC code can be entered by the application using the lineDial() API. The code may be entered in its entirety or it may be entered one digit at a time. An application may also enter the FAC and CMC code in the same string as long as they are separated by a "#" character and also ended with a "#" character. The "#" character at the end is optional as it only serves to indicate to the CallManager that dialing is complete.

If an application does a lineRedirect() or a lineBlindTransfer() to a destination that requires a FAC or CMC, then the TSP will return an error. The error returned by the TSP indicates whether a FAC, CMC, or both is required. The TSP supports two new lineDevSpecific() functions, one for Redirect and one for BlindTransfer, that will allow an application to enter a FAC or CMC, or both, when either Redirecting or Blind Transferring a call.

CTI Port Third-Party Monitoring

Prior to CiscoTSP 4.1, the TSP allowed TAPI applications to open a CTI port device in first party mode. First party mode means that either the application is terminating the media itself at the CTI port or that the application is using the Cisco Wave Drivers to terminate the media at the CTI port. This is also known as registering the CTI port device.

In all releases prior to CiscoTSP 4.1, there was no way for a TAPI application using the CiscoTSP to open a CTI port in third party mode. Third party mode means that the application is interested in just opening the CTI port device, but it does not want to handle the media termination at the CTI port device. An example of this would be a case where an application would want to open a CTI port in third party mode because it is interested in monitoring a CTI port device that has already been opened/registered by another application in first party mode. Please note that opening a CTI Port in third party mode does not prohibit the application from performing call control operations on the line or on the calls of that line.

In CiscoTSP 4.1, the TSP has been enhanced to allow TAPI applications to open a CTI port device in third party mode. This will be exposed to TAPI applications via a new lineDevSpecific() API. In order to use the new lineDevSpecific() API, the application must negotiate for at least extension version 5.0 and set the high order bit so that the extension version is set to at least 0x80050000.

The TAPI architecture allows two different TAPI applications to be running on the same PC using the same TSP. In this situation, if both applications want to open the CTI port, there could be problems. Therefore, the first application to open the CTI port will control which mode in which the second application is allowed to open the CTI port. In other words, both or all applications running on the same PC, using the same TSP, must open CTI ports in the same mode in order to be successful. If the second application tries to open the CTI port in a mode that is different from the way in which the first application opened it, then the lineDevSpecific() request will fail.

QSIG Path Replacement

CiscoTSP 4.1(2) supports events generated because of the Cisco CallManager QSIG Path Replacement feature.


Note Call information on a tromboned call across a QSIG gateway is not consistent. Due to the limitations in the protocol, the application would see inconsistent values for LINECALLINFO RedirectingID/name and CalledID/Name.


Progressing Call State

CiscoTSP 4.1(2) supports CtiProgressingCallState as a TAPI LINECALLSTATE_UNKNOWN | CLDSMT_CALL_PROGRESSING_STATE (0x01000000). This call state is reported to the application if it has negotiated extension version 0x00050001 during lineOpen. Similar changes are made to report the callStatus when queried using lineGetCallStatus. The call features associated to this call state is just LINE_DROP.

The current cause codes associated with ProgressingCallState are standard Q931 cause codes and the application must be able to decode them if required. The cause codes will be reported only when the application has negotiated extension version 0x00050001 or greater.

Transfer/Conference Destination DN in Setup Request Support

CiscoTSP 4.1(2) is modified to accept the consult DN for TAPI lineSetupTransfer and lineSetupConference requests through LINECALLPARAMS::devSpecificdata. The application has to negotiate extension version 0x00050002 or greater to provide the destination DN in these requests. The support has been added for promptly dialing the consult destinations. The earlier TSP implementation allowed applications to dial the destination DN using lineDial method, which introduces a dial delay for each digit resulting in a delay in establishing a consult call.

Modified CiscoTSP 4.1(2) Entities

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

Entity
Type

LINE_DEVSPECIFIC

TAPI line message

LineDevSpecific

TAPI line function

lineSetupTransfer

TAPI line function

lineSetupConference

TAPI line function


CiscoTSP 4.0 Enhancements

The following describe the CiscoTSP 4.0 enhancements for Cisco CallManager 4.0.

Dynamic Port Registration

The purpose of the Dynamic Port Registration feature is to allow 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 same static IP address and UDP port number is used for every call

This feature allows an application to be able to specify the IP address and UDP port number on a call-by-call basis.

An application that wishes 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 timeout occurs.

Media Termination at Route Point

The purpose of the Media Termination at Route Point feature is to allow applications to 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 following features are supported at route points:

Answer

Multiple active calls

Redirect

Hold

UnHold

Blind Transfer

DTMF Digits

Tones

Redirect Support for Blind Transfer

The purpose of the Redirect support for blind transfer is to eliminate problems arising from the consult call created during a blind transfer in the earlier CiscoTSPs and also bring it in accordance with TAPI specification. This means that lineBlindTransfer() is now properly supported.

Redirect Set Original Called ID

The purpose of the Redirect Set Original Called ID is to allow applications to redirect a call on a line to another destination while allowing the applications to set the OriginalCalledID to any value.

This request can be used to implement the Transfer to Voice Mail feature (TxToVM). Using this feature, the applications can transfer the call on a line directly to another line's voice mailbox. TxToVM can be achieved by specifying the following fields in the above request: voice mail pilot as the destination DN and the DN of the line to whose voice mail box the call needs to be transferred to as the preferredOriginalCalledID.

Multiple Calls per Line Appearance

Maximum Number of Calls

With the current Cisco CallManager 3.3, the maximum number of calls per line appearance (LA) is limited to two. In Cisco CallManager 4.0, the maximum number of calls per LA has been changed to be database configurable. This means that the CiscoTSP has been enhanced to support more than 2 calls per line on MCD (Multiple Call Display) devices. An MCD device is a device that can display more than 2 call instances per DN at any given time. For non-MCD devices, the CiscoTSP will only support a maximum of 2 calls per line. The absolute maximum number of calls per line appearance is 200.

Busy Trigger

In Cisco CallManager 4.0, there is a new setting, busy trigger, that indicates the limit on the number of calls per line appearance before the CallManager will reject an incoming call. The busy trigger setting is database configurable, per line appearance, per cluster. The busy trigger setting replaces the existing call waiting flag per DN. Since the busy trigger setting cannot be modified using the CiscoTSP, there are no changes in the TAPI interface exposed by the CiscoTSP as a result of this feature, but it will have an effect on applications that use the existing call waiting flag per DN.

CFNA Timer

Prior to Cisco CallManager 4.0, the Call Forward No Answer (CFNA) timer was configured through a service parameter. This has been changed in Cisco CallManager 4.0 to be database configurable, per DN, per cluster. This timer is not configurable using the CiscoTSP, so there are no changes to the CiscoTSP to support this feature, but this change will have an effect on applications that use the CFNA feature of the CallManager.

Shared Line Appearance

In Cisco CallManager 3.3, the Cisco CallManager supports the ability for a line on a device to share the same directory number (DN) as a line on a different device. This functionality is known as Shared Line Appearance. The CiscoTSP 3.3 did not support opening two different lines that each shares the same DN.

In Cisco CallManager 4.0, several changes were made in the Cisco CallManager to the Shared Line Appearance feature. The CiscoTSP has been enhanced in Release 4.0 to support Shared Line Appearances.

In Cisco CallManager 3.3, if there is more than one device that shares the same line appearance, only one of those devices can have an active (connected) call. Also, if one of those devices has an active call using this line appearance, then no other device can use this line appearance anymore.

In Cisco CallManager 4.0, the Cisco CallManager has been enhanced to allow multiple active calls to exist concurrently on each of the different devices that share the same line appearance. Each device is still limited to at most one active call and multiple hold or incoming calls at any given time. This functionality can be supported by applications that use the CiscoTSP to monitor and control shared line appearances.

If a call is active on a line that is a shared line appearance with another line, then the call will appear on the other line with the dwCallState=CONNECTED and the dwCallStateMode=INACTIVE. Even though the call party information may not be displayed on the actual IP Phone for the call at the other line, the call party information is still be reported by the TSP on the call at the other line. This gives the application the ability to decide if it wishes to block this information or not. Also, no call control functions are allowed on a call that is in the CONNECTED INACTIVE call state.

The CiscoTSP does not support shared lines on CTI Route Point devices.

In the scenario where a line is calling a DN that contains multiple shared lines, the dwCalledIDName in the LINECALLINFO structure for the line with the outbound call may be empty or set randomly to the name of one of the shared DNs. The reason for this is the Cisco TSP and the Cisco CallManager cannot resolve which of the shared DNs you are calling until the call is answered.


Note CiscoTSP does not support configurations that include devices with two or more lines with the same directory numbers (DN) in different partitions.


Select Calls

There is a new softkey "select" on the IP Phones that allows a user the ability to select call instances in order to perform feature activation, such as transfer or conference, on those calls. The action of selecting a call on a line locks that call so that it cannot be selected by any of the shared line appearances. Pressing the "Select" key on a selected call will de-select the call.

The ability to select calls is not supported by the CiscoTSP. The reason for this is that all of the Transfer and Conference functions contain parameters indicating which calls that the operation should be invoked on. Therefore, there is no reason to support "Select" through the TSP.

The CiscoTSP supports the events caused by a user selecting a call on a line that is being monitored by the application. When a call on a line is selected, all of the other lines that share the same line appearance will see the call state change to dwCallState=CONNECTED, and dwCallStateMode=INACTIVE.

Transfer Changes

In Cisco CallManager 3.3, the "Transfer" softkey had two different behaviors depending on the number of calls at that DN.

1. If there was only one active call at the DN, the first invocation of the "Transfer" softkey resulted in putting the active call on hold and initiating a new call using the same DN. Once the new call was setup, the second invocation of the "Transfer" softkey would transfer the calls.

2. If there were already two calls in the line appearance, the first invocation of the "Transfer" softkey resulted in putting the active call on hold, but not initiating a new call. If the other call was not an incoming call, it was highlighted. Then, the second invocation of the "Transfer" softkey would transfer the calls.

In Cisco CallManager 4.0, the "Transfer" softkey has been changed so that it always initiates a new consultation call. This is the behavior described in #1 above. The "Transfer" softkey can no longer be used to perform behavior #2. Behavior #2, which is sometimes known as "Arbitrary Transfer," is not necessary anymore with the addition of the Direct Transfer feature.

Because of these changes, the CiscoTSP has removed the lineDevSpecific() - Swap Hold Setup Transfer function. The lineDevSpecific() - Swap Hold Setup Transfer function performs the functionality described in behavior #2 above and as mentioned above is not needed anymore because of the addition of the "Direct Transfer" feature.

Direct Transfer

In Cisco CallManager 4.0, a new softkey, "Direct Transfer" has been provided to transfer the other end of one established call to the other end of another established call, while dropping the feature initiator from those two calls. Here, an established call refers to a call that is either in the onhold state or in the connected state. The "Direct Transfer" feature will not initiate a consultation call and will not put the active call onhold.

The addition of the "Direct Transfer" feature makes the CiscoTSP function lineDevSpecific() - Swap Hold Setup Transfer obsolete. A TAPI application can invoke the "Direct Transfer" feature using the TAPI lineCompleteTransfer() function on two calls that are already in the established state. This also means that the two calls do not have to be initially set up using the lineSetupTransfer() function.

Conference Changes

In Cisco CallManager 3.3, the "Conference" softkey had two different behaviors depending on the number of calls at that DN.

1. If there was only one active call at the DN, the first invocation of the "Conference" softkey resulted in putting the active call on hold and initiating a new call using the same DN. Once the new call was setup, the second invocation of the "Conference" softkey created a conference call between all of the parties connected on both calls.

2. If there were already two calls in the line appearance, the first invocation of the "Conference" softkey resulted in putting the active call on hold, but not initiating a new call. If the other call is not an incoming call, it would be highlighted. Then, the second invocation of the "Conference" softkey created a conference call between all of the parties connected on both calls.

In Cisco CallManager 4.0, the "Conference" softkey has been changed so that it always initiates a new consultation call. This is the behavior described in #1 above. The "Conference" softkey can no longer be used to perform behavior #2. Behavior #2, which is sometimes known as "Arbitrary Conference" is not necessary anymore with the addition of the "Join" feature which is described later in this document.

Call Join

In Cisco CallManager 4.0, a new softkey, "Join" has been provided to join all the parties of established calls, at least two, into one conference call. The "Join" feature will not initiate a consultation call and will not put the active call onhold. It also can include more than 2 calls, resulting in a call with more than 3 parties.

In Cisco CallManager 4.0, the CiscoTSP has exposed the "Join" feature as a new device specific function which will be known as lineDevSpecific() - Join. This function can be performed on two or more calls that are already in the established state. This also means that the two calls do not have to be initially set up using the lineSetupConference() or linePrepareAddToConference() functions.

The CiscoTSP has also been enhanced to support the lineCompleteTransfer() function with the dwTransferMode=Conference. This function allows a TAPI application to join all the parties of two, and only two, established calls into one conference call.

The CiscoTSP has also been enhanced to support the lineAddToConference() function to join a call to an existing conference call that is in the ONHOLD state.

There is a feature interaction issue involving Join, Shared Lines, and the Maximum Number of Calls. The issue occurs when you have two shared lines and the maximum calls on one line is less than the maximum calls on the other line. If a Join is performed on the line that has more maximum calls, then this issue will be encountered if the primary call of the Join is beyond the maximum number of calls for the other shared line.

For example, one shared line, A, has a maximum number of calls set to 5 and another shared line, A', has a maximum number of calls set to 2. The scenario involves the following steps:

1. A calls B. B answers. A puts the call onhold.

2. C calls A. A answers. C puts the call onhold.

At this point, line A has two calls in the ONHOLD state and line A' has two calls in the CONNECTED_INACTIVE state.

3. D calls A. A answers.

At this point, the call will presented to A, but it will not be presented to A'. The reason for this is because the maximum calls for A' is set to 2.

4. A performs a Join operation either through the phone or using the lineDevSpecific - Join API to join all the parties in the conference. It uses the call between A and D as the primary call of the Join operation.

Because the call between A and D was used as the primary call of the Join, the ensuing conference call will not be presented to A'. Both calls on A' will go to the IDLE state. The end result is that A' will not see the conference call that exists on A.

Privacy Release

In Cisco CallManager 3.2 and Cisco CallManager 3.3, the privacy feature was controlled by a service wide parameter, BargeEnabled. This parameter has been removed in Cisco CallManager 4.0.

The Privacy feature is being fully implemented in Cisco CallManager 4.0, allowing the user to dynamically alter its privacy setting. The privacy setting will affect all existing and future calls on the device.

In Cisco CallManager 4.0, the CiscoTSP is not being enhanced to support the Privacy Release feature.

Barge and cBarge

The Barge feature is currently supported in Cisco CallManager 3.3. In Cisco CallManager 3.3, the Barge feature always uses the built-in conference bridge at the target device. The Cisco CallManager 3.3 version of the CiscoTSP did not support handling the events caused by the invocation of the Barge feature on the phones. The TSP also did not support an API that allows the invocation of the Barge feature.

In Cisco CallManager 4.0, there are changes in the CallManager that allow the TSP to support the events caused by the Barge feature. Also in Cisco CallManager 4.0, the CallManager has implemented a new feature, cBarge, which always uses the shared conference resource in the CallManager, also known as a conference bridge, as opposed to the built-in bridge on the phone. In Cisco CallManager 4.0, the TSP does not support an API to invoke either the Barge feature or the cBarge feature. The TSP has only been modified to support the events caused by the invocation of the Barge and cBarge features.

TSP Auto Update Functionality

CiscoTSP supports auto update functionality so that the latest plug-in can be downloaded and installed on client machine. The new plug-in will be QBE compatible with the connected CTIManager. When the Call Manager is upgraded to a higher version, and CiscoTSP auto update functionality is enabled, user will receive the latest compatible CiscoTSP, which will work with the upgraded Call Manager. This makes sure that the applications work as expected with the new release of CallManager (provided the new call manager interface is backward compatible with the TAPI interface). The CiscoTSP installed locally on the client machine allows application to set the auto update options as part of the CiscoTSP configuration. You can opt for updating the CiscoTSP in following different ways:

Update CiscoTSP, whenever a different (has to be higher version that existing) version is available on Call Manager server

Update CiscoTSP whenever there is a QBE protocol version mismatch between the existing CiscoTSP and the CM version.

Do not update CiscoTSP using Auto Update functionality.

AutoInstall Behavior

As part of initialization of CiscoTSP, when application does lineInitializeEx, CiscoTSP will query the current TSP plugin version information available on CallManager server. Once this information is available CiscoTSP will compare the installed CiscoTSP version with the plugin version. If user has selected an option for auto update, CiscoTSP will trigger the update process. As part of Auto update, CiscoTSP will behave in following ways on different platforms.

On Windows 95, Windows 98, Windows ME

Because CiscoTSP is in use and locked when application does lineInitializeEx, the auto update process will request user to close all the running applications, in order to install the new TSP version on the client setup. If user closes all the running applications, CiscoTSP auto update process will succeed and user will be informed about the success. If user does not close running applications and still continue with the installation, new version of CiscoTSP will not be installed and corresponding error will be reported to applications.

On Windows NT

Once CiscoTSP detects that an upgradeable version is available on Call Manager server and user has selected to auto update, CiscoTSP will report 0 lines to application and will remove the CiscoTSP provider from the provider list. It will then try to stop the telephony service to avoid any locked files during auto upgrade. If the telephony service can be stopped TSP will be auto updated silently and the service will be restarted. Applications must be reinitiatlized in order to start using the CiscoTSP. If the telephony service could not be stopped then CiscoTSP will install the new version and inform user to restart the system. User has to restart the system in order to use the new CiscoTSP.

On Windows 2000/XP

Once CiscoTSP detects that an upgradeable version is available on Call Manager server and user has selected to auto update, CiscoTSP will report 0 lines to application and will remove the CiscoTSP provider from the provider list. If a new TSP version is detected during reconnect time, the running applications will receive LINE_REMOVE on all the lines which are already initialized and are in OutOfService state. Then CiscoTSP will silently upgrade itself to new version downloaded from CM and will add back the provider to provider list. All the running applications will receive LINE_CREATE messages.

WinXP supports multiple user log on sessions (fast user switching), in Parche release auto update is only supported for the first logon user. If there are multiple active log on sessions, TSP will only support the auto update functionality for the first logged on user.


Note In case user has a multiple CiscoTSPs installed on the client machine, only first CiscoTSP instance is enabled to setup the auto update configuration. All CiscoTSPs are upgraded to a common version upon version mismatch. From "Control Panel/Phone & Modem Options/Advanced/CiscoTSP001" - General page will show the options for auto update.


User can change the location of Plugin to be a different machine than the CallManager server. It is a CTI service parameter which can be configured, the default is "//<CMServer>//ccmpluginsserver".

If Silent upgrade fails on any of the listed platforms due to any reason (e.g. locked files encountered during upgrade on Win95/98/ME), the old CiscoTSP provider/s will not be added back to provider list to avoid any looping of auto update process. User will have to clear the update options and will have to add back the providers to provider list manually. User can update the CiscoTSP manually or by fixing the problem/s encountered during auto update and reinitializing TAPI to trigger the auto update process.


Note The details of user interface are provided as part of TSP install and configuration guide.



Note TSPAutoInstall.exe has UI screens and can proceed to display these screens only when the telephony service has enabled the LocalSystem logon option with "Allow Service to interact with user". If logon option is not set as LocalSystem or logon option is LocalSystem but "Allow Service to interact with User" is disabled then TSP will not be able to launch the AutoInstall UI screens and will not continue with AutoInstall. User has to make sure that the following logon options are set for the telephony service.


Logon as : LocalSystem

Enable checkbox : "Allow Service to interact with Desktop"

These telephony service settings, when changed, requires the user to manually restart the service in order to take into effect.

If, after changing the settings to above values the user does not restart the service, the TSP checks for "Allow Service to interact with user" will be positive (as the configuration is updated for the service in the database) but AutoInstall UI can not be displayed. TSP will continue to put the entry for TSPAutoInstall.exe under Registry key RUNONCE. This will help autoinstall to run when the machine reboots next time.

QoS Support

CiscoTSP 4.0 supports the Cisco baseline for Quality of service documented in EDCS-206468. TSP marks the IP DSCP (Differentiated Services Code Point) for QBE control signals flowing from TSP to CTI with Class 3 DSCP marking as 0x18. Cisco TAPI Wave driver will mark the RTP packets with EF DSCP marking as 0x2E. TSP does not allow user to configure these values instead defaults them to above values. There is no change in the TAPI interface to support QoS. If the underlying network is enabled for DSCP it will make use of the IP header DSCP bit marking and route the traffic accordingly.

Forwarding Changes

There is a slight change in behavior in CiscoTSP 4.0 in forwarding. The scenario is as follows. A line is set to FwdAll to the Voice Mail Pilot Number by the user of the phone manually on the phone. Then, an application is used to turn forwarding off on the same line. Prior to CiscoTSP 4.0 and Cisco CallManager 4.0, the calls that come into the line would still get forwarded to voice mail. In CiscoTSP 4.0 and Cisco CallManager 4.0, the calls that come into the line will no longer be forwarded to voice mail.

Presentation Indication Flag

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 is still needed by another system like Unity VM etc. Hence, each number/name of 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.

This feature can be set up as follows:

On a Per Call Basis—Route Patterns and Translation Patterns can be used to set or reset PI flags for various partyDNs/Names on a per call basis. If the pattern matches the digits, then the PI settings associated with the pattern will be applied to the call information.

On a Permanent basis—A trunk device can be configured with "Allow" or "Restrict" options for parties. This will set the PI flags for the corresponding party information for all calls from this trunk.

In Cisco CallManager 4.0, the CiscoTSP is being enhanced to support this feature. If calls are made via Translation patterns with the all the flags set to Restricted then the CallerID/Name, ConnectedID/Name and RedirectionID/Name will be sent to applications as Blank. The LINECALLPARTYID flags will also be set to Blocked if both the Name and Party number are set to Restricted.

Modified CiscoTSP 4.0 Entities

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

Entity
Type

LINE_CALLSTATE

TAPI Line Message

LINEADDRESSCAPS

TAPI Line Device Structure

LINECALLSTATUS

TAPI Line Device Structure

lineAddToConference

TAPI Line Function

lineCompleteTransfer

TAPI Line Function

lineDevSpecific

TAPI Line Function


Changes From CiscoTSP 3.3 to CiscoTSP 4.0

Line In-Service or 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 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 OriginalCalledParty information.

User Deletion from Directory

In previous releases, when the TSP user is removed from the Cisco CallManager directory, the TSP would place all of the lines and phones OUTOFSERVICE/SUSPENDED indefinitely until the lines and phones are closed.

In CiscoTSP 3.3, when the TSP user is removed, the TSP now closes all of the lines and phones and sends LINE_CLOSE/PHONE_CLOSE messages. After doing this, the TSP removes all of the lines and phones and sends LINE_REMOVE/PHONE_REMOVE messages.

Removal of lineDevSpecific() - Swap Hold Setup Transfer

In CiscoTSP 4.0, the lineDevSpecific() - Swap Hold Setup Transfer function has been removed because of the changes made to the Transfer feature in the Cisco CallManager and because of the addition of the Direct Transfer feature.

Call Reason Enhancements

In CiscoTSP 3.3, the TSP did not properly support the TAPI call reason model. For example, in a lineRedirect() function, both the party that was redirected and the party that the call was redirected to had the LINECALLREASON_REDIRECT set in the dwReason of LINECALLINFO. In TAPI, only the destination of the redirect is supposed to have LINECALLREASON_REDIRECT while the party that was redirected should maintain the same dwReason that it had before the redirect occurred. In CiscoTSP 4.0, the TSP properly supports call reasons as defined in the TAPI specification.

Changes to phoneSetDisplay()

In releases prior to Cisco CallManager 4.0, Cisco CallManager messages that were passed to the phone would automatically overwrite any messages sent to the phone using phoneSetDisplay(). In Cisco CallManager 4.0, the message sent to the phone in the phoneSetDisplay() API will remain on the phone until the phone is rebooted. If the application wants to clear the text from the display and see the Cisco CallManager messages again, a NULL string, not spaces, should be passed in the phoneSetDisplay() API. In other words, the lpsDisplay parameter should be NULL and the dwSize should be set to 0.

CiscoTSP 3.3 Enhancements

The following CiscoTSP 3.3 enhancements for Cisco CallManager 3.3 exist:

Support for linePark and lineUnpark

Support for monitoring CallPark Directory Numbers using lineOpen

Support for Cisco IP Phones 7902, 7912, and 7935

Reporting TSP Initialization Problems or Errors to the Application

CiscoTSP now reports the initialization error code through the registry key that provide applications to better diagnose the initialization problems. The newly added registry key is HKEY_LOCAL_MACHINE\SOFTWARE\Cisco Systems, Inc.\Cisco TSP\Cisco TSP001\TSPInitializationErrorCode.


Note Each TSP instance (in case of multiple TSP installation) has its own TSPInitializationErrorCode in the respective registry key HKEY_LOCAL_MACHINE\SOFTWARE\cisco systems, Inc.\Cisco TSP\Cisco TSPXXX.


The following error codes get exposed to the user. The definitions are located in CiscoLineDevspecificmsg.h.

#define TSP_WILL_RECONNECT 0x80000000

This high bit gets set when TSP performs reconnection to configured CTIManagers. Usually when TSP initialization with CTI fails due to temporary failure reasons, such as CTI not initialized or request timeouts, TSP reconnects to CTI. In those situations, TSP returns 0 devices for the initial TSPI_ProviderEnumDevices request and enumerates the devices when connection to CTI is reestablished. After enumeration, TSP informs the devices to TAPI applications through LINE_CREATE / PHONE_CREATE messages.

#define TSP_SUCCESS 0x00000000

#define TSPERR_INTERNAL 0x00000001

This error indicates some Internal TSP error occurred. Collect the appropriate TSP traces and send it to TSP developer support to further diagnose the issue.

#define TSPERR_CONNECT_TO_CTI_FAILED 0x00000002

This error indicates socket connection to CTIManager failed, either the service is not up and running on the server or configured CTIManager IPAddress is invalid or unreachable.

#define TSPERR_INIT_AUTHENTICATION_REQUEST_TIMEOUT 0x00000003

This error indicates username, password, and authentication request for CTI access timed out. TSP reconnects in this situation.

#define TSPERR_INIT_CTI_NOT_INITIALIZED 0x00000004

This error indicates CTI is not yet completely initialized so that TSP can reconnect within ReconnectInterval.

#define TSPERR_INIT_CTI_RESPONSE_TIMEOUT 0x00000005

This error indicates the request for initialization (providerOpen) timed out. User needs to configure or verify the settings for ProviderOpenCompletedTimeout, Synchronous message timeout, and CTI service parameter for Synchronous message timeout so that CTI gets more time to initialize the devices/lines and TSP can wait for some more time to get the successful response.

#define TSPERR_INIT_AUTHENTICATION_TEMPORARY_FAILED 0x00000006

This error indicates authentication failed temporarily. TSP reconnects to CTI within ReconnectInterval and can have a successful connection later.

#define TSPERR_INIT_AUTHENTICATION_FAILED 0x00000007

This error indicates authentication failure. User needs to verify the Username or Password. This is a permanent failure. If multiple CTIManagers are configured, TSP attempts to connect to the remaining CTIManagers.

#define TSPERR_INIT_CTI_USE_NOT_ALLOWED_FOR_USER 0x00000008

This error indicates CTI use for this user is not enabled through Cisco CallManager Administration. This is a permanent failure. If multiple CTIManagers are configured, TSP attempts to connect to remaining CTIManagers.

#define TSPERR_INIT_ILLEGAL_MESSAGE 0x00000009

This error indicates invalid message format (internal protocol error). TSP does not reconnect.

#define TSPERR_INIT_INCOMPATIBLE_PROTOCOL_VERSION 0x0000000a

This error indicates internal protocol error - as the QBE version mismatch. The TSP QBE protocol version does not match with the CTI protocol version, hence the initialization can not proceed. TSP does not reconnect.

#define TSPERR_UNKNOWN 0x00000010

This error indicates some internal unknown error. Do not report because this is the default case. Case is only when a new error is introduced in CTI-TSP QBE protocol and is not already mapped to new TSP error. Collect the appropriate TSP traces and send it to TSP developer support to further diagnose the issue.

New or Changed CiscoTSP 3.3 Entities

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

Entity
Type

LINEDEVCAPS

TAPI Line Device Structure

linePark

TAPI Line Function

lineUnpark

TAPI Line Function


Changes From CiscoTSP 3.2 to CiscoTSP 3.3

This section describes two important changes in CiscoTSP version 3.3:

A change in the way CiscoTSP behaves when the TSP user is deleted from the Cisco CallManager Directory

Changes that allow opening two lines on the same CTI port device

User Deletion From Directory

In previous releases, when the TSP user is removed from the Cisco CallManager directory, the TSP would place all the lines and phones OUTOFSERVICE/SUSPENDED indefinitely until the lines and phones are closed.

In CiscoTSP 3.3, when the TSP user is removed, the TSP now closes all the lines and phones and sends LINE_CLOSE/PHONE_CLOSE messages. After doing this, the TSP removes all the lines and phones and sends LINE_REMOVE/PHONE_REMOVE messages.

Opening Two Lines on One CTI Port Device

In previous releases, the CiscoTSP opened only one line at a time on CTI port devices that are configured with multiple lines.

In CiscoTSP 3.3, the TSP allows the simultaneous opening of all lines on the same CTI port device as long as the media parameters are matching for each lineOpen.

Media termination occurs two ways on CTI port devices:

Cisco Wave Drivers—The Cisco Wave Drivers set up the media parameters.

Media Termination Controlled by the Application—The application provides the media parameters.

CiscoTSP 3.3 allows applications to open all lines on the same CTI port device at the same time as long as all the lines are using the Cisco Wave Drivers or as long as all the lines are using custom media termination with the same media termination settings for each line.

CiscoTSP 3.2 Enhancements

The following CiscoTSP enhancements apply for 3.2:

Support for multiple languages in the CiscoTSP installation program and in the CiscoTSP configuration dialogs

Support for ATA186 devices

Changes From CiscoTSP 3.1 to CiscoTSP 3.2

Cisco TSP enhancements for 3.1 include CTI Manager and support for fault tolerance and using Cisco CallManager Extension Mobility.

CiscoTSP 3.1 Enhancements

The following Cisco TSP enhancements apply for 3.1:

CTI Manager and support for fault tolerance

Support for Cisco CallManager Extension Mobility

Support for Multiple CiscoTSP

Support for swap hold and setup transfer with the lineDevSpecific function

Support for lineForward

Support to Reset the Original Called Party upon Redirect with the lineDevSpecific function

Support for VG248 devices

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 line or phone and changes in the LINE_CALLINFO message.

Line In Service or 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 o 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 change, from the behavior in CiscoTSP 3.0, 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

A change 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.

New or Changed CiscoTSP 3.1 Entities

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

Entity
Type

LINE_ADDRESSSTATE

TAPI Line Message

LINE_REMOVE

TAPI Line Message

LINEADDRESSCAPS

TAPI Line Device Structure

LINEFORWARD

TAPI Line Device Structure

LINEFORWARDLIST

TAPI Line Device Structure

PHONE_REMOVE

TAPI Phone Message

lineForward

TAPI Line Function


Chapter
Description

"Overview"

Outlines the key concepts for Cisco TAPI. Lists all functions available in the Cisco TAPI implementation for Cisco CallManager. Describes changes in and enhancements to Cisco TSP.

"Cisco TAPI Implementation"

Describes the supported functions in the Cisco implementation of the standard Microsoft TAPI v2.1.

Chapter 3, "Cisco Device Specific Extensions"

Describes the functions that comprise the Cisco hardware-specific implementation classes.

Chapter 4, "Cisco TAPI Examples"

Provides examples that illustrate how to use the Cisco TAPI implementation.


Organization

Related Documentation

For more information about TAPI specifications, creating an application to use TAPI, or TAPI administration, see

Microsoft TAPI 2.1 Features:
http://www.microsoft.com/ntserver/techresources/commnet/tele/tapi21.asp

Getting Started with Windows Telephony
http://www.microsoft.com/NTServer/commserv/deployment/planguides
/getstartedtele.asp

Windows Telephony API (TAPI)
http://www.microsoft.com/NTServer/commserv/exec/overview
/tapiabout.asp

Creating Next Generation Telephony Applications:
http://www.microsoft.com/NTServer/commserv/techdetails/prodarch
/tapi21wp.asp

The Microsoft Telephony Application Programming Interface (TAPI) Programmer's Reference

"For the Telephony API, Press 1; For Unimodem, Press 2; or Stay on the Line" —A paper on TAPI by Hiroo Umeno a COMM and TAPI specialist at Microsoft.

"TAPI 2.1 Microsoft TAPI Client Management"

"TAPI 2.1 Administration Tool"

Required Software

CiscoTSP requires the following software:

Cisco CallManager version 4.0(1) on the Cisco CallManager server

Microsoft Internet Explorer 4.01 or later

Supported Windows Platforms

All Windows operating systems support Cisco TAPI. Depending on the type and version of your operating system, you may need to install a service pack.

Windows 2000

Windows 2000 includes TAPI 2.1.

Windows XP

Windows XP includes TAPI 2.1.

Windows Me

Windows Me includes TAPI 2.1.

Windows NT Server 4.0 or Windows NT Workstation 4.0

Service Pack 5 (SP5) includes TAPI 2.1.

SP5 is available via download from Microsoft.

Windows 98

Windows 98 includes TAPI 2.1.

Windows 95

Microsoft provides TAPI 2.1.


Note Check%SystemRoot%\system32 for these dynamically loaded library (.dll) files
and versions:
msvcrt.dll version: 6.00.8397.0
msvcp60.dll version: 6.00.8168.0
mfc42.dll version: 6.00.8447.0


Conventions

This document uses the following conventions:

Convention
Description

boldface font

Commands and keywords are in boldface.

italic font

Arguments for which you supply values are in italics.

[   ]

Elements in square brackets are optional.

{ x | y | z }

Alternative keywords are grouped in braces and separated by vertical bars.

[ x | y | z ]

Optional alternative keywords are grouped in brackets and separated by vertical bars.

string

An unquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

screen font

Terminal sessions and information that the system displays are in screen font.

boldface screen font

Information you must enter is in boldface screen font.

italic screen font

Arguments for which you supply values are in italic screen font.

This pointer highlights an important line of text in an example.

^

The symbol ^ represents the key labeled Control—for example, the key combination ^D in a screen display means hold down the Control key while you press the D key.

<   >

Nonprinting characters, such as passwords are in angle brackets.


Notes use the following convention:


Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the publication.


Obtaining Documentation

Cisco documentation and additional literature are available on Cisco.com. Cisco also provides several ways to obtain technical assistance and other technical resources. These sections explain how to obtain technical information from Cisco Systems.

Cisco.com

You can access the most current Cisco documentation at this URL:

http://www.cisco.com/univercd/home/home.htm

You can access the Cisco website at this URL:

http://www.cisco.com

You can access international Cisco websites at this URL:

http://www.cisco.com/public/countries_languages.shtml

Ordering Documentation

You can find instructions for ordering documentation at this URL:

http://www.cisco.com/univercd/cc/td/doc/es_inpck/pdi.htm

You can order Cisco documentation in these ways:

Registered Cisco.com users (Cisco direct customers) can order Cisco product documentation from the Ordering tool:

http://www.cisco.com/en/US/partner/ordering/index.shtml

Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco Systems Corporate Headquarters (California, USA) at 408 526-7208 or, elsewhere in North America, by calling 800 553-NETS (6387).

Documentation Feedback

You can send comments about technical documentation to bug-doc@cisco.com.

You can submit comments by using the response card (if present) behind the front cover of your document or by writing to the following address:

Cisco Systems
Attn: Customer Document Ordering
170 West Tasman Drive
San Jose, CA 95134-9883

We appreciate your comments.

Obtaining Technical Assistance

For all customers, partners, resellers, and distributors who hold valid Cisco service contracts, Cisco Technical Support provides 24-hour-a-day, award-winning technical assistance. The Cisco Technical Support Website on Cisco.com features extensive online support resources. In addition, Cisco Technical Assistance Center (TAC) engineers provide telephone support. If you do not hold a valid Cisco service contract, contact your reseller.

Cisco Technical Support Website

The Cisco Technical Support Website provides online documents and tools for troubleshooting and resolving technical issues with Cisco products and technologies. The website is available 24 hours a day, 365 days a year at this URL:

http://www.cisco.com/techsupport

Access to all tools on the Cisco Technical Support Website requires a Cisco.com user ID and password. If you have a valid service contract but do not have a user ID or password, you can register at this URL:

http://tools.cisco.com/RPF/register/register.do

Submitting a Service Request

Using the online TAC Service Request Tool is the fastest way to open S3 and S4 service requests. (S3 and S4 service requests are those in which your network is minimally impaired or for which you require product information.) After you describe your situation, the TAC Service Request Tool automatically provides recommended solutions. If your issue is not resolved using the recommended resources, your service request will be assigned to a Cisco TAC engineer. The TAC Service Request Tool is located at this URL:

http://www.cisco.com/techsupport/servicerequest

For S1 or S2 service requests or if you do not have Internet access, contact the Cisco TAC by telephone. (S1 or S2 service requests are those in which your production network is down or severely degraded.) Cisco TAC engineers are assigned immediately to S1 and S2 service requests to help keep your business operations running smoothly.

To open a service request by telephone, use one of the following numbers:

Asia-Pacific: +61 2 8446 7411 (Australia: 1 800 805 227)
EMEA: +32 2 704 55 55
USA: 1 800 553 2447

For a complete list of Cisco TAC contacts, go to this URL:

http://www.cisco.com/techsupport/contacts

Definitions of Service Request Severity

To ensure that all service requests are reported in a standard format, Cisco has established severity definitions.

Severity 1 (S1)—Your network is "down," or there is a critical impact to your business operations. You and Cisco will commit all necessary resources around the clock to resolve the situation.

Severity 2 (S2)—Operation of an existing network is severely degraded, or significant aspects of your business operation are negatively affected by inadequate performance of Cisco products. You and Cisco will commit full-time resources during normal business hours to resolve the situation.

Severity 3 (S3)—Operational performance of your network is impaired, but most business operations remain functional. You and Cisco will commit resources during normal business hours to restore service to satisfactory levels.

Severity 4 (S4)—You require information or assistance with Cisco product capabilities, installation, or configuration. There is little or no effect on your business operations.

Obtaining Additional Publications and Information

Information about Cisco products, technologies, and network solutions is available from various online and printed sources.

Cisco Marketplace provides a variety of Cisco books, reference guides, and logo merchandise. Visit Cisco Marketplace, the company store, at this URL:

http://www.cisco.com/go/marketplace/

The Cisco Product Catalog describes the networking products offered by Cisco Systems, as well as ordering and customer support services. Access the Cisco Product Catalog at this URL:

http://cisco.com/univercd/cc/td/doc/pcat/

Cisco Press publishes a wide range of general networking, training and certification titles. Both new and experienced users will benefit from these publications. For current Cisco Press titles and other information, go to Cisco Press at this URL:

http://www.ciscopress.com

Packet magazine is the Cisco Systems technical user magazine for maximizing Internet and networking investments. Each quarter, Packet delivers coverage of the latest industry trends, technology breakthroughs, and Cisco products and solutions, as well as network deployment and troubleshooting tips, configuration examples, customer case studies, certification and training information, and links to scores of in-depth online resources. You can access Packet magazine at this URL:

http://www.cisco.com/packet

iQ Magazine is the quarterly publication from Cisco Systems designed to help growing companies learn how they can use technology to increase revenue, streamline their business, and expand services. The publication identifies the challenges facing these companies and the technologies to help solve them, using real-world case studies and business strategies to help readers make sound technology investment decisions. You can access iQ Magazine at this URL:

http://www.cisco.com/go/iqmagazine

Internet Protocol Journal is a quarterly journal published by Cisco Systems for engineering professionals involved in designing, developing, and operating public and private internets and intranets. You can access the Internet Protocol Journal at this URL:

http://www.cisco.com/ipj

World-class networking training is available from Cisco. You can view current offerings at this URL:

http://www.cisco.com/en/US/learning/index.html