Cisco Unified Communications Manager TAPI Developers Guide
Chapter 1. Overview
Downloads: This chapterpdf (PDF - 553.0KB) The complete bookPDF (PDF - 7.19MB) | Feedback

Overview

Table Of Contents

Overview

Cisco Unified TSP Functions

Call Control

First-Party Call Control

Third-Party Call Control

CTI Port

Dynamic Port Registration

CTI Route Point

Media Termination at Route Point

CTI Manager (Cluster Support)

Cisco Unified Communications Manager Failure

Call Survivability

CTI Manager Failure

Cisco Unified TAPI Application Failure

Supported Device Types

Forwarding

Redirect and Blind Transfer

lineRedirect

lineDevSpecific - Redirect Reset Original Called ID

lineDevSpecific - Redirect Set Original Called ID

lineDevSpecific - Redirect FAC CMC

lineBlindTransfer

lineDevSpecific - BlindTransfer FAC CMC

Extension Mobility Support

Directory Change Notification Handling

Monitoring Call Park Directory Numbers

Multiple Cisco Unified TSPs

Multiple Calls per Line Appearance

Maximum Number of Calls

Busy Trigger

CFNA Timer

Shared Line Appearance

Select Calls

Direct Transfer

Join

Privacy Release

Barge and cBarge

Cisco Unified TSP Auto Update Functionality

QoS Support

Presentation Indication (PI)

Compatibility

Unicode Support

TLS Support

SRTP Support

FAC/CMC Support

CTI Port Third-Party Monitoring Port

CTI Device/Line Restriction

XSI Object Pass Through

Intercom Support

Secure Conferencing Support

Additional Features Supported on SIP Phones

Silent Monitoring

Call Recording

Conference Enhancements

Arabic and Hebrew Language Support

Silent Install Support

Do Not Disturb

Translation Pattern


Overview


This chapter outlines the key concepts that are involved in using Cisco Unified TAPI service provider (Cisco Unified TSP) and lists the functions that are available in the Cisco Unified Communications Manager (formerly Cisco Unified CallManager) Release 6.0(1) implementation. The Cisco Unified TAPI service provider that is shipped with Cisco Unified Communications Manager Release 6.0(1) is TAPI version 2.1.

Cisco Unified TSP Functions

The following list includes all the functions that are available in the Cisco TSP implementation for Cisco Unified Communications Manager Release 6.0(1):

Call Control

CTI Port

Dynamic Port Registration

CTI Route Point

Media Termination at Route Point

CTI Manager (Cluster Support)

Supported Device Types

Forwarding

Redirect and Blind Transfer

Extension Mobility Support

Directory Change Notification Handling

Monitoring Call Park Directory Numbers

Multiple Cisco Unified TSPs

Multiple Calls per Line Appearance

Shared Line Appearance

Select Calls

Direct Transfer

Join

Privacy Release

Barge and cBarge

Cisco Unified TSP Auto Update Functionality

QoS Support

Presentation Indication (PI)

Compatibility

Unicode Support

TLS Support

SRTP Support

FAC/CMC Support

CTI Port Third-Party Monitoring Port

CTI Device/Line Restriction

Release 6.0(1) adds the following features:

Intercom Support

Secure Conferencing Support

Additional Features Supported on SIP Phones

Silent Monitoring

Call Recording

Conference Enhancements

Arabic and Hebrew Language Support

Silent Install Support

Do Not Disturb

Translation Pattern

Call Control

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.

CTI Port

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

The Dynamic Port Registration feature lets applications 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 timeout 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:

Answer

Multiple Active Calls

Redirect

Hold

UnHold

Blind Transfer

DTMF Digits

Tones

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

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

Call Survivability

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.

Supported Device Types

Cisco Unified TSP 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.)

7835

7902

7905

7910

7912

7914

7940

7941

7960

7961

7965

7970

7971

CTI Route Points

CTI Ports

VG248 Analog Devices

ATA186 Analog Devices

Forwarding

Cisco Unified TSP 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.

Cisco Unified TSP 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 Cisco Unified Communications Manager Administration or another application setting call forward all.

Redirect and Blind Transfer

The Cisco Unified TSP supports several different methods of Redirect and Blind Transfer. This section outlines the different methods as well as the differences between each method.

lineRedirect

This standard TAPI lineRedirect function redirects calls to a specified destination. The Calling Search Space and Original Called Party that Cisco Unified TSP uses for this function are as follows:

Calling Search Space (CSS) — Uses CSS of the CallingParty (the party being redirected) for all cases unless the call is in a conference or a member of a two-party conference where it uses the CSS of the RedirectingParty (the party that is doing the redirect).

Original Called Party — Not changed.

lineDevSpecific - Redirect Reset Original Called ID

This function redirects calls to a specified destination while resetting the Original Called Party to the party that is redirecting the call. The Calling Search Space and Original Called Party that Cisco Unified TSP uses for this function follow:

Calling Search Space (CSS) — Uses CSS of the CallingParty (the party being redirected).

Original Called Party — Set to the RedirectingParty (the party that is redirecting the call).

lineDevSpecific - Redirect Set Original Called ID

This function redirects calls to a specified destination while allowing the application to set the Original Called Party to any value. The Calling Search Space and Original Called Party that Cisco Unified TSP uses for this function follow:

Calling Search Space (CSS) — Uses CSS of the CallingParty (the party being redirected).

Original Called Party — Set to the preferredOriginalCalledID that the lineDevSpecific function specifies.

You can use this request to implement the Transfer to Voice Mail feature (TxToVM). Using this feature, applications can transfer the call on a line directly to the voice mailbox on another line. You can achieve TxToVM 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 is to be transferred as the preferredOriginalCalledID.

lineDevSpecific - Redirect FAC CMC

This function redirects calls to a specified destination that requires either a FAC, CMC, or both. The Calling Search Space and Original Called Party that Cisco Unified TSP uses for this function follow:

Calling Search Space (CSS) — Uses CSS of the CallingParty (the party being redirected).

Original Called Party — Not changed.

lineBlindTransfer

Use the standard TAPI lineBlindTransfer function to blind transfer calls to a specified destination. The Calling Search Space and Original Called Party that Cisco Unified TSP uses for this function follow:

Calling Search Space (CSS) — Uses CSS of the TransferringParty (the party that is transferring the call).

Original Called Party — Set to the TransferringParty (the party that is transferring the call).

lineDevSpecific - BlindTransfer FAC CMC

This function blind transfers calls to a specified destination that requires either a FAC, CMC, or both. The Calling Search Space and Original Called Party that Cisco Unified TSP uses for this function follow:

Calling Search Space (CSS) — Uses CSS of the TransferringParty (the party that is transferring the call).

Original Called Party — Set to the TransferringParty (the party that is transferring the call).

Extension Mobility Support

Extension Mobility, a Cisco Unified Communications Manager feature, allows a user to log in and log out of a phone. Cisco Extension Mobility loads a user Device Profile (including line, speed dial numbers, and so on) onto the phone when the user logs in.

Cisco Unified TSP recognizes a user who is logged into a device as the Cisco Unified TSP User.

Using Cisco Unified Communications Manager Administration, you can associate a list of controlled devices with a user.

When the Cisco Unified TSP user logs into the device, the system places the lines that are listed in the user Cisco Extension Mobility profile on the phone device, and removes lines previously on the phone. If the device is not in the controlled device list for the Cisco Unified TSP User, 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 Unified TSP sends notification events when a device has been added to or removed from the user-controlled device list in the directory. Cisco Unified TSP sends events when the user is deleted from Cisco Unified Communications Manager Administration.

Cisco Unified 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 controlled list or the device is removed from database.

When the system administrator deletes the current user, Cisco Unified 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 Unified TSP generates PHONE_REMOVE / PHONE_CREATE messages only if the application called the phoneInitialize function earlier.

The system generates a change notification if the device is added to or removed from the user by using Cisco Unified Communications Manager Administration or the Bulk Administration Tool (BAT).

If you program against the LDAP directory, change notification does not generate.


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-2. Multiple Cisco Unified TSPs help in scalability and higher performance.

Figure 1-2 Multiple Cisco Unified TSPs Connect to CTI Manager

Multiple Calls per Line Appearance

Maximum Number of Calls

Because the maximum number of calls per Line Appearance is database configurable, Cisco Unified TSP supports more than two calls per line on MCD (Multiple Call Display) devices. An MCD device is a device that can display more than two call instances per DN at any given time. For non-MCD devices, the Cisco Unified TSP supports a maximum of two calls per line. The absolute maximum number of calls per line appearance equals 200.

Busy Trigger

In Cisco Unified Communications Manager, the busy trigger setting indicates the limit on the number of calls per line appearance before the system will reject an incoming call. You can set the database-configurable busy trigger setting per line appearance, per cluster. The busy trigger setting replaces the old call waiting flag per DN. You cannot modify the busy trigger setting by using Cisco Unified TSP.

CFNA Timer

The Call Forward No Answer (CFNA) timer is database configurable per DN and per cluster. You cannot configure this timer by using Cisco Unified TSP.

Shared Line Appearance

Cisco Unified TSP supports opening two different lines that each share the same DN. Each of these lines represents a Shared Line Appearance.

The Cisco Unified Communications Manager allows multiple active calls to exist concurrently on each of the different devices that share the same line appearance. The system still limits each device to, at most, one active call and multiple hold or incoming calls at any given time. Applications that use the Cisco Unified TSP to monitor and control shared line appearances can support this functionality.

If a call is active on a line that is a shared line appearance with another line, the call appears on the other line with the dwCallState=CONNECTED and the dwCallStateMode=INACTIVE. Even though the call party information may not display on the actual IP phone for the call at the other line, Cisco Unified TSP still reports the call party information on the call at the other line. This gives the application the ability to decide whether to block this information. Also, the system does not allow call control functions on a call that is in the CONNECTED INACTIVE call state.

Cisco Unified TSP 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 should be obvious as Cisco Unified TSP and the Cisco Unified Communications Manager cannot resolve which of the shared DN's you are calling until the call is answered.

Select Calls

The "Select" softkey on IP phones lets a user select call instances 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 it cannot be selected by any of the shared line appearances. Pressing the "Select" key on a selected call will deselect the call.

Cisco Unified TSP does not support the "Select" function to select calls because all of the transfer and conference functions contain parameters that indicate on which calls the operation should be invoked.

Cisco Unified TSP supports the events that a user selecting a call on an application-monitored line causes. When a call on a line is selected, all other lines that share the same line appearance will see the call state change to dwCallState=CONNECTED and dwCallStateMode=INACTIVE.

Direct Transfer

In Cisco Unified Communications Manager, the "Direct Transfer" softkey lets users 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 does not initiate a consultation call and does not put the active call on hold.

A TAPI application can invoke the "Direct Transfer" feature by 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 by using the lineSetupTransfer() function.

Join

In Cisco Unified Communications Manager, the "Join" softkey joins all the parties of established calls (at least two) into one conference call. The "Join" feature does not initiate a consultation call and does not put the active call on hold. It also can include more than two calls, which results in a call with more than three parties.

Cisco Unified TSP exposes the "Join" feature as a new device-specific function that is known as lineDevSpecific() - Join. Applications can apply this function to two or more calls that are already in the established state. This also means that the two calls do not initially need to be set up using the lineSetupConference() or linePrepareAddToConference() functions.

Cisco Unified TSP also supports the lineCompleteTransfer() function with dwTransferMode=Conference. This function allows a TAPI application to join all the parties of two, and only two, established calls into one conference call.

Cisco Unified TSP also supports the lineAddToConference() function to join a call to an existing conference call that is in the ONHOLD state.

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

For example, in a scenario where 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:

A calls B. B answers. A puts the call on hold.

C calls A. A answers. C puts the call on hold.

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

D calls A. A answers.

At this point, the system presents the call to A, but not to to A'. This happens because the maximum calls for A' is set to 2.

A performs a Join operation either through the phone or by 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 system does not present the ensuing conference call to A'. Both calls on A' will go to the IDLE state. As the end result, A' will not see the conference call that exists on A.

Privacy Release

The Cisco Unified Communications Manager Privacy Release feature allows the user to dynamically alter the privacy setting. The privacy setting affects all existing and future calls on the device.

Cisco Unified TSP does not support the Privacy Release feature.

Barge and cBarge

Cisco Unified Communications Manager supports the Barge and cBarge features. The Barge feature uses the built-in conference bridge. The cBarge feature uses the shared conference resource.

Cisco Unified TSP supports the events that are caused by the invocation of the Barge and cBarge features. It does not support invoking either Barge or cBarge through an API of Cisco Unified TSP.

Cisco Unified TSP Auto Update Functionality

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

Update Cisco Unified TSP whenever a different version (higher version than the existing version) is available on the Cisco Unified Communications Manager server.

Update Cisco Unified TSP whenever a QBE protocol version mismatch exists between the existing Cisco Unified TSP and the Cisco Unified Communications Manager version.

Do not update Cisco Unified TSP by using Auto Update functionality.

QoS Support

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.

Compatibility

The Cisco TAPI Service Provider is a TAPI 2.1 service provider.

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.

Unicode Support

Cisco Unified TSP provides support for Unicode character sets.

Cisco Unified TSP will send Unicode party names to the application in all call events. You need to configure the party name in Cisco Unified Communications Manager Administration, and this support is limited to only party names. The system also sends locale information to the application. The system uses the UCS-2 encoding for Unicode.

The DevSpecific portion of the LINECALLINFO structure contains the party names.

TLS Support

Cisco Unified TSP supports security for signalling and media and provides secure CTI QBE signalling through TLS. This helps prevent security attacks like "man in the middle," spoofing, and eavesdropping. Signaling data passes over a secure channel and will be encrypted. No third party on the network can view the data on this secure connection. TLS support provides secure, encrypted, and authenticated signaling communication stream between TSP/CTI applications and the CTIManager. The system also uses this secure signaling path for SRTP keys exchange for media security.

SRTP Support

This release supports Secure RTP. The system will report detail SRTP key information to applications if there is secure connection to CTIManager and the application user is authorized to receive SRTP information. However, SRTP key information will not be available for mid-call events, except for the secure media indicator. The system sends the secure media indicator for each call on the device as a LineCallDevSpecific event following a PhoneDevSpecific request with the CPDST_REQUEST_RTP_SNAPSHOT_INFO message type.

During device registration, applications can specify algorithm IDs for SRTP.

FAC/CMC Support

Cisco Unified TSP supports and interacts with two Cisco Unified Communications Manager features: Forced Authorization Code (FAC) and Client Matter Code (CMC). The FAC feature lets the System Administrator require users to enter an authorization code to reach certain dialed numbers. The CMC feature lets the System Administrator require users to enter a client matter code to reach certain dialed numbers.

The system alerts a user of a phone that a FAC or CMC must be entered by sending a "ZipZip" tone to the phone that the phone in turn plays to the user. Cisco Unified TSP will send a new LINE_DEVSPECIFIC event to the application whenever the application should play a "ZipZip" tone. Applications can use this event to indicate when a FAC or CMC is required. For an application to start receiving the new LINE_DEVSPECIFIC event, it must perform the following steps:

1. lineOpen with dwExtVersion set to 0x00050000 or higher

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

The application can enter the FAC or CMC code with the lineDial() API. Applications can enter the code in its entirety or 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 optional "#" character at the end only serves to indicate dialing is complete.

If an application does a lineRedirect() or a lineBlindTransfer() to a destination that requires a FAC or CMC, then Cisco Unified TSP will return an error. The error that Cisco Unified TSP returns indicates whether a FAC, a CMC, or both are required. Cisco Unified 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 Port

Opening a CTI port device in 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.

Opening a CTI port in 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. 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.

Cisco Unified TSP allows TAPI applications to open a CTI port device in third-party mode via the lineDevSpecific API, if the application has negotiated at least extension version 6.0(1) and set the high order bit so that the extension version is set to at least 0x80050000.

The TAPI architecture lets two different TAPI applications running on the same PC use the same Cisco Unified TSP. In this situation, if both applications want to open the CTI port, problems could occur. Therefore, the first application to open the CTI port will control the mode in which the second application is allowed to open the CTI port. In other words, all applications that are running on the same PC, using the same Cisco Unified TSP, must open CTI ports in the same mode. If a second application tries to open the CTI port in a different mode, the lineDevSpecific() request fails.

CTI Device/Line Restriction

With CTI Device/Line restriction implementation, a CTIRestricted flag will be placed on device or line basis. When a device is restricted, it will assume that all its configured lines are restricted.

Cisco Unified TSP will 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 will treat it as normal device/line add or removal.

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. 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. The system exposes this feature as a Cisco Unified TSP device-specific extension.

The system only supports the PhoneDevSpecificDataPassthrough request for IP phone devices.

Intercom Support

The Intercom feature allows one user to call another user and have the call automatically answered with one-way media from the caller to the called party, regardless of whether the called party is busy or idle.

To ensure that no accidental voice of the called party is sent back to the caller, Cisco Unified Communications Manager implements a 'whisper' intercom, which means that only one-way audio from the caller is connected, but not audio from the called party. The called party must manually press a key to talk back to the caller. A zipzip (auto-answer) tone will play to the called party before the party can hear the caller's voice. For intercom users to know whether the intercom is using one-way or two-way audio, the lamp for both intercom buttons is colored amber for a one-way whisper Intercom and green for two-way audio. For TSP applications, only one RTP event occurs for the monitored party: either the intercom originator or the intercom destination, with the call state as whisper, in the case of a one-way whisper intercom.

TSP exposes the Intercom line indication and Intercom Speeddial information in DevSpecific of LineDevCap. The application can retrieve the information by issuing LineGetDevCaps. In the DevSpecific portion, TSP provides information that indicates (DevSpecificFlag = LINEDEVCAPSDEVSPECIFIC_INTERCOMDN) whether this is the Intercom line. You can retrieve the Intercom speeddial information in the DevSpecific portion after the partition field.

If a CTI port is used for the Intercom, the application should open the CTI port with dynamic media termination. TSP returns LINEERR_OPERATIONUNAVAIL if the Intercom line is opened with static media termination.


Note You cannot use CTI RoutePoint for the Intercom feature.


The administrator can configure the speed dial and label options from Cisco Unified Communications Manager Administration. However, the application can issue CciscoLineSetIntercomSpeeddial with SLDST_LINE_SET_INTERCOM_SPEEDDIAL to set or reset SpeedDial and Label for the Intercom line. The Application setting will overwrite the administrator setting that is configured in the database. Cisco Unified Communications Manager uses the application setting to make the intercom call until the line is closed or the application resets it. In the case of a Communications Manager or CTIManager failover, CTIManager or Cisco TSP is responsible for resetting the previous application's speeddial setting. If the application restarts, the application must reset the speeddial setting; otherwise, Cisco Unified Communications Manager will use the database setting to make the Intercom call. In any case, if resetting the speed dial or label fails, the system sends a LINE_DEVSPECIFIC event indicating the failure. When the application wants to release the application setting and have the speeddial setting revert to the database setting, the application can call CCiscoLineDevSpecificSetIntercomSpeedDial with a NULL value for SpeedDial and Label.

If the speed dial setting is changed, whether due to a change in the database or because the setting was overwritten by the application, the system generates a LineDevSpecific event to indicate the change. However, the application needs to call CCiscoLineDevSpecificSetStatusMsgs with DEVSPECIFIC_SPEEDDIAL_CHANGED to receive this notification. After receiving the notification, the application can call LineGetDevCaps to find out the current settings of speed dial and label.

Users can initiate an Intercom call by pressing the Intercom button at the originator or by issuing a LineMakeCall with a NULL destination if Speedial/Label is configured on the intercom line. Otherwise, LineMakeCall should have a valid Intercom DN.

For an intercom call, a CallAttribute field in LINECALLINFO::DEVSPECIFIC indicates whether the call is for the intercom originator or the intercom target.

After the Intercom call is established, the system sends a zipzip tone event to the application as a tone-changed event.

Users can invoke a TalkBack at the destination in two ways:

By pressing the Intercom button

By issuing CciscoLineIntercomTalkback with SLDST_LINE _INTERCOM_TALKBACK

TSP reports the Whisper call state in the extended call state bit as CLDSMT_CALL_WHISPER_STATE. If the call is being put on hold because the destination is answering an intercom call by using talk back, the system reports the call reason CtiReasonTalkBack in the extended call reason field for the held call.

The application cannot set line features, such as set call forwarding and set message waiting, other than to initiate the intercom call, drop the intercom call, or talk back. After the intercom call is established, the system limits call features for the intercom call. For the originator, only LINECALLFEATURE_DROP is allowed. For the destination, the system supports only the LINECALLFEATURE_DROP and TalkBack features for the whisper intercom call. After the intercom call has become two-audio after the destination initiates talkback, the system allows only LINECALLFEATURE_DROP at the destination.

Speed dial labels support Unicode.

Secure Conferencing Support

Prior to release 6.0(1), the security status of each call matched the status for the call between the phone and its immediately connected party, which is a conference bridge in the case of a conference call. No secured conference resource existed, so secure conference calls were not possible.

This release supports a secured conference resource to enable secure conferencing. The secure conferencing feature lets the administrator configure the Conference bridge resources with either a non-secure mode or an encrypted signaling and media mode. If the bridge is configured in encrypted signaling and media mode, the Conference Bridge will register to Cisco Unified Communications Manager as a secure media resource. This enables the user to create a secure conference session. When the media streams of all participants involved in the conference are encrypted, the conference is in encrypted mode. Otherwise, the conference is in non-secure mode.

The overall conference security status will be based on the least-secure call in the conference. For example, suppose parties A (secure), B(secure), and C(non-secure) are in a conference. Even though the conference bridge can support encrypted sRTP and is using that protocol to communicate with A and B, C is a non-secure phone. Thus, the overall conference security status is non-secure. Even though the overall conference security status is non-secure, because a secure conference bridge was allocated, all secure phones (in this case, A and B) will receive sRTP keys. TSP informs each participant about the overall call security status. The system provides the overall call security level of the conference to the application in the DEVSPECIFIC portion of LINECALLINFO to indicate whether the conference call is encrypted or non-secure.

The Secure Conferencing feature uses four fields to present the call security status:

DWORD CallSecurityStatusOffset;
DWORD CallSecurityStatusSize; 
DWORD CallSecurityStatusElementCount; 
DWORD CallSecurityStatusElementFixedSize;

The offset will point to following structure:

typedef struct CallSecurityStatusInfo
{
    DWORD CallSecurityStatus;
} CallSecurityStatusInfo;

The system updates LINECALLINFO whenever the overall call security status changes during the call due to a secure or non-secure party joining or leaving the conference.

A conference resource will be allocated to the conference creator based on the creator security capability. If no conference resource with the same security capability is available, the system allocates a less-secure conference resource to preserve existing functionality.

When a shared line is involved in the secure conference, the phone that has its line in RIU (remote in use) mode will not show a security status for the call. However, TSP exposes the overall security status to the application along with other call information for the inactive call. This means that TSP also reports the OverallSecurityStatus to all RIU lines. The status will match what is reported to the active line. Applications can decide whether to expose the information to the end user.

Additional Features Supported on SIP Phones

Release 6.0(1) extends support for SIP phones with these new features:

PhoneSetLamp (but only for setting the MWI lamp)

PhoneSetDisplay

PhoneDevSpecific (CPDST_SET_DEVICE_UNICODE_DISPLAY)

LineGenerateTone

Park and UnPark

The LINECALLREASON_REMINDER reason for CallPark reminder calls

PhoneGetDisplay (but only after a PhoneSetDisplay)


Note TSP does not pass through the Unicode name for SIP phones.


Silent Monitoring

Silent monitoring lets a supervisor eavesdrop on a conversation between an agent and a customer without allowing the agent to detect the monitoring session.

TSP provides a start monitoring type in the line DevSpecific request to allow applications to monitor calls on a per-call basis. Both the monitored and the monitoring party must be in the user's controlled list. The application must send a permanent lineID, monitoring Mode, and toneDirection as input to CCiscoLineDevSpecificStartCallMonitoring. The system supports only "silent monitoring" mode, in which a supervisor cannot talk to the agent. The application can specify whether a tone play when monitoring starts. The ToneDirection can be none (no tone played), local (tone played to the agent only), remote (tone played to both the customer and the supervisor), both local & remote (tone played to the agent, the customer, and the supervisor):

enum  PlayToneDirection
{
 PlayToneDirection_LocalOnly = 0,    
 PlayToneDirection_RemoteOnly,
 PlayToneDirection_BothLocalAndRemote,
 PlayToneDirection_NoLocalOrRemote
};

Monitoring of a call that is in the connected state on that line will start if the request is successful. This results in a new call between the supervisor and the agent. However, the call automatically gets answered by the agent's Built-in Bridge (BIB), and the agent will not be aware of the call. The call that is established between the supervisor and the agent is a one-way audio call. The supervisor receives the mixed stream of the agent and customer voices. The application can only invoke the monitoring session for a call after the call becomes active.

TSP sends a LINE_CALLDEVSPECIFIC (SLDSMT_MONITORING_STARTED) event to the agent call when the supervisor starts monitoring the call. TSP provides call attribute information for the monitored party (deviceName, DN, and Partition) to the monitoring party in the DEVSPECIFIC portion of LINECALLINFO after monitoring has started. Similarly, TSP provides call attribute information for the monitoring party (deviceName, DN, and Partition) to the monitored party in devspecific data of LINECALLINFO after monitoring has started.

The monitoring session terminates when either the agent or the customer ends the agent-customer call. The supervisor can also terminate the monitoring session by dropping the monitoring call. TSP will inform the agent by sending a LINE_CALLDEVSPECIFIC (SLDSMT_MONITORING_ENDED) event when the supervisor drops the call. TSP will not send the event if the monitoring session ended after the agent dropped the call.

Call Recording

Call recording provides two ways of recording the conversation between the agent and the customer:

Automatic recording of all calls

Application-invoked selective call recording

A line appearance configuration determines which mode is enabled. Administrators can disable recording or configure either of the two preceding options. Applications cannot override the recording configuration on a line appearance. TSP reports 'Recording type' information to the application in the devSpecificData object of the LineDevCaps structure. Whenever a change occurs in 'Recording Type', TSP sends a LINE_DEVSPECIFIC(SLDSMT_LINE_PROPERTY_CHANGED with indication of LPCT_RECORDING_TYPE) event to the application.

If automatic call recording is enabled, the system triggers a recording session whenever a call is received or initiated from the line appearance. When application-invoked call recording is enabled, the application can start a recording session by using CCiscoLineDevSpecificStartCallRecording (SLDST_START_CALL_RECORDING) on the call after the call becomes active. Thus, selective recording can start in the middle of the call, whereas the automatic recording always starts at the beginning of the call. Configure the recorder in Cisco Unified Communications Manager as a SIP trunk device. An application cannot override the recorder DN.

TSP provides a start recording request in a lineDevSpecific event to the application for establishing a recording session. The application needs to provide toneDirection as input to TSP in the start recording request. As the result of the recording session, the two media streams of the recorded call (agent-customer call) get relayed from the agent phone to the recorder. TSP provides the agent Call Handle in the devSpecificData of LINECALLINFO.

TSP informs the application when recording has started on its call by sending a LINE_CALLDEVSPECIFIC (SLDSMT_RECORDING_STARTED ) event. TSP provides recording call attribute information (deviceName, DN, Partition) in the devspecific data of LINECALLINFO after recording has started.

The system terminates the recording session when the call ends or the application sends a stop recording request to TSP through lineDevSpecific — CciscoLineDevSpecificStopCallRecording (SLDST_STOP_CALL_RECORDING). TSP will inform the agent by sending a LINE_CALLDEVSPECIFIC (SLDSMT_RECORDING_ENDED) event when a stop recording request stops the recording.

Be aware that both recording and monitoring are supported only for IP Phones and CTI-supported SIP phones within one cluster. Applications can invoke these features only on phones that support built-in bridges. The built-in bridge should be turned on to monitor or record calls on a device. The monitoring party need not have a configured BIB.


Note The system does not support recording and monitoring for secure calls.


You can find the call attributes in the DEVSPECIFIC portion of the LINECALLINFO structure. The system presents the call attribute information in array format because monitoring and recoding could happen at the same time.

DWORD CallAttrtibuteInfoOffset;
DWORD CallAttrtibuteInfoSize;
DWORD CallAttrtibuteInfoElementCount;
DWORD CallAttrtibuteInfoElementFixedSize;

where the offset is pointing to array of the following structure:

typedef struct CallAttributeInfo
{
    DWORD CallAttributeType;
    DWORD PartyDNOffset;
    DWORD PartyDNSize;
    DWORD PartyPartitionOffset;
    DWORD PartyPartitionSize;
    DWORD DeviceNameOffset;
    DWORD DeviceNameSize;
}CallAttributeInfo;

and where enum CallAttributeType is

{
	CallAttribute_Regular                   		 = 0,
	CallAttribute_SilentMonitorCall,  
	CallAttribute_SilentMonitorCall_Target,
	CallAttribute_RecordedCall
} ;

Conference Enhancements

Conference enhancements in this release include

Allowing a noncontroller to add another party into an ad hoc conference.

Applications can issue the lineGetCallStatus against a CONNECTED call of a noncontroller conference participant and check the dwCallFeatures before adding another party into the conference. The application should have the PREPAREADDCONF feature in the dwCallFeatures list if the participant is allowed to add another party.

Allowing multiple conferences to be chained.

Be aware that these features are only available if the 'Advanced Ad-hoc Conference' service parameter is enabled on the Cisco Unified Communications Manager.

When this service parameter is changed from enabled to disabled, the system no longer allows new chaining between ad hoc conferences. However, existing chained conferences will stay intact. Any participant brought into the ad hoc conference by a noncontroller before this change will remain in the conference, but they can no longer add a new participant or remove an existing participant.

To avoid ad hoc conference resources remaining connected together after all real participants have left, Cisco Unified Communications Manager will disallow having more than two conference resources connected to the same ad hoc conference. However, using a star topology to connect multiple conferences could yield better voice quality than a linear topology. A new advanced service parameter, 'Non-linear Ad Hoc Conference Linking Enabled', lets an administrator select the star topology.

A participant can use the conference, transfer, or join commands to chain two conferences together. When two conferences are chained together, each participant only sees the participants from their own conference, and the chained conference appears as a participant with a unique conference bridge name. In other words, participants do not have a full view of the chained conference. Thesystem treates the conferences as two separate conferences, even though all the participants are talking to each other.

Figure 1-3 shows how TSP presents a conference model in the case of conference chaining. A, B, and C are in conference-1, and C, D, and E are in conference-2. C has an ONHOLD call on conference-1 and an active call on conference-2.

Figure 1-3 Conference Before Join

C then does a join with the primary call from conference-1. For A, B, and C, the conference participants comprise A, B, C and conference-2. For D and E, the conference participants comprise D, E, and conference-1.

Figure 1-4 Conference After Join

When a user removes a CONFERENCE from its conference list on the phone, the operation actually drops the chained conference bridge. In the previous example, the two chained conferences have been unchained. Conference-1 will remain active and has A, B, and C as participants. However, conference-2 will become a direct call between Dave and Ed because they are the only two parties left in the conference.

Aplications can achieve conference chaining by issuing a JOIN or TRANSFER on two separated conference calls. However, a LineCompleteTransfer with a conference option will fail due to a Microsoft TAPI limitation on this standard API. The application can use the Cisco LineDevSpecific extension to issue the join request to chain multiple conference together.

Arabic and Hebrew Language Support

Release 6.0(1) supports the Arabic and Hebrew languages. Users can select these languages during installation and also in the Cisco TSP settings user interface.

Silent Install Support

The Cisco TSP installer now supports silent install, silent upgrade, and silent reinstall from the command prompt. Users do not see any dialog boxes during the silent installation.

Do Not Disturb

The Do Not Disturb (DND) feature lets phone users go into a Do Not Disturb state on the phone when they are away from their phone or simply do not want to answer incoming calls. The phone softkey DND enables and disables this feature.

From theCisco Unified Communications Manager user windows, users can select the DND option DNR (Do Not Ring).

Cisco TSP makes the following phone device settings available for DND functionality:

DND Option: None/Ringer off

DND Incoming Call Alert: Beep only/flash only/disable

DND Timer: a value between 0-120 mins. It specifies a period in minutes to remind the user that DND is active.

DND enable and disable

Cisco TSP includes DND feature support for TAPI applications that negotiate at least extension version 8.0 (0x00080000).

Applications can only enable or disable the DND feature on a device. Cisco TSP allows TAPI applications to enable or disable the DND feature via the lineDevSpecificFeature API.

Cisco TSP notifies applications via the LINE_DEVSPECIFICFEATURE message about changes in the DND configuration or status. To receive change notifications, an application must enable the DEVSPECIFIC_DONOTDISTURB_CHANGED message flag with a lineDevSpecific SLDST_SET_STATUS_MESSAGES request.

This feature applies to phones and CTI ports. It does not apply to route points.

Translation Pattern


Warning TSP does not support the translation pattern because it may cause a dangling call in a conference scenario. The application needs to clear the call to remove this dangling call or simply close and reopen the line.