Cisco Unified TAPI Developers Guide for Cisco Unified Communications Manager Release 7.0(1)
New and Changed Information
Downloads: This chapterpdf (PDF - 317.0KB) The complete bookPDF (PDF - 8.21MB) | Feedback

New and Changed Information

Table Of Contents

New and Changed Information

Cisco Unified Communications Manager Release 7.0(1)

Join Across Lines (SIP)

Localization Infrastructure Changes

Do Not Disturb-Reject

Calling Party Normalization

Click to Conference

Microsoft Windows Vista

Cisco Unified Communications Manager Release 6.1(x)

Join Across Lines (SCCP)

Cisco Unified Communications Manager Release 6.0(1)

Intercom Support

Secure Conferencing Support

Do Not Disturb

Conference Enhancements

Arabic and Hebrew Language Support

Additional Features Supported on SIP Phones

Silent Monitoring

Silent Recording

Calling Party IP Address

Backward Compatibility

Cisco Unified Communications Manager Release 5.1

Partition Support

Alternate Script

Secure RTP

SuperProvider

Refer and Replaces for SIP Phones

SIP URL Address

3XX

Secure TLS Support

Monitoring Call Park Directory Numbers

Super Provider Support

Cisco Unified Communications Manager Release 5.0

Unicode Support

Line-Side SIP Phones

Cisco Unified Communications Manager Release 4.x

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

Direct Transfer

Join

Set the Original Called Party upon Redirect

Cisco Unified TSP Auto Update

Multiple Calls per Line Appearance

Maximum Number of Calls

Busy Trigger

Call Forward No Answer Timer

Shared Line Appearance

Select Calls

Forced Authorization Code and Client Matter Code

CTI Port Third-Party Monitoring Port

Translation Pattern


New and Changed Information


This chapter describes new and changed Cisco Unified TAPI Service Provider (TSP) information for Cisco Unified Communications Manager. For feature changes and additions for all Cisco Unified Communications Manager releases beginning with Release 3.x, see Appendix D, "Cisco Unified TAPI Matrices." See Chapter 3, "Features Supported by TSP" for additional feature information.

Refer to the programming guides website for prior Cisco JTAPI Developer Guides at http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_
list.html
.

This chapter contains the following sections:

Cisco Unified Communications Manager Release 7.0(1)

Cisco Unified Communications Manager Release 6.1(x)

Cisco Unified Communications Manager Release 6.0(1)

Cisco Unified Communications Manager Release 5.1

Cisco Unified Communications Manager Release 5.0

Cisco Unified Communications Manager Release 4.x

Cisco Unified Communications Manager Release 7.0(1)

This section describes new and changed features supported in Cisco Unified Communications Manager Release 7.0(1) and contains the following:

Join Across Lines (SIP)

Localization Infrastructure Changes

Do Not Disturb-Reject

Calling Party Normalization

Click to Conference

Microsoft Windows Vista

Join Across Lines (SIP)

This feature allows two or more calls on different lines of the same device to be joined by using the join operation. Applications can use the existing join API to perform the task. When the join across line happens, the consultation call on the different line that the survival call does not reside on will be cleared, and a CONFERENCED call that represents the consultation call will be created on the primary line where conference parent is created. This feature should have no impact when joining multiple calls on the same line.

This feature is supported both on SCCP and SIP devices that can be controlled by CTI. In addition, this feature also supports chaining of conference calls on different lines on the same device. Also, a join across line can be performed on a non-controller (the original conference controller was on a different device then where the join is being performed) line.

This feature returns an error if one of the lines involved in the Join Across Lines is an intercom line.

Interface Changes

There are no interface changes for this feature.

Message Sequences

See Join Across Lines, page A-73.

Backwards Compatibility

This feature is backward compatible.

Localization Infrastructure Changes

Beginning with Release 7.0(1), the TSP localization is automated. The TSP UI can download the new and updated locale files directly from a configured TFTP sever location. As a result of the download functionality, Cisco TSP install supports only the English language during the installation.

During installation, the TFTP server IP address is input by the user. When the user opens the TSP interface for the first time, the TSP interface automatically downloads the locale files from the configured TFTP server and extracts those files to the resources directory. The languages tab in the TSP preferences UI also provides functionality to update the locale files.


Note To upgrade from Cisco Unified Communications Manager, Release 6.0(1) TSP to Cisco Unified Communications Manager, Release 7.0(1) TSP, Release 6.0(1) TSP must have been installed by using English. If Release 6.0(1) TSP is installed using any language other than English and if the user upgrades to Release 7.0(1) TSP, then the user must manually uninstall Release 6.0(1) TSP from Add/Remove programs in control panel and then perform a fresh install of Release 7.0(1) TSP.


Interface Changes

There are no interface changes for this feature.

Message Sequences

There are no message sequences for this feature.

Backward Compatibility

Only English locale is packaged in Cisco TSP installer. The TSP UI downloads the locale files from the configured TFTP server so that the end user can select the required and supported locale after the installation.

Do Not Disturb-Reject

Do Not Disturb (DND) is enhanced to support the rejection of a call. The enhancement is called Do Not Disturb-Reject (DND-R). DND-R enables the user to reject any calls when necessary. Prior to the Cisco Unified Communications Manager Release 7.0(1), DND was available only with the Ringer Off option. If DND was set, the call would still be presented but without ringing the phone.

To enable DND-R, access the Cisco Unified Communications Manager Administration phone page or the user can enable it on the phone.

However, if the call has an emergency priority set, the incoming call is presented on the phone even if the DND-R option is selected. This will make sure that emergency calls are not missed.

Feature priority is introduced and defined in the "enum type" for making calls or redirecting existing calls. The priority as defined as:

enum CiscoDoNotDisturbFeaturePriority {
CallPriority_NORMAL=1
CallPriority_URGENT=2
CallPriority_EMERGENCY=3
};

Feature priority introduces LineMakeCall as part of DevSpecific data. Currently the following structure is supported in DevSpecific data for LineMakeCall:

typedef struct LineParams {
	DWORD FeaturePriority;
} LINE_PARAMS;

The new Cisco LineDevSpecific extension, CciscoLineRedirectWithFeaturePriority with type SLDST_REDIRECT_WITH_FEATURE_PRIORITY, supports redirected calls with feature priority.

Also in a shared line scenario, if one of the lines is DND-R enabled and if the Remote In Use is true, then it will be marked as connected inactive.

Interface Changes

See lineMakeCall, page 5-34 and Redirect with Feature Priority, page 6-37.

Message Sequences

See Do Not Disturb-Reject, page A-70.

Backward Compatibility

This feature is backward compatible.

Calling Party Normalization

Prior to the Cisco Unified Communication Manager Release 7.0(1), the "+" symbol was not displayed. There was no support for displaying the localized or global number of the caller to the called party on its alerting display and the entry into its call directories for supporting a callback without the need of an EditDial.

Support for "+" symbol is added and also the calling number is globalized and passed to the application. This enables the end user to dial back without using EditDial. Along with the globalized calling party, the user would also get the number type of the calling party. This would help the user to know from where the call originated i.e whether it is a SUBSCRIBER, NATIONAL or INTERNATIONAL number.

Interface Changes

See LINECALLINFO, page 6-6.

Message Sequences

See Calling Party Normalization, page A-66.

Backward Compatibility

This feature is backward compatible.

Click to Conference

Click to Conference enables users to create conferences from an Instant Messaging (IM) application without creating a consult call first. The Cisco TSP treats the feature as an existing conference model. However, when the conference is created or dropped, the CtiExtendedReason may come as Click2Conference.

Interface Changes

There are no interface changes for this feature.

Message Sequences

See Click to Conference, page A-57.

Backward Compatibility

This feature is backward compatible.

Microsoft Windows Vista

The Cisco TSP client is supported on Microsoft Windows Vista operating system with the following workarounds:

The initial installation of the Cisco TSP and Cisco Unified Communications Manager TSP Wave Driver should always be performed as a fresh install.

If a secure connection to Cisco Unified Communications Manager is used, the Windows Firewall should be turned off/disabled.

If Cisco Unified Communications Manager TSP Wave Driver is used for inbound audio streaming, the Windows Firewall should be turned off/disabled.

If Cisco Unified Communications Manager TSP Wave Driver is used for audio streaming, all other devices in the Sound, Video, and Game Controllers group must be disabled.

Cisco Unified Communications Manager Release 6.1(x)

This section describes new and changed features supported in Cisco Unified Communications Manager Release 6.1(x) and contains the following:

Join Across Lines (SCCP)

Join Across Lines (SCCP)

This feature allows two or more calls on different lines of the same device to be joined through the join operation. Applications can use the existing join API to perform the task. When the join across line happens, the consultation call on the different line that the survival call does not reside on will be cleared, and a CONFERENCED call that represents the consultation call will be created on the primary line where conference parent is created. This feature should have no impact when joining multiple calls on the same line.

This feature is supported SCCP devices that can be controlled by CTI. In addition, this feature also supports chaining of conference calls on different lines on the same device. Also, a join across line can be performed on a non-controller (the original conference controller was on a different device then where the join is being performed) line.


Note This feature returns an error if one of the lines involved in the Join Across Lines is an intercom line.


Backwards Compatibility

This feature is backward compatible.

Cisco Unified Communications Manager Release 6.0(1)

This section describes new and changed features supported in Cisco Unified Communications Manager Release 6.0(1) and contains the following:

Intercom Support

Secure Conferencing Support

Do Not Disturb

Conference Enhancements

Arabic and Hebrew Language Support

Additional Features Supported on SIP Phones

Silent Monitoring

Silent Recording

Calling Party IP Address

Backward Compatibility

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 zip-zip (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 Route Point 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 LINECALLINFODEVSPECIFIC indicates whether the call is for the intercom originator or the intercom target.

After the Intercom call is established, the system sends a zip-zip 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.

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.

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. The system treats the conferences as two separate conferences, even though all the participants are talking to each other.

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

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

Additional Features Supported on SIP Phones

Cisco Unified Communications Manager 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 Unicode name for SIP phones.


Silent Monitoring

Silent monitoring is a feature that enables a supervisor to eavesdrop on a conversation between an agent and a customer without the agent detecting the monitoring session. TSP provides monitoring type in line DevSpecific request for applications to monitor calls on a per call basis. Both monitored and monitoring party have to be in controlled list of the user.

The Application is required to send permanent lineID, monitoring Mode and toneDirection as input to CCiscoLineDevSpecificStartCallMonitoring. Only silent monitoring mode is supported and the supervisor cannot talk to the agent.

The Application can specify if a tone should be played when monitoring starts. ToneDirection can be none (no tone played), local (tone played to Agent only), remote (tone played to Customer and Supervisor), both local and remote (tone played to agent, customer, and supervisor).

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

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

TSP will send LINE_CALLDEVSPECIFIC (SLDSMT_MONITORING_STARTED) event to the agent call when supervisor starts monitoring the call. TSP will provide monitored party's call attribute information (deviceName, DN, Partition) to the monitoring party in DEVSPECIFIC portion of LINECALLINFO after monitoring has started. Similarly, TSP will provide monitoring party's call attribute information (deviceName, DN, Partition) to the monitored party in devspecific data of LINECALLINFO after monitoring has started.

The monitoring session will be terminated when the agent-customer call is ended by either the agent or the customer. The supervisor can also terminate the monitoring session by dropping the monitoring call.TSP will inform agent by sending LINE_CALLDEVSPECIFIC (SLDSMT_MONITORING_ENDED) when supervisor drops the call. The event will not be sent if monitoring session has been ended after agent dropped the call.

Silent Recording

Call recording is a feature that provides two ways of recording the conversations between the agent and the customer: the automatic call recording and the application invoked selective call recording. A line appearance configuration determines which mode is enabled. Administrators can configure no recording, automatically record all calls or per call based recording through application control. The recording configuration on a line appearance cannot be overridden by an application. TSP will report `Recording type' info to app in devSpecificData of LineDevCaps structure. Whenever there is a change in `Recording Type', TSP will send LINE_DEVSPECIFIC (SLDSMT_LINE_PROPERTY_CHANGED with indication of LPCT_RECORDING_TYPE) event to application.

If the automatic call recording is enabled, a recording session will be triggered whenever a call is received or initiated from the line appearance. When the application invoked call recording is enabled, application can start a recording session by using CCiscoLineDevSpecificStartCallRecording (SLDST_START_CALL_RECORDING) on the call after it becomes active. The selective recording can occur in the middle of the call, whereas the automatic recording always starts at the beginning of the call.The recorder is configured in CallManager as a SIP trunk device. Recorder DN can not be overridden by an application.

TSP will provide start recording request in lineDevSpecific to app for establishing a recording session. Application need to provide toneDirection as input to TSP in the start recording request. The result of the recording session is that the two media streams of the recorded call (agent-customer call) is being relayed from agent's phone to the recorder. TSP will provide agent's CCM Call Handle in the devSpecificData of LINECALLINFO.

TSP will inform application when recording has started on its call by sending LINE_CALLDEVSPECIFIC (SLDSMT_RECORDING_STARTED ) event. TSP will provide recording call attribute info (deviceName, DN, Partition) in devspecific data of LINECALLINFO after recording has started.

The recording session will be terminated when the call is ended or if app sends stop recording request to TSP through lineDevSpecific - CciscoLineDevSpecificStopCallRecording (SLDST_STOP_CALL_RECORDING).TSP will inform agent by sending LINE_CALLDEVSPECIFIC (SLDSMT_RECORDING_ENDED) when recording is stopped by stop recording request.

Both recording and monitoring are supported only for IP Phones/CTI supported SIP phones and within one cluster. It can be invoked only on phones that support built in bridges. Also built in bridge should be turned on to monitor or record calls on a device. Monitoring party need not have a BIB configured. Recording and monitoring will not be supported for secure calls in this phase.

Call Attributes

Call Attributes can be found in DEVSPECIFIC porting of LINECALLINFO structure. The Call Attribute Info is presented in the format of an array since Silent Monitoring and Recoding could happen at the same time.

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

Offset 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;

enum CallAttributeType

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

Calling Party IP Address

The Calling Party IP Address feature provides the IP address of the calling party. The calling party device must be supported and must be an IP phones. The IP address is provided to applications in the devspecific data of LINECALLINFO. A value of zero (0) indicates that the information in not available.

The enhancement provides the IP address to the destination side of basic calls, consultation calls for transfer and conference, and basic redirect and forwarding. If the calling party changes, no support is provided.

Message Sequence

See Calling Party IP Address, page A-56.

Backward Compatibility

There is no backward compatibility issues for any features introduced in Cisco Unified Communications Manage Release 6.0(1).

Cisco Unified Communications Manager Release 5.1

This section describes new and changed features supported in Cisco Unified Communications Manager, Release 5.1 and contains the following:

Partition Support

Alternate Script

Secure RTP

SuperProvider

Refer and Replaces for SIP Phones

SIP URL Address

3XX

Secure TLS Support

Monitoring Call Park Directory Numbers

Super Provider Support

Partition Support

The CiscoTSP support of this feature will provide Partition support information. Prior to this release, CiscoTSP only reported partial information about the DNs to the applications in that it would report the numbers assigned but not the information about which partitions they were associated with.

Thus, if a phone has 2 lines configured both with same DNs - one in Partition P1 and the other in P2, a TSP application would not be able to distinguish between these two and consequently would be able to open only 1 line of these two.

In this release, CiscoTSP will provide the partition information about all DNs to the applications. Thus, the above limitation would be overcome and applications would be able to distinguish between and open 2 lines on a device, which share the same DN but belong to different partitions.

TSP applications can query for LINEDEVCAPS where the partition information is stored in the devSpecific portion of the structure.Application will receive the Partition info for the CallerID, CalledID, ConnectedID, RedirectionID and RedirectingID in a call. This will be provided as a part of DevSpecific Portion of the LINECALLINFO structure.

Also, the Partition info of the Call Park DN at which the call was parked will also be sent to the applications. The value of the partition info would be sent to applications in ASCII format.


Note Opening of a line from the application point of view will remain unchanged as before.


Alternate Script

Certain IP phone types support an alternate language script other than the default script corresponding to the phone configurable locale. For example, the Japanese phone locale is associated two written scripts. Some phone types support only the default "Katakana" script, while other phones types support both the default "Katakana" script and the alternate "Kanji" script. Since applications can send text information to the phone for display purposes, they need to know what alternate script a phone supports - if any.

Secure RTP

The secure RTP (SRTP) feature will allow Cisco TSP to report SRTP information to application as well as allow application to specify SRTP algorithm Ids during device registration. The SRTP information provided by Cisco TSP will include master key, master salt, algorithmID, isMKIPresent and keyDerivation. In order to receive those key materials, administrator needs to configure TLS Enabled and SRTP Enabled flag in CallManager Admin User pages and TLS link need to be established between TSP and CTIManager.

Besides, during device registration, application has an option to provide SRTP algorithm ids for CTI port and CTI Route Point in case of media termination by application. Application should use new Cisco extension for Line_devSpecific - CciscoLineDevSpecificUserSetSRTPAlgorithmID to set supported SRTP algorithm IDs after calling LineOpen with 0x80070000 version or higher negotiated, then followed by either CCiscoLineDevSpecificUserControlRTPStream or CciscoLineDevSpecificPortRegistrationPerCall to allow TSP to open device on CTI Manager.

When call arrives on an opened line, TSP will send LINE_CALLDEVSPECIFIC event to application with secure media indicator, then application should query LINECALLINFO to get detail SRTP information if SRTP information is available. The SRTP information will be in the DevSpecific portion of the LINECALLINFO structure.

In case of mid-call monitoring, Cisco TSP will send LINE_CALLDEVSPECIFIC with secure media indicator, however there will be no SRTP info available for retrieval under this scenario. The event is only sent upon application request via PhoneDevSpecific with CPDST_REQUEST_RTP_SNAPSHOT_INFO message type.

In order to support SRTP using static registration, we introduced generic mechanism for delayed device/line. The following are introduced with this release:

Extension version bit SELSIUSTSP_LINE_EXT_VER_FOR_DELAYED_OPEN = 0x40000000

CiscoLineDevSpecificType - SLDST_SEND_LINE_OPEN

CCiscoLineDevSpecific - CciscoLineDevSpecificSendLineOpen

If application negotiates with 0x00070000 in lineOpen against CTI port, TSP will do LineOpen/DeviceOpen immediately. This is the same behavior as implemented today. If application negotiates with 0x40070000 in LineOpen against CTI port, TSP will delay the LineOpen/DeviceOpen. Application can specify SRTP algorithm id using CciscoLineDevSpecificUserSetSRTPAlgorithmID (SLDST_USER_SET_SRTP_ALGORITHM_ID). However, in order to trigger actual device/line open in TSP, application needs to send CciscoLineDevSpecificSendLineOpen(SLDST_SEND_LINE_OPEN)

If application negotiates with 0x80070000 in LineOpen against CTI port/RP, TSP will delay the LineOpen/DeviceOpen until application specifies media information in CCiscoLineDevSpecific. However, application can use CciscoLineDevSpecificUserSetSRTPAlgorithmID (SLDST_USER_SET_SRTP_ALGORITHM_ID) to specify SRTP algorithm id before specifying the media information.

If application negotiates with 0x40070000 in LineOpen against RP, TSP should fail CciscoLineDevSpecificUserSetSRTPAlgorithmID (SLDST_USER_SET_SRTP_ALGORITHM_ID) request since RP should have media terminated by application.

Currently, the SELSIUSTSP_LINE_EXT_VER_FOR_DELAYED_OPEN bit is only used on CTI port when using TSP Wave Driver to terminate media. Under conference scenario, the SRTP information will be stored in conference parent call for each party. Application that negotiates with correct version and interested in SRTP info in conference scenario, should retrieve SRTP information from CONNECTED call of particular conference party.

Backwards Compatibility

CCiscoLineDevSpecific extension

CciscoLineDevSpecificUserSetSRTPAlgorithmID is defined.

CCiscoLineDevSpecific extension CciscoLineDevSpecificSendLineOpen is defined. An extra LINE_CALLDEVSPECIFIC event will be sent if application's negotiated version supports this feature while keeping existing LINE_CALLDEVSPECIFIC for reporting existing RTP parameters.

The srtp_policy is used by wave driver (media terminating endpoint) to create a crypto context. It should match to encrypt and decrypt packets sent/received by IPPhones/CTIPorts. Phone is using one hardcoded srtp_policy for all phone types including sip phones.

policy->cipher_type = AES_128_ICM;

policy->cipher_key_len = 30;

policy->auth_type = HMAC_SHA1;

policy->auth_key_len = 20;

policy->auth_tag_len = 4;

policy->sec_serv = sec_serv_conf_and_auth;


Note Applications should not store key material and must use proper security method to ensure confidentially of the key material. Application should clear out memory after key info is processed. Applications are subject to export control when they provide mechanism to encrypt the data (SRTP). Applications should get export clearance for that.


SuperProvider

SuperProvider functionality allows a TSP application to control any CTI controllable device in the system (IP Phones, CTI Ports, CTI Route Points etc). Normally, a TSP application has to have an associated list of devices that it can control. It cannot control any devices that are outside of this list. However, certain applications would want to control a large number (possibly all) the CTI controllable devices in the system.

SuperProvider functionality enables the administrator to configure a CTI application as a "SuperProvider". This will mean that particular application can control absolutely any CTI controllable device in the system.

Previously, the SuperProvider functionality was never exposed to TSP apps i.e, TSP application needed to have the device in the controllable list. In this release, TSP apps can control any CTI controllable device in the CallManager system.

The SuperProvider apps need to explicitly `Acquire' the device before opening them. In this release, TSP will expose new interfaces to the apps to explicitly Acquire/Deacquire any device in the system. The device info will be fetched for the explicitly acquired device using the SingleGetInfoFetch API exposed via QBE by CTI. Later, TSP will fetch the line info for this device using the LineInfoFetch API. The lines of this device will be reported to the app using the LINE_CREATE/PHONE_CREATE events.

The apps can explicitly `De-Acquire' the device. After the device is successfully de-acquired, TSP will fire LINE_REMOVE/PHONE_REMOVE events to the apps.

TSP also supports Change Notification of "Super-Provider" flag. If the administrator has configured a User as a "Super-Provider" in the admin pages, then the status of this is changed and the user is no more a Super-Provider, then CTI will inform the same to TSP in ProviderUserChangedEvent. If any device had been explicitly acquired and opened in super-provider mode, then TSP will fire PHONE_REMOVE/LINE_REMOVE to the app indicating that the device/line is no more available for the app to use.

In this release, TSP supports change notification of CallParkDN Monitoring as well. Say, the user has been configured to allow monitoring of CallParkDN in the admin pages, now the status of this flag is disabled. Then TSP will fire LINE_REMOVE for the CallParkDNs.

Say, initially the CallParkDN Monitoring is disabled, now the status is changed to enabled, then TSP will fetch all the CallParkDNs from CTI and fire LINE_CREATE for each of the CallParkDNs.

Refer and Replaces for SIP Phones

As part of CTI SIP Phone support, TSP will support new SIP features Refer and Replaces. Refer, Refer with Replaces, Invite with Replaces are different mechanisms to initiate different call control features. E.g. Refer with Replaces in SIP terms can be translated to Transfer operation in CCM world. Invite with

Replaces can be used for Pickup call feature across SIP trunks. TSP will support event handling corresponding to the features initiated by CCM SIP Phones/ third party SIP Phones. TSP will not support Refer / Replaces request initiation from the API. Since TAPI does not have Refer/Replaces feature related reason codes defined, the standard TAPI reason will be LINECALLREASON_UNKNOWN. TSP will provide new call reason to user as part of LINE_CALLINFO::dwDevSpecificData if the application has negotiated extension version greater equal to 0x00070000.

For In-dialog refer, TSP will put Referrer in LINECALLSTATE_UNKNOWN | CLDSMT_CALL_WAITING_STATE call state with extended call reason as CtiCallReasonRefer. This will help present the Referrer's call leg such that applications can not call any other call functions on this call. Any request on this call when it is in LINECALLSTATE_UNKNOWN | CLDSMT_CALL_ WAITING_STATE will return an error as LINEERR_INVALCALLSTATE.

It is up to the Referrer to clear this call once the Refer request is initiated. If Referrer does not drop the call, then Refer feature will clear this call if the refer is successful. LINECALLSTATE_IDLE with extended reason as CtiCallReasonRefer will be reported.

If Referrer does not drop the call and if Refer request fails (e.g. Refer to target is busy) refer feature will restore the call between Referrer and Referee.

With Cisco Call Manager SIP Phones, Call Manager makes all the existing call features transparent such that applications will get the existing events when the phone invokes a SIP feature whose behavior matches with the call manager's existing feature. For example, When Refer with Replaces is called by SIP phone (with both primary and secondary/consult call legs on same SIP line) within CCM cluster, all the events will be reported same as that of Transfer feature.

SIP URL Address

As part of CTI SIP Phone support, TSP will expose SIP URL received in Device/Call event received from CTIManager. The SIP URL will be presented for each corresponding party in extended call info structure of LINE_CALLINFO::dwDevSpecificData.

When SIP trunk is involved in a call, the DN may not be presented in party information. Application then needs to take a look at SIP URL information under this call scenario for information.

TSP will provide SIP URL information to user as part of LINE_CALLINFO::dwDevSpecificData if the application has negotiated extension version greater equal to 0x00070000.

The following features or functions are supported on CTI SIP Phones:

Call Initiate

Call Answer

Call Close/Disconnect

Consult Transfer

Direct Transfer

Call Join

Conference

Hold/unhold

Line Dial

Redirect

lineDevSpecific (SLDST_MSG_WAITING)

lineDevSpecific (SLDST_MSG_WAITING_DIRN)

3XX

No interface change for TSP 3XX support. The CTI reason code for 3XX will be mapped to REDIRECT by Cisco TSP. When a call arrives on a monitored line due to 3XX feature, the call reason for the incoming call will be REDIRECT in this case.

Backward Compatibility

This feature is backward compatible.

Secure TLS Support

Establishing secure connection to CTIManager involves application user to configure more information through Cisco TSP UI screens. This information will help TSP to create its own client certificate. This certificate will be used to create a mutually authenticated secure channel between TSP and CTIManager.

TSP UI will add a new tab called Security and the options available on this tab are as follows:

Check box for Secure Connection to CTIManager: If checked TSP will connect over TLS CTIQBE port (2749), else TSP will connect over CTIQBE port (2748).

Default setting is non secure connection and the setting will be unchecked.

It is important that the security flag for the TSP user must be enabled through Cisco Unified Communications Manager Administration as well. CTIManager will perform a verification check whether a user connecting on TLS is allowed to have secure access. CTIManager will allow only security enabled users to connect to TLS port 2749 and only nonsecure users to connect to CTIQBE port 2748.

The user flag to enable security will depend on the cluster security mode. If cluster security mode is set to secure then user's security settings will have a meaning otherwise the connection has to be nonsecure. If secure connection to CTIManager is checked, following settings will be enabled for editing.

CAPF Server: CAPF server IP address to fetch the client certificate from.

CAPF Port: (Default 3804) - CAPF Server Port to connect to for Certificate download Authorization Code (AuthCode): This is required for Client authentication with CAPF Server and Private Key storage on client machine.

Instance ID(IID): Each secure connection to CTIManager needs to have its own certificate for authentication. Previously multiple instances of application were able to use same user/pwd to get authenticated with CTIManager. With the restriction of having a distinct certificate per connection, CAPF Server needs to verify that the user with appropriate AuthCode and IID is requesting the certificate. CAPF server will use AuthCode and IID to verify the user identity. Once CAPF server provides a certificate it clears the AuthCode in order to make sure only one instance of an app requests a certificate based on a single AuthCode. CCM admin will allow user configuration to provide multiple IID and AuthCode.

TFTP Server: TFTP server IP address to fetch the CTL file. CTL file is required to verify the server certificate, sent while mutually authenticating the TLS connection.

Check box to Fetch Certificate: This setting is not stored anywhere instead is only used to update the Client certificate when checked and will be cleared automatically.

Number of Retries for Certificate Fetch: This indicates the number of retries TSP will perform to connect to CAPF Server for certificate download in case an error. (Default - 0) (Range - 0 to 3)

Retry Interval for Certificate Fetch: This will be used when the retry is configured. It would indicate the (secs) for which TSP will wait during retries. (Default - 0) (Range - 0 to 15)

Since user is not expected to update the client certificate everytime it changes, TSP UI will popup a warning message when this box is checked by user, saying "This will trigger a certificate update. Please make sure that you really want to update the TSP certificate now". This will make sure if user selects this checkbox in an error. TSP will fail to establish a secure connection to CTIManager if a valid certificate can not be obtained. Each secure connection to CTIManager needs to have a unique certificate for authentication.

If an application tries to create more than one Provider simultaneously with the same certificate or when a session with the same certificate already exists/is open, both providers will be disconnected by CTIManager. TSP will try reconnecting to CTIManager to bring the provider in service. However, if both providers continuously try to connect using the same duplicated certificate, then both providers will be closed after certain number of retries and the certificate will be marked as compromised by CTIManager on CallManager server. The number of retries after which the certificate should be marked as compromised is configurable from the CTIManager Service Parameter "CTI InstanceId Retry Count". Any further attempt to open provider with the certificate which is compromised will be rejected by CTIManager. In this case, the compromised certificate's CAPF profile should be deleted and a new CAPF Profile needs to be created for the user. The user's new CAPF profile should use new instance id. Otherwise, the old certificate which was compromised previously can be used again.

A new error code, TSPERR_INIT_CERTIFICATE_COMPROMISED, has been added with value as 0x00000011 where TSPERR_UNKNOWN is 0x00000010. Hence, application should not have checks like "if (err < TSPERR_UNKNOWN))" as there are error codes that have a value greater than that.

When TLS is used, the initial handshake will be slow as expected due to heavy use of public key cryptography. Once the initial handshake is complete and the session is established, the overhead is significantly reduced. Here in below is the profiling result on ProviderOpen for both secure and non-secure CTI connection.

Controlled Devices
Type of CTI Connection
Duration on ProviderOpen
Duration on OpenAllLines
Comments

0

Non-Secure

1 sec 382 ms

N/A

 
 

Secure

4 sec 987 ms

N/A

With certificate retrieval.

 

Secure

3 sec 736 ms

N/A

 

100

Non-secure

1 sec 672 ms

3 sec 164ms

 
 

Secure

5 sec 758 ms

3 sec 445ms

 

2500

Non-Secure

29 sec 513 ms

3 min 26 sec 728 ms

 
 

Secure

34 sec 219 ms

3 min 26 sec 928 ms

 

Monitoring Call Park Directory Numbers

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

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

Super Provider Support

The Super Provider functionality allows a TSP application to control any CTI controllable device in the system (IP Phones, CTI Ports, CTI Route Points etc). The TSP application has to have an associated list of devices that it can control. It cannot control any devices that are outside of this list. However, certain applications would want to control a large number (possibly all) of the CTI controllable devices in the system. Super Provider enables the administrator to configure a CTI application as a "Super-Provider." This will mean that that particular application can control absolutely any CTI controllable device in the system.

Previously, the Super Provider functionality was never exposed to TSP apps, that is the TSP application needed to have the device in the controllable list. In this release, TSP apps can control any CTI controllable device in the CallManager system. The Super-Provider apps need to explicitly "Acquire" the device before opening them.

TSP exposes new interfaces to the apps to explicitly Acquire/Deacquire any device in the system. The device info will be fetched for the explicitly acquired device using the SingleGetInfoFetch API exposed via QBE by CTI. Later, TSP will fetch the line info for this device using the LineInfoFetch API. The lines of this device will be reported to the app using the LINE_CREATE/PHONE_CREATE events.

The apps can explicitly 'De-Acquire' the device. After the device is successfully de-acquired, TSP will fire LINE_REMOVE/PHONE_REMOVE events to the apps.

TSP also supports Change Notification of "Super-Provider" flag. If the administrator has configured a User as a "Super-Provider"in the admin pages, then the status of this is changed and the user is no more a Super-Provider, then CTI will inform the same to TSP in ProviderUserChangedEvent.

If any device had been explicity acquired and opened in super-provider mode, then TSP will fire PHONE_REMOVE/LINE_REMOVE to the app indicating that the device/line is no more available for the app to use.

In this release, TSP supports change notification of CallParkDN Monitoring as well. Say, the user has been configured to allow monitoring of CallParkDN in the admin pages, now the status of this flag is disabled. Then TSP will fire LINE_REMOVE for the CallParkDNs.

Say, initially the CallParkDN Monitoring is disabled, now the status is changed to enabled, then TSP will fetch all the CallParkDNs from CTI and fire LINE_CREATE for each of the CallParkDNs.

Cisco Unified Communications Manager Release 5.0

This section describes new and changed features supported in Cisco Unified Communications Manager, Release 5.0 and contains the following:

Unicode Support

Line-Side SIP Phones

Unicode Support

Cisco TSP supports Unicode character sets. TSP will send Unicode party names to the application in all call events. The party name needs to be configured in the Cisco Unified Communications Manager Administration. This support is limited to only party names. The locale information is also sent to the application. The UCS-2 encoding for Unicode is used.

The party names will be in the DevSpecific portion of the LINECALLINFO structure. In SIP call scenarios, where a call comes back into Call Manager from SIP proxy over a SIP trunk, only ASCII name will be passed since SIP protocol has no way of populating both ASCII and Unicode. As the result, the Connected and Redirection Unicode Name will be reported as empty to application.

Line-Side SIP Phones

TSP supports controlling and monitoring of TNP based SIP phones. Existing phones (7960 and 7940) running SIP cannot be controlled or monitored by the TSP and should not be included in the control list. Though the general behavior of a SIP phone is similar to SCCP phone not all TSP features are supported for SIP phones.

Also note that CCiscoPhoneDevSpecificDataPassThrough functionality is not supported on SIP phones configured with UDP transport due to UDP limitations. SIP phones must be configured to use TCP (default) if the CCiscoPhoneDevSpecificDataPassThrough functionality is needed.

TSP application registration state for SIP TNP phones with UDP as transport may not be consistent to the registration state of the phone. SIP TNP phone with UDP as transport may appear to be registered when application reports the devices as out of service. This may happen when CTIManager determines that CCM is down and puts the device as out of service, but because of the inherent delay in UDP to determine the lost connectivity, phone may appear to be inservice.

The way applications open devices and lines on SIP phones remain the same as that of SCCP phone. It is the SIP phone that controls when and how long to play reorder tone. When a SIP phone gets a request to play reorder tone, the SIP phone will release the resources from CallManager and plays reorder tone. Therefore, the call appears to be IDLE to a TSP application even though reorder tone is being played on the phone. Applications will still be able to receive and initiate calls from the phone even when there is reorder tone being played by the phone is these scenarios. Because resources have been released on CallManager, this call does not count against the busy trigger and maximum number of call counters.

When consult call scenario is invoked on the SIP, the order of new call event (for consult call) and on hold call state change event (for original call).

Cisco Unified Communications Manager Release 4.x

This section describes new and changed features supported in Cisco Unified Communications Manager, Release 4.x and contains the following:

Release 4.0

Redirect and Blind Transfer

Direct Transfer

Join

Set the Original Called Party upon Redirect

Cisco Unified TSP Auto Update

Multiple Calls per Line Appearance

Shared Line Appearance

Select Calls

Release 4.1

Forced Authorization Code and Client Matter Code

CTI Port Third-Party Monitoring Port

Translation Pattern

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

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 on hold 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 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.

Set the Original Called Party upon Redirect

Two extensions enable setting the original called party upon redirect as follows:

CCiscoLineDevSpecificRedirectResetOrigCalled

CCiscoLineDevSpecificRedirectSetOrigCalled

See lineDevSpecific, page 5-10 for more information.

Cisco Unified TSP Auto Update

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.

Multiple Calls per Line Appearance

The following describe the conditions of Line Appearance.

Maximum Number of Calls

The maximum number of calls per Line Appearance is database configurable. This means that the Cisco TSP supports more than 2 calls per line on Multiple Call Display (MCD) 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 Cisco TSP supports a maximum of 2 calls per line. The absolute maximum number of calls per line appearance is 200.

Busy Trigger

In Cisco CallManager, there is a 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 old call waiting flag per DN. The busy trigger setting cannot be modified using the CiscoTSP.

Call Forward No Answer Timer

The Call Forward No Answer timer is database configurable, per DN, per cluster. This timer is not configurable using the CiscoTSP.

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.

Forced Authorization Code and Client Matter Code

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.

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.