Cisco JTAPI Developer Guide For CCM 4.1

Cisco JTAPI Developer Guide for
Cisco CallManager 4.1(3)
Corporate Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 526-4100
Customer Order Number:

Text Part Number: OL-7242-02
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT
NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT
ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR
THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION
PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO
LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as
part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE
PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED
OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL
DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR
INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
CCSP, the Cisco Square Bridge logo, Follow Me Browsing, and StackWise are trademarks of Cisco Systems, Inc.; Changing the Way We Work,
Live, Play, and Learn, and iQuick Study are service marks of Cisco Systems, Inc.; and Access Registrar, Aironet, ASIST, BPX, Catalyst, CCDA,
CCDP, CCIE, CCIP, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems
Capital, the Cisco Systems logo, Cisco Unity, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Fast
Step, FormShare, GigaDrive, GigaStack, HomeLink, Internet Quotient, IOS, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard,
LightStream, Linksys, MeetingPlace, MGX, the Networkers logo, Networking Academy, Network Registrar, Packet, PIX, Post-Routing,
Pre-Routing, ProConnect, RateMUX, ScriptShare, SlideCast, SMARTnet, StrataView Plus, SwitchProbe, TeleRouter, The Fastest Way to Increase
Your Internet Quotient, TransPath, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain
other countries.
All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply
a partnership relationship between Cisco and any other company. (0501R)
Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Copyright © 2002-2005, Cisco Systems, Inc.
All rights reserved.
C O N T E N T S O
L- 7 2 4 2 - 0 2
Preface xxxi
Introduction xxxii
Purpose xxxii
Audience xxxii
New and Changed Information xxxiii
Cisco CallManager 4.1(3) xxxiii
Windows 2003 Support xxxiii
Auto Call Pickup xxxiii
Caveats xxxiv
Cisco CallManager Release 4.1(2) xxxv
Caveats for Cisco CallManager Release 4.1(2) xxxv
Cisco CallManager Release 4.0(1) xxxvii
Caveats xxxix
Cisco CallManager Release 3.3 xxxix
Cisco CallManager Release 3.2 xl
Cisco CallManager Release 3.1 xli
Organization xli
Related Documentation xlii
Required Software xlii
Conventions xliii
Obtaining Documentation xliv
Cisco.com xliv

OL-7242-02 iii
Contents
Documentation DVD xliv

Ordering Documentation xlv
Documentation Feedback xlv
Cisco Product Security Overview xlv
Reporting Security Problems in Cisco Products xlvi
Obtaining Technical Assistance xlvii
Cisco Technical Support Website xlvii
Submitting a Service Request xlviii
Definitions of Service Request Severity xlviii
Obtaining Additional Publications and Information xlix
Overview 1-1
Cisco JTAPI 1-3
CiscoObjectContainer 1-4
JtapiPeer and Provider 1-4
Initialization 1-5
Shutdown 1-5
Provider.getTerminals() 1-6
Provider.getAddresses() 1-6
Changes to the User Control List in the Directory 1-6
Addresses and Terminals 1-7
Address and Terminal Relationship 1-8
Unobserved Addresses and Terminals 1-8
Connection 1-9
TerminalConnection 1-9
CiscoConnectionID 1-9
CiscoCallID 1-9
Threaded CallBacks 1-9

iv OL-7242-02
Contents
CiscoSynchronousObserver Interface 1-10

Querying Dynamic Objects 1-10
callChangeEvent() 1-10
CiscoConsultCall 1-11
CiscoTransferStartEv 1-11
Alarm Services 1-11
Application Control of JTAPI Parameters 1-12
Jtapi.ini Parameters 1-12
Dynamic Trace Enabling Using Jtprefs 1-14
Supported Device Types 1-14
Call Forward Setting 1-15
Call Park 1-15
Park Retrieval 1-16
Park Reminder 1-16
Park DN Monitor 1-16
CiscoJtapiExceptions 1-17
Cisco JTAPI Install Internationalization 1-17
Clear Calls Interface 1-17
Device Recovery 1-17
Device Recovery for phones 1-18
CTI RoutePoints 1-18
CTI Ports 1-18
Directory Change Notification 1-19
Enable or Disable Ringer 1-19
Transfer and Conference Extensions 1-19
Transfer 1-19

OL-7242-02 v
Contents
CiscoTransferEndEv 1-20
Transfer Scenarios 1-20
Conference 1-23
Cisco Extensions 1-24
Conference Scenarios 1-25
Conference Events 1-26
Transfer and Conference Enhancement 1-27
Consult Without Media 1-27
Media Termination Extensions 1-28
Cisco CallManager Media Endpoint Model 1-29
Payload and Parameter Negotiation 1-29
Initialization 1-30
Payload Selection 1-30
Receive Channel Allocation 1-31
Starting Transmission and Reception 1-31
Stopping Transmission and Reception 1-32
CiscoMediaTerminal 1-32
Provisioning 1-32
Registration 1-33
Adding Observers 1-35
Accepting Calls 1-36
Receiving and Responding to Media Flow Events 1-36
Inbound Call Media Flow Event Diagram 1-37
Cisco IP Telephony Solutions RTP Implementation 1-38
Redirect 1-38
Routing 1-40

vi OL-7242-02
Contents
Cisco Route Session Implementation 1-41

Select Route Timer 1-42
Forwarding Timer 1-42
RouteSession Extension 1-42
Caller Options Summary 1-42
Fault Tolerance When Using Route Points 1-43
Redundancy 1-44
Cluster Abstraction 1-44
Cisco CallManager Server Failure 1-46
Redundancy in CTIManagers 1-48
Invoking CTIManager Redundancy 1-49
CTIManager Failure 1-50
Heartbeats 1-51
Display Name Interface 1-51
SetMessageWaiting Interface 1-52
Quite Clear 1-53
GetCallInfo Interface on Address 1-53
DeleteCall Interface 1-54
GetGlobalCallID 1-54
GetCallID in RTP Events 1-55
XSI Object Pass Through 1-55
CiscoTerminal Method 1-56
Authentication and Mechanism 1-56
VG248 and ATA 186 Analog Phone Gateways 1-57
Multiple Calls Per DN 1-57
Shared Line Support 1-57
Transfer and DirectTransfer 1-62
Conference and Join 1-63

OL-7242-02 vii
Contents
Barge and Privacy Event Notification 1-66

CallSelect and UnSelect Event Notification 1-67
Dynamic CTIPort Registration Per Call 1-68
Media Termination at Route Point 1-70
Redirect Set Original Called ID 1-74
Single Step Transfer 1-75
Auto Update of API 1-75
CiscoTerminal Filter and ButtonPressedEvents 1-78
Modifying Calling Number 1-79
AutoAccept Support for CTIPort and RoutePoint 1-82
CiscoTermRegistrationFailed Event 1-83
SelectRoute Interface Enhancement 1-85
Presentation Indicator (PI) for the Call 1-88
Progress State Converted to Disconnect State 1-90
Device State Server 1-90
Forced Authorization and Client Matter Codes 1-92
Forced Authorization Code (FAC) 1-92
Client Matter Code (CMC) 1-92
Supported Interfaces 1-92
Call.Connect() and Call.Consult() 1-93
Call.transfer(String) and Connection.redirect() 1-95
RouteSession.selectRoute() 1-95
Super Provider (Disable Device Validation) 1-95
Q.Signaling (QSIG) Path Replacement 1-96
Network Events 1-96

viii OL-7242-02
Contents
Cisco JTAPI Implementation 2-1

Cisco JTAPI Extensions Hierarchy 2-1
Class Hierarchy 2-1
class java.lang.Object 2-1
Interface Hierarchy 2-2
Class com.cisco.jtapi.extensions 2-8
CiscoAddrAddedToTerminalEv 2-8
Declaration 2-8
All Superinterfaces 2-8
Description 2-8
Fields 2-9
Methods 2-10
CiscoAddrAutoAcceptStatusChangedEv 2-10
Declaration 2-10
Description 2-10
Fields 2-11
Methods 2-12
CiscoAddrCreatedEv 2-12
Declaration 2-12
Description 2-13
Fields 2-13
Methods 2-13
CiscoAddress 2-14
Declaration 2-14
Description 2-14
Fields 2-16

OL-7242-02 ix
Contents
Methods 2-18
CiscoAddressCallInfo 2-23
Declaration 2-23
Constructors 2-23
Methods 2-24
CiscoAddressObserver 2-24
Declaration 2-24
Description 2-25
CiscoAddrEv 2-25
Declaration 2-25
All Known Subinterfaces 2-25
Description 2-26
CiscoAddrInServiceEv 2-26
Declaration 2-26
Description 2-27
Fields 2-28
Methods 2-28
CiscoAddrOutOfServiceEv 2-28
Declaration 2-28
Description 2-29
Fields 2-30
Methods 2-30
CiscoAddrRemovedEv 2-30
Declaration 2-30

x OL-7242-02
Contents

Description 2-31
Fields 2-32
Methods 2-32
CiscoAddrRemovedFromTerminalEv 2-32
Declaration 2-32
Description 2-32
Fields 2-33
Methods 2-34
CiscoCall 2-34
Declaration 2-34
Description 2-34
Methods 2-38
CiscoCallChangedEv 2-45
Declaration 2-45
Description 2-46
Methods 2-48
CiscoCallEv 2-48
Declaration 2-48
Description 2-49
Fields 2-52
Methods 2-58
CiscoCallID 2-58

OL-7242-02 xi
Contents
Declaration 2-58
Description 2-58
Methods 2-59
CiscoConferenceEndEv 2-60
Declaration 2-60
Description 2-60
Fields 2-63
Methods 2-63
CiscoConferenceStartEv 2-65
Declaration 2-65
Description 2-65
Fields 2-67
Methods 2-67
CiscoConnection 2-69
Declaration 2-69
Description 2-69
Fields 2-72
Methods 2-74
CiscoConnectionID 2-81
Declaration 2-81
Description 2-82
Methods 2-82
CiscoConsultCall 2-83
Declaration 2-83

xii OL-7242-02
Contents

Description 2-83
Methods 2-85
CiscoConsultCallActiveEv 2-87
Declaration 2-87
Description 2-87
Fields 2-89
Methods 2-89
CiscoEv 2-90
Declaration 2-90
Description 2-90
CiscoG711MediaCapability 2-91
Declaration 2-91
Description 2-91
Fields 2-92
Constructors 2-93
Declaration 2-93
Description 2-94
Fields 2-95
Constructors 2-95
Methods 2-96
Declaration 2-96
Description 2-96
Fields 2-97

OL-7242-02 xiii
Contents
Constructors 2-98
CiscoGSMMediaCapability 2-99
Declaration 2-99
Description 2-99
Fields 2-100
Constructors 2-100
CiscoJtapiException 2-101
Declaration 2-101
Description 2-101
Fields 2-105
Methods 2-118
CiscoJtapiPeer 2-119
Declaration 2-119
Description 2-120
Methods 2-121
CiscoJtapiProperties 2-121
Declaration 2-121
Description 2-121
Methods 2-126
CiscoJtapi Version 2-133
Declaration 2-133
Description 2-133
Constructors 2-134
Methods 2-134
CiscoMediaCapability 2-136
Declaration 2-136

xiv OL-7242-02
Contents
Direct Known Subclasses 2-136

Description 2-136
Fields 2-137
Constructors 2-139
Methods 2-139
CiscoMediaOpenLogicalChannelEv 2-140
Declaration 2-140
Description 2-140
Fields 2-141
Methods 2-141
Declaration 2-143
Description 2-143
Methods 2-145
CiscoObjectContainer 2-150
Declaration 2-150
Description 2-150
Methods 2-150
CiscoOutOfServiceEv 2-151
Declaration 2-151
Description 2-151
Fields 2-152
CiscoProvCallParkEv 2-153
Declaration 2-153

OL-7242-02 xv
Contents

Description 2-153
Fields 2-155
Methods 2-156
CiscoProvEv 2-157
Declaration 2-157
Description 2-157
CiscoProvFeatureEv 2-158
Declaration 2-158
Methods 2-159
CiscoProvFeatureID 2-160
Declaration 2-160
Description 2-160
Fields 2-160
CiscoProvFeatureUnRegisteredEv 2-160
Declaration 2-160
Description 2-161
Fields 2-162
Methods 2-163
CiscoProvider 2-163
Declaration 2-163
Description 2-163
Methods 2-165

xvi OL-7242-02
Contents
CiscoProviderCapabilities 2-170
Declaration 2-170
Description 2-170
Methods 2-171
CiscoProviderObserver 2-171
Declaration 2-171
Description 2-171
CiscoRegistrationException 2-172
Declaration 2-172
All Implemented Interfaces 2-172
Description 2-172
Constructors 2-173
CiscoRouteAddress 2-173
Declaration 2-173
Methods 2-174
CiscoRouteSession 2-175
Declaration 2-175
Description 2-175
Fields 2-177
Methods 2-178
CiscoRouteTerminal 2-181
Declaration 2-181
Description 2-182
Fields 2-184

OL-7242-02 xvii
Contents
Methods 2-185
CiscoRouteUsedEvent 2-187
Declaration 2-187
Description 2-188
Methods 2-188
CiscoRTPBitRate 2-189
Declaration 2-189
Description 2-189
Fields 2-190
CiscoRTPHandle 2-190
Declaration 2-190
Description 2-190
Methods 2-191
CiscoRTPInputProperties 2-191
Declaration 2-191
Description 2-191
Methods 2-192
CiscoRTPInputStartedEv 2-194
Declaration 2-194
Description 2-194
Fields 2-195
Methods 2-195
CiscoRTPInputStoppedEv 2-195
Declaration 2-195
Description 2-196
Fields 2-196

xviii OL-7242-02
Contents
Methods 2-197
CiscoRTPOutputProperties 2-197
Declaration 2-197
Description 2-197
Methods 2-198
CiscoRTPOutputStartedEv 2-200
Declaration 2-200
Description 2-200
Fields 2-201
Methods 2-201
CiscoRTPOutputStoppedEv 2-202
Declaration 2-202
Description 2-202
Fields 2-203
Methods 2-203
CiscoRTPParams 2-204
Declaration 2-204
Constructors 2-204
Methods 2-205
CiscoRTPPayload 2-205
Declaration 2-205
Description 2-205
Fields 2-207
CiscoSynchronousObserver 2-209
Declaration 2-209
Description 2-210

OL-7242-02 xix
Contents
CiscoTermButtonPressedEv 2-211
Declaration 2-211
Description 2-211
Fields 2-212
Methods 2-214
CiscoTermConnPrivacyChangedEv 2-214
Declaration 2-214
Description 2-214
Fields 2-215
Methods 2-215
CiscoTermCreatedEv 2-215
Declaration 2-215
Description 2-215
Fields 2-216
Methods 2-216
CiscoTermDataEv 2-217
Declaration 2-217
Description 2-217
Fields 2-218
Methods 2-218
CiscoTermDeviceStateActiveEv 2-218
Declaration 2-218
All Super-Interfaces 2-219
Description 2-219
Methods 2-220

xx OL-7242-02
Contents
CiscoTermDeviceStateAlertingEv 2-220
Declaration 2-220
Description 2-221
Methods 2-222
CiscoTermDeviceStateHeldEv 2-222
Declaration 2-222
Description 2-223
Methods 2-224
CiscoTermDeviceStateIdleEv 2-224
Declaration 2-224
Description 2-225
Methods 2-226
CiscoTermEv 2-227
Declaration 2-227
Description 2-227
CiscoTermEvFilter 2-228
Declaration 2-228
Description 2-228
Methods 2-229
CiscoTerminal 2-230
Declaration 2-230
Description 2-231

OL-7242-02 xxi
Contents
Fields 2-232
Methods 2-233
CiscoTerminalConnection 2-237
Declaration 2-237
Description 2-237
Methods 2-238
CiscoTerminalObserver 2-239
Declaration 2-239
All Superinterfaces: 2-239
Description 2-239
CiscoTermInServiceEv 2-240
Declaration 2-240
Description 2-240
Fields 2-241
CiscoTermOutOfServiceEv 2-241
Declaration 2-241
Description 2-242
Fields 2-242
CiscoTermRegistrationFailedEv 2-243
Declaration 2-243
Description 2-243
Fields 2-245
Methods 2-246
CiscoTermRemovedEv 2-246

xxii OL-7242-02
Contents
Declaration 2-246
Description 2-247
Fields 2-248
Methods 2-248
CiscoToneChangedEv 2-248
Declaration 2-248
Description 2-248
Fields 2-250
Methods 2-251
CiscoTransferEndEv 2-251
Declaration 2-251
Description 2-251
Fields 2-254
Methods 2-254
Declaration 2-255
Description 2-255
Fields 2-257
Methods 2-257
CiscoUnregistrationException 2-258
Declaration 2-258
Description 2-259
Constructors 2-259

OL-7242-02 xxiii
Contents
CiscoWideBandMediaCapability 2-260
Description 2-260
Fields 2-261
Constructors 2-261
Class com.cisco.services.alarm 2-262
Alarm 2-262
Declaration 2-262
All Known Implementing Classes 2-262
Description 2-263
Fields 2-265
Methods 2-267
AlarmManager 2-268
Declaration 2-268
Description 2-268
Constructors 2-270
Methods 2-270
AlarmWriter 2-271
Declaration 2-271
Description 2-271
Methods 2-272
DefaultAlarm 2-273
Declaration 2-273
Description 2-273
Constructors 2-274
Methods 2-274
DefaultAlarmWriter 2-276
Declaration 2-276

xxiv OL-7242-02
Contents

Description 2-276
Constructors 2-277
Methods 2-279
ParameterList 2-280
Declaration 2-280
Description 2-280
Constructors 2-281
Methods 2-282
Class com.cisco.services.tracing 2-283
BaseTraceWriter 2-284
Declaration 2-284
Direct Known Subclasses 2-284
Description 2-284
Constructors 2-286
Methods 2-287
ConditionalTrace 2-289
Declaration 2-289
Description 2-289
Methods 2-290
ConsoleTraceWriter 2-291
Declaration 2-291
Description 2-291
Constructors 2-292
Methods 2-293
LogFileTraceWriter 2-294

OL-7242-02 xxv
Contents
Declaration 2-294
Description 2-294
Fields 2-297
Constructors 2-298
Methods 2-299
OutputStreamTraceWriter 2-302
Declaration 2-302
Description 2-302
Constructors 2-303
Methods 2-303
SyslogTraceWriter 2-304
Declaration 2-304
Description 2-305
Constructors 2-306
Methods 2-307
Trace 2-307
Declaration 2-307
Description 2-308
Fields 2-310
Methods 2-313
TraceManager 2-315
Declaration 2-315
Description 2-316
Methods 2-318
TraceManagerFactory 2-321

xxvi OL-7242-02
Contents
Declaration 2-321
Description 2-321
Methods 2-322
TraceModule 2-323
Declaration 2-323
Description 2-323
Methods 2-323
TraceWriter 2-324
Declaration 2-324
Description 2-324
Methods 2-325
TraceWriterManager 2-327
Declaration 2-327
Description 2-327
Methods 2-328
UnconditionalTrace 2-329
Declaration 2-329
Description 2-329
JTAPI Examples 3-1

MakeCall.java 3-2
Actor.java 3-5
Originator.java 3-10
Receiver.java 3-14

OL-7242-02 xxvii
Contents
StopSignal.java 3-16
Trace.java 3-17
TraceWindow.java 3-18
Running makecall 3-21
APPENDIX A Message Sequence Charts A-1

Shared Line Support A-2
AddressInService/AddressOutofService Events A-3
Incoming Call to Shared Address A-4
Outgoing Call from Shared Address A-5
Shared Address Calling Itself A-6
Transfer and Direct Transfer A-7
DirectTransfer/Arbitrary Transfer Scenario—Page 1 A-7
Direct Transfer/Arbitrary Transfer—Page 2 A-8
Consult Transfer Scenario A-9
Conference and Join A-9
Join/Arbitrary Conference Scenario—Page 1 A-10
Join/Arbitrary Conference Scenario—Page 2 A-11
Consult Conference Scenario A-12
Barge and Privacy A-12
Barge Feature A-13
CBarge Feature A-14
Privacy A-15
CallSelect and UnSelect A-15
CallSelect and UnSelect Scenario A-16
Dynamic CTIPort Registration Per Call A-16
Dynamic Registration for CTIPort A-17
Media Termination at Route Point A-17
Media Termination at Route Point Scenario A-18

xxviii OL-7242-02
Contents
Redirect Set OriginalCalledID A-19

Scenario One A-19
Scenario Two A-20
Single Step Transfer A-22
Modifying Calling Number A-25
Scenario One A-25
Scenario Two A-26
AutoAccept for CTIPort and RoutePoint A-29
Forced Authorization and Customer Matter Codes Scenarios A-29
Scenario One A-29
Scenario Two A-31
Scenario Three A-32
Scenario Four A-34
Scenario Five A-37
Super Provider Message Flow A-38
QSIG Path Replacement Use Cases A-39
Device State Server Message Flow A-42
APPENDIX B Cisco JTAPI Classes and Interfaces B-1

Cisco JTAPI Version 1.2 Classes and Interfaces B-2
Core Package B-2
Call Center Package B-6
Call Center Capabilities Package B-8
Call Center Events Package B-9
Call Control Package B-11
Call Control Capabilities Package B-15
Call Control Events Package B-17
Capabilities Package B-18
Events Package B-19

OL-7242-02 xxix
Contents
Media Package B-20

Media Capabilities Package B-21
Media Events Package B-22
Unsupported Packages B-22
Cisco JTAPI Extension Classes and Interfaces B-23
Cisco JTAPI Extension Classes B-23
Cisco JTAPI Extension Interfaces B-23
Cisco Trace Logging Classes and Interfaces B-27
Cisco Trace Logging Classes B-27
Cisco Trace Logging Interfaces B-29
APPENDIX C Troubleshooting CiscoJTAPI c-1

CTI Error Codes c-1
CiscoEvent IDs c-8
Additional Troubleshooting Information c-9
Viewing JTAPI Debug Output c-9
INDEX

xxx OL-7242-02
Preface
This chapter introduces Cisco JTAPI implementation, describes the purpose of

this document, and outlines the required software. The chapter includes the
following topics:
• Introduction
• Purpose
• Audience
• New and Changed Information
• Organization
• Related Documentation
• Required Software
• Conventions
• Obtaining Documentation
• Documentation Feedback
• Obtaining Technical Assistance
• Obtaining Additional Publications and Information

OL-7242-02 xxxi
Preface
Introduction
Introduction
Java Telephony Application Programming Interface (JTAPI) acts as a portable,
object-oriented API for computer telephony integrated call control. The package
of JTAPI interfaces, located in the javax.telephony.* hierarchy, defines a
programming model by which Java applications interact with telephony resources
such as PBXs and telephones. The Cisco JTAPI implementation supports Java
application access to Cisco Architecture for Voice, Video and Integrated Data
(AVVID) communication systems according to the JTAPI v 1.2 specification.
Furthermore, Cisco JTAPI exposes Cisco-specific events and methods for certain
telephony resources such as calls and connections.
Purpose
Providing an unchanging programming interface under which varied
implementations may stand represents one of the primary goals of a standard
Application Programming Interface (API) such as JTAPI. In implementing JTAPI
for the Cisco CallManager platform, Cisco tries to conform as closely as possible
to the JTAPI specification while providing extensions that enhance JTAPI and
expose the advanced features of Cisco CallManager to applications.
As new versions of Cisco CallManager and the Cisco JTAPI implementation are
released, variances in the API should be very minor and should tend in the
direction of compliance. Cisco remains committed to maintaining its API
extensions with the same stability and reliability, though additional extensions
may be provided as new Cisco CallManager features become available.
This document outlines some basic JTAPI concepts including transfer and
conference extensions. It also describes the support of extensions to the Sun
JTAPI v 1.2 specification.
Audience
This document applies for telephony software developers who are developing
Cisco IP Telephony applications that require JTAPI. This document assumes that
the programmer is familiar with both the Java language and the Sun JTAPI v 1.2
specification.

xxxii OL-7242-02
Preface
New and Changed Information

This section describes any new features and or changes for Cisco JTAPI that are
pertinent to the specified release of Cisco CallManager. This section also lists
caveats that apply to a particular release, where applicable.
Cisco CallManager 4.1(3)

This section describes the changes to Cisco JTAPI for Cisco CallManager 4.1(3).
Windows 2003 Support

Cisco JTAPI provides support for Windows 2003, and the Install Shield for the
Cisco_JTAPI plug-in also includes support for Windows 2003. Before
Cisco_JTAPI 4.1(3) gets installed on a Windows 2003 client machine, you must
first install Sun Java Virtual Machine (JVM).
Before Cisco JTAPI 4.0 gets installed on a Windows 2003 client machine, you
must first install Microsoft JVM.
Cisco JTAPI contains no interface changes for Windows 2003 support.
Auto Call Pickup

For Release 4.1(3), Cisco CallManager provides support for the Auto Call Pickup
feature. Cisco JTAPI does not support either the new Auto Call Pickup features or
the existing Call Pickup features and contains no interface changes for Release
4.1(3). Cisco CallManager does send different call information for Auto Call
Pickup feature than for Call Pickup, which causes different call information to be
sent to the application.
The following scenarios illustrate the differences in call information between the
existing Call Pickup feature and the new Auto Call Pickup feature. In each
scenario, A calls B, and C picks up the call.

OL-7242-02 xxxiii
Preface
Call Information for Existing Call Pickup Feature
When C picks up the call, the application at A receives the following call
information:
• call.getCalledAddress()=B
• call.getCurrentCallingAddress=A
• call.getCurrentCalledAddress=C
• call.getLastRedirectedAddress()=B
Call Information for New Auto Call Pickup Feature
When C picks up the call, the application at A receives the following call
information:
• call.getCalledAddress()=C
• call.getCurrentCallingAddress=A
• call.getCurrentCalledAddress=C
• call.getLastRedirectedAddress()=B
Caveats
The following caveat applies to Cisco JTAPI 4.1.
CP Requires Previous Calls on the Device to be in the Connected Call State
Call processing requires previous calls on the device to be in connected call state
before it answers another calls on the same device. If call processing answers calls
without checking for the call state of previous calls on the same device, then CTI
might return a successful answer response but the call will not go to connected
state and needs to be answered again.

xxxiv OL-7242-02
Preface
Cisco CallManager Release 4.1(2)

The following list provides the features or changes for Cisco JTAPI in
Cisco CallManager release 4.1(2):
• Device State Server—Provides the cumulative state of all the addresses on a
CTI-supported device. States include IDLE, ACTIVE, ALERTING, and
HELD.
• QSIG Path Replacement—Provides new interfaces in JTAPI to support
Q.Signaling, which optimizes the real-time path (RTP) when calls are
transferred or forwarded to other PBXs that are connected through QSIG
trunks.
• Forced Authorization Code (FAC)—Forces the user to enter a valid
authorization code prior to extending a call. JTAPI provides an event to
indicate that an FAC is required.
• Client Matter Code (CMC)—Enables the user to enter a code that can used to
enter “client matter” information, such as accounting or billing codes. JTAPI
provides an event to indicate that a CMC is required.
• Super Provider—Enables applications to control and monitor any terminal in
a Cisco CallManager cluster.
Caveats for Cisco CallManager Release 4.1(2)

The following paragraphs describe the caveats that apply to Cisco CallManager
4.1(2):
FAC-CMC
Forwarding should not be configured to a DN that requires an FAC or CMC code.
Forwarding requests will be successful, but calls will not be forwarded to these
DNs and will be rejected.
The application should always terminate the code with “#”; otherwise, the system
waits for the T302 timer before extending the call. For these cases, the application
could get the postConditionTimeOut exception for call.connect() or call.consult(),
but the call may actually be offered. If applications need to avoid this, either all
the digits with a # terminated string are entered with post-condition timeout
(which is by default equals 15 seconds in the JTAPI Prefs UI) in the
PlatformException or increase the postcondition timeout.

OL-7242-02 xxxv
Preface
When two identical CiscoToneChangedEvents are sent to applications, and the

second one needs to be ignored if both the codes are entered with # separated upon
receiving the first event.
setConferenceController
According to the design, the party who starts the conference and adds a new party
acts as original conference controller. Changing the conference controller while
conference is going on does not take effect (no error gets thrown in
“setConferenceController” API). Only original conference controller can add a
new party into the conference. Even if the original conference controller has
dropped out of the conference, no other party in that particular conference can add
a new party.
Consider the following scenario as an example:
Scenario: A, B, C, and D belong to a conference call and all are in TALKING
state. A acts as the conference controller. A uses the SetConferenceController API
to change the conference controller to B and then drops out of the conference.
Now, B tries to add a new party E into the conference but is cannot do so. This is
happens per the design.
Interval During DTMF Digits

Change PlayDTMF to allow applications to specify the time delay; now,
applications can configure the time delay during DTMF digits through
Administration window Service parameter ('generate DTMF delay') for
Cisco CallManager.
Shared Lines Support

Cisco JTAPI does not support configuration of same DN from different partitions
on the same or any device, but does support configuration of different DNs from
different partitions on the same device as well as different devices.
CP requires previous calls on the device to be in connected call state

CP requires previous calls on the device to be in connected call state before
answering further calls on the same device. If calls are answered without checking
for the call state of previous calls on the same device, then CTI might return a
successful answer response, but the call will not go to connected state and needs
to be answered again.

xxxvi OL-7242-02
Preface
Cisco CallManager Release 4.0(1)

Cisco CallManager release 4.0(1):
• Multiple Calls Per DN—Enables applications to have multiple calls on the
same line with feature operations.
• Shared Line Support—Provides the following abilities to applications:
– Control shared DN terminals
– Hold a call on one Shared DN terminal and unhold the same call from
another Shared DN terminal
– Make calls between two Shared lines
– Initiate a call from one Shared line terminal while another active call
exists on another Shared line terminal with the same DN
• Transfer and DirectTransfer—Provides the following enhancements:
– Application can transfer two held calls.
– Application can have one held call and one connected call in any order.
– Application can transfer any two calls that are present on the line.
• Conference and Join—Enhances ability to perform Arbitrary Conference of
multiple calls
• Barge, CBarge, and Privacy Event Notification—For Barge and CBarge,
supports manual feature activation on the application-controlled IP phones.
The system does not support feature activation through the API. The Privacy
feature provides a shared address with the ability to enable or disable other
shared addresses to Barge into a call.
• CallSelect and UnSelect Even Notification—Provides events for applications
when they monitor RemoteInUse terminals. Applications cannot invoke an
API on the Passive or InUse TerminalConnection.
• Dynamic CTIPort Registration Per Call—Enables applications to provide an
ipAddress and port number for each call or whenever media gets established.
• Media Termination at Route Point—Enables applications to terminate media
for all active calls by specifying an ipAddress and port number for each call
or whenever media gets established.

OL-7242-02 xxxvii
Preface
• Redirect Set Original Called ID—Provides applications with the ability to

specify preferred original called party DN apart from the destination party
information in the redirect request.
• Single Step Transfer—Provides applications with the following
enhancements:
– A new call does not get created
– CiscoTransferStartEv and CiscoTransferEndEv do not get delivered to
applications
– The state of the original call gets retained if the transfer operation fails
• Auto Update of API—Provides a facility by which an application at startup
can identify itself to a web server via an HTTP request and receives a
response with the version of the required JTAPI API. The application
compares the version that is available on the server to the local version in the
application classpath and determines whether an upgrade is necessary.
• CiscoTerminal Filter and ButtonPressedEvents—Enables applications to
receive the CiscoTermButtonPressedEv when a digit gets pressed on the
phone.
• Modifying Calling Number—Enables applications to modify the calling
party in the select route API from a route point.
• AutoAccept support for CTIPort and RoutePoint—Provides applications with
the ability to enable or disable AutoAccept for the addresses on the CTIPort
and RoutePoint. When changes occur to AutoAccept on the address, the
application receives CiscoAddrAutoAcceptStatusChangedEv on
AddressObservers.
• CiscoTermRegistrationFailed event—Provides the applications with an event
when CiscoMediaTerminal or CiscoRouteTerminal registration
asynchronously fails.
• SelectRoute Interface Enhancement—Enhances the SelectRoute interface to
take the parameters “PreferedOriginalCalledNumber” and
“PreferedOriginalCalledOption,” which enables applications to reset the
OriginalCalled value to a specified “PreferedOriginalCalledNumber” when
the call gets routed.
• Presentation Indicator (PI) for the Call—Provides applications with the
ability to hide or reveal
Calling/Called/CurrentCalling/CurrentCalled/LastRedirecting parties name
and number to the end user.

xxxviii OL-7242-02
Preface
Caveats
The following caveat applies to Cisco CallManager 4.0.
Transferring to a Conference
In Cisco JTAPI, whenever Transfer connects a normal call to a conference call,

the GlobalCallId of the conference call always survives regardless of whether Call
1 or Call 2 performs the transfer.
When transferring to a conference, the system might deliver external connection
creation events before CiscoTransferStartedEv, however, the system will still
deliver Call Merge events within the CiscoTransferStart and CiscoTransferEnd
boundary.
Cisco CallManager Release 3.3

Cisco CallManager release 3.3:
• CallParkRequest, CallParkResponse, and Parked DN Monitoring—Defines
new extensions to allow applications to park a call or unpark a call.
• XSI Object Pass Through—Allows application to pass an XML object
through a Cisco JTAPI or CTI interface to an IP phone.
• VG248 and ATA 186 Analog Phone Gateways—Supports control of analog
phones that are connected to these gateways.
• Cisco JTAPI Installation Internationalization—Supports multiple languages
for the Cisco JTAPI installation and the user preference user interface. Refer
to the Cisco CallManager 3.3 JTAPI Installation Guide for more information.
• Enable or Disable Ringer—Supports application control of ringer settings for
each address on a device.
• Clear Calls Interface—Provides a clearCallConnections interface that allows
applications to remove phantom calls without removing the call observer.
• Display Name Interface—Extends the CiscoCall interface to provide methods
to get name displays of the calling party and the called party in a call.
Applications can use getCurrentCallingPartyDisplayName() to get the
display name of the calling party.

OL-7242-02 xxxix
Preface
• SetMessageWaiting Interface—Provides a method for applications to set the

message-waiting lamp or indicator for an address.
• Quite Clear—Provides QuiteClear at the other end when two parties are on a
call and one address goes OutOfService because of a network outage, the
Cisco CallManager goes down, application controlling CTIPort goes down,
or CTIManager goes down.
• GetCallInfo Interface—Provides applications with the ability to query
CallInfo on an address. A query returns the CiscoAddressCallInfo object,
which contains information about the number of active or held calls,
maximum number of active or held calls, and the Call object for current calls
on the address. This interface also provides information regarding what calls
are at a specific address at a specific time.
• DeleteCall Interface—Provides applications with the ability to delete a call
that was created by using the createCall interface. This method accepts a call
and throws an InvalidStateException if a provider is not in service or if the
call is not in the IDLE state. DeleteCall moves the call to the INVALID state.
• GetGCID—Provides an interface on the CiscoCallID to get the nodeID and
the GCID of the call, which exposes the GCID information that is available
in the internal call object.
• GetCallID in RTP Events—Provides an interface on RTP events to access any
call information, so applications can link RTP events with the calls.

• Call Park—Cisco JTAPI supports user interactions with Call Park and reports
appropriate events to the applications.
• Super Provider—Supports static control of devices and the ability to query
for devices.
• Reconnect Logic—Connects Cisco JTAPI applications to the secondary
CTIManager after waiting for a random time, so all Cisco JTAPI applications
do not connect to the secondary CTIManager at the same time.

xl OL-7242-02
Preface
Organization

• CTIManager Component—Allows a JTAPI application to control devices on
another Cisco CallManager in a cluster. It supports multiple
Cisco CallManagers and CTI managers during failover and recovery and
supports automatic device recovery during a failover.
• Directory Change Notification—Allows asynchronous directory change
notification.
• Transfer and Conference Enhancement—Allows enhancements to
Transferring & Conferencing.
• Call Forward Setting—Allows Cisco JTAPI implementation for supporting
Call Forwarding.
• CiscoJtapiExceptions—Allows CiscoJtapiException handling modifications.
• Redirect—Allows a Cisco JTAPI Redirect request.
• Alarm Services—Allows Cisco JTAPI support for Alarm Services.
• Application Control of JTAPI Parameters—Allows control of the parameters
within jtapi.ini.
• Dynamic Trace Enabling Using Jtprefs—Allows dynamic enabling of traces
from the Jtprefs application.
Organization
The following table provides an outline of this document’s organization.
Chapter Description
Chapter 1, “Overview” This chapter introduces the major concepts with
which you need to be familiar before creating JTAPI
applications for Cisco IP Telephony Solutions.
Chapter 2, “Cisco JTAPI This chapter describes the interfaces and classes that
Implementation” are available.

OL-7242-02 xli
Preface
Related Documentation
Chapter Description
Chapter 3, “JTAPI This chapter provides the source code for makecall,
Examples” which is the Cisco JTAPI program that is used to test
the JTAPI installation.
Appendix A, “Message This appendix contains message flow diagrams.
Sequence Charts”
Appendix B, This appendix contains a listing of all the classes and
“Cisco JTAPI Classes interfaces that are available in the Cisco JTAPI im-
and Interfaces” plementation for Cisco CallManager.
Appendix C, “Trouble- This appendix contains CTI Error Codes, CiscoEv-
shooting CiscoJTAPI” ent IDs, and other information to assist with trouble-
shooting efforts.
Related Documentation
To obtain the latest version of the complete Sun Microsystems JTAPI
specification files, go directly to the following web site:
• http://java.sun.com/products/jtapi
Required Software
The following table lists software requirements for the following applications:
JTAPI applications, JTPREFS, and sample code.
.
Application Required Software Examples

JTAPI appli- Any JDK 1.1 compliant • Microsoft Internet Explorer 4.01
cations java environment or later
• Sun JDK 1.1, 1.2, or 1.3
JTPREFS Any JDK 1.2 compliant
environment.
Sample code Microsoft Internet
Explorer 4.01 or later

xlii OL-7242-02
Preface
Conventions
Conventions
This document uses the following conventions:
Convention Description
boldface font Commands and keywords are in boldface.
italic font Arguments for which you supply values are in italics.
[ ] Elements in square brackets are optional.
{x|y|z} Alternative keywords are grouped in braces and separated by
vertical bars.
[x|y|z] Optional alternative keywords are grouped in brackets and
separated by vertical bars.
string A nonquoted set of characters. Do not use quotation marks
around the string or the string will include the quotation marks.
screen font Terminal sessions and information the system displays are in
screenfont.
boldface Information you must enter is in boldface screen font.
screen font
italic screen Arguments for which you supply values are in italic screen
font font.
This pointer highlights an important line of text in an example.
^ The symbol ^ represents the key labeled Control—for example,
the key combination ^D in a screen display means hold down
the Control key while you press the D key.
< > Nonprinting characters, such as passwords are in angle
brackets.
Notes use the following conventions:
Note Means reader take note. Notes contain helpful suggestions or references to
material not covered in the publication.

OL-7242-02 xliii
Preface
Obtaining Documentation
Obtaining Documentation
Cisco documentation and additional literature are available on Cisco.com. Cisco
also provides several ways to obtain technical assistance and other technical
resources. These sections explain how to obtain technical information from Cisco
Systems.
Cisco.com
You can access the most current Cisco documentation at this URL:
http://www.cisco.com/univercd/home/home.htm
You can access the Cisco website at this URL:
http://www.cisco.com
You can access international Cisco websites at this URL:
http://www.cisco.com/public/countries_languages.shtml
Documentation DVD
Cisco documentation and additional literature are available in a Documentation
DVD package, which may have shipped with your product. The Documentation
DVD is updated regularly and may be more current than printed documentation.
The Documentation DVD package is available as a single unit.
Registered Cisco.com users (Cisco direct customers) can order a Cisco
Documentation DVD (product number DOC-DOCDVD=) from the Ordering tool
or Cisco Marketplace.
Cisco Ordering tool:
http://www.cisco.com/en/US/partner/ordering/
Cisco Marketplace:
http://www.cisco.com/go/marketplace/

xliv OL-7242-02
Preface
Documentation Feedback
Ordering Documentation
You can find instructions for ordering documentation at this URL:
http://www.cisco.com/univercd/cc/td/doc/es_inpck/pdi.htm
You can order Cisco documentation in these ways:
• Registered Cisco.com users (Cisco direct customers) can order Cisco product
documentation from the Ordering tool:
http://www.cisco.com/en/US/partner/ordering/
• Nonregistered Cisco.com users can order documentation through a local
account representative by calling Cisco Systems Corporate Headquarters
(California, USA) at 408 526-7208 or, elsewhere in North America, by
calling 1 800 553-NETS (6387).
Documentation Feedback
You can send comments about technical documentation to bug-doc@cisco.com.
You can submit comments by using the response card (if present) behind the front
cover of your document or by writing to the following address:
Cisco Systems
Attn: Customer Document Ordering
170 West Tasman Drive
San Jose, CA 95134-9883
We appreciate your comments.
Cisco Product Security Overview

Cisco provides a free online Security Vulnerability Policy portal at this URL:
http://www.cisco.com/en/US/products/products_security_vulnerability_policy.ht
ml
From this site, you can perform these tasks:
• Report security vulnerabilities in Cisco products.

OL-7242-02 xlv
Preface
Cisco Product Security Overview
• Obtain assistance with security incidents that involve Cisco products.

• Register to receive security information from Cisco.
A current list of security advisories and notices for Cisco products is available at
this URL:
http://www.cisco.com/go/psirt
If you prefer to see advisories and notices as they are updated in real time, you
can access a Product Security Incident Response Team Really Simple Syndication
(PSIRT RSS) feed from this URL:
http://www.cisco.com/en/US/products/products_psirt_rss_feed.html
Reporting Security Problems in Cisco Products

Cisco is committed to delivering secure products. We test our products internally
before we release them, and we strive to correct all vulnerabilities quickly. If you
think that you might have identified a vulnerability in a Cisco product, contact
PSIRT:
• Emergencies — security-alert@cisco.com
• Nonemergencies — psirt@cisco.com
Tip We encourage you to use Pretty Good Privacy (PGP) or a compatible product to
encrypt any sensitive information that you send to Cisco. PSIRT can work from
encrypted information that is compatible with PGP versions 2.x through 8.x.
Never use a revoked or an expired encryption key. The correct public key to use
in your correspondence with PSIRT is the one that has the most recent creation
date in this public key server list:
http://pgp.mit.edu:11371/pks/lookup?search=psirt%40cisco.com&op=index&ex
act=on
In an emergency, you can also reach PSIRT by telephone:

• 1 877 228-7302
• 1 408 525-6532

xlvi OL-7242-02
Preface
Obtaining Technical Assistance

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

The Cisco Technical Support Website provides online documents and tools for
troubleshooting and resolving technical issues with Cisco products and
technologies. The website is available 24 hours a day, 365 days a year, at this
URL:
http://www.cisco.com/techsupport
Access to all tools on the Cisco Technical Support Website requires a Cisco.com
user ID and password. If you have a valid service contract but do not have a user
ID or password, you can register at this URL:
http://tools.cisco.com/RPF/register/register.do
Note Use the Cisco Product Identification (CPI) tool to locate your product serial
number before submitting a web or phone request for service. You can access the
CPI tool from the Cisco Technical Support Website by clicking the Tools &
Resources link under Documentation & Tools. Choose Cisco Product
Identification Tool from the Alphabetical Index drop-down list, or click the
Cisco Product Identification Tool link under Alerts & RMAs. The CPI tool
offers three search options: by product ID or model name; by tree view; or for
certain products, by copying and pasting show command output. Search results
show an illustration of your product with the serial number label location
highlighted. Locate the serial number label on your product and record the
information before placing a service call.

OL-7242-02 xlvii
Preface
Submitting a Service Request

Using the online TAC Service Request Tool is the fastest way to open S3 and S4
service requests. (S3 and S4 service requests are those in which your network is
minimally impaired or for which you require product information.) After you
describe your situation, the TAC Service Request Tool provides recommended
solutions. If your issue is not resolved using the recommended resources, your
service request is assigned to a Cisco TAC engineer. The TAC Service Request
Tool is located at this URL:
http://www.cisco.com/techsupport/servicerequest
For S1 or S2 service requests or if you do not have Internet access, contact the
Cisco TAC by telephone. (S1 or S2 service requests are those in which your
production network is down or severely degraded.) Cisco TAC engineers are
assigned immediately to S1 and S2 service requests to help keep your business
operations running smoothly.
To open a service request by telephone, use one of the following numbers:
Asia-Pacific: +61 2 8446 7411 (Australia: 1 800 805 227)
EMEA: +32 2 704 55 55
USA: 1 800 553-2447
For a complete list of Cisco TAC contacts, go to this URL:
http://www.cisco.com/techsupport/contacts
Definitions of Service Request Severity

To ensure that all service requests are reported in a standard format, Cisco has
established severity definitions.
Severity 1 (S1)—Your network is “down,” or there is a critical impact to your
business operations. You and Cisco will commit all necessary resources around
the clock to resolve the situation.
Severity 2 (S2)—Operation of an existing network is severely degraded, or
significant aspects of your business operation are negatively affected by
inadequate performance of Cisco products. You and Cisco will commit full-time
resources during normal business hours to resolve the situation.

xlviii OL-7242-02
Preface
Obtaining Additional Publications and Information
Severity 3 (S3)—Operational performance of your network is impaired, but most

business operations remain functional. You and Cisco will commit resources
during normal business hours to restore service to satisfactory levels.
Severity 4 (S4)—You require information or assistance with Cisco product
capabilities, installation, or configuration. There is little or no effect on your
business operations.

Information about Cisco products, technologies, and network solutions is
available from various online and printed sources.
• Cisco Marketplace provides a variety of Cisco books, reference guides, and
logo merchandise. Visit Cisco Marketplace, the company store, at this URL:
http://www.cisco.com/go/marketplace/
• Cisco Press publishes a wide range of general networking, training and
certification titles. Both new and experienced users will benefit from these
publications. For current Cisco Press titles and other information, go to Cisco
Press at this URL:
http://www.ciscopress.com
• Packet magazine is the Cisco Systems technical user magazine for
maximizing Internet and networking investments. Each quarter, Packet
delivers coverage of the latest industry trends, technology breakthroughs, and
Cisco products and solutions, as well as network deployment and
troubleshooting tips, configuration examples, customer case studies,
certification and training information, and links to scores of in-depth online
resources. You can access Packet magazine at this URL:
http://www.cisco.com/packet
• iQ Magazine is the quarterly publication from Cisco Systems designed to
help growing companies learn how they can use technology to increase
revenue, streamline their business, and expand services. The publication
identifies the challenges facing these companies and the technologies to help
solve them, using real-world case studies and business strategies to help
readers make sound technology investment decisions. You can access iQ
Magazine at this URL:
http://www.cisco.com/go/iqmagazine

OL-7242-02 xlix
Preface
• Internet Protocol Journal is a quarterly journal published by Cisco Systems

for engineering professionals involved in designing, developing, and
operating public and private internets and intranets. You can access the
Internet Protocol Journal at this URL:
http://www.cisco.com/ipj
• World-class networking training is available from Cisco. You can view
current offerings at this URL:
http://www.cisco.com/en/US/learning/index.html

l OL-7242-02
C H A P T E R 1
Overview
This chapter introduces the major concepts with which you need to be familiar
before creating JTAPI applications for Cisco IP Telephony Solutions. The chapter
covers the following concepts:
• Cisco JTAPI
• CiscoObjectContainer
• JtapiPeer and Provider
• Addresses and Terminals
• Threaded CallBacks
• Alarm Services
• Application Control of JTAPI Parameters
• Supported Device Types
• Call Forward Setting
• Call Park
• CiscoJtapiExceptions
• Device Recovery
• Directory Change Notification
• Transfer and Conference Extensions
• Media Termination Extensions
• Redirect

OL-7242-02 1-1
My Documents.lnk
Chapter 1 Overview
• Routing
• Redundancy
• Display Name Interface
• SetMessageWaiting Interface
• Quite Clear
• GetCallInfo Interface on Address
• DeleteCall Interface
• GetGlobalCallID
• GetCallID in RTP Events
• XSI Object Pass Through
• VG248 and ATA 186 Analog Phone Gateways
• Multiple Calls Per DN
• Shared Line Support
• Transfer and DirectTransfer
• Conference and Join
• Barge and Privacy Event Notification
• CallSelect and UnSelect Event Notification
• Dynamic CTIPort Registration Per Call
• Media Termination at Route Point
• Redirect Set Original Called ID
• Single Step Transfer
• Auto Update of API
• CiscoTerminal Filter and ButtonPressedEvents
• Modifying Calling Number
• AutoAccept Support for CTIPort and RoutePoint
• CiscoTermRegistrationFailed Event
• SelectRoute Interface Enhancement
• Presentation Indicator (PI) for the Call
• Device State Server

1-2 OL-7242-02
Chapter 1 Overview
Cisco JTAPI
• Forced Authorization and Client Matter Codes

• Super Provider (Disable Device Validation)
• Q.Signaling (QSIG) Path Replacement
• Network Events
Cisco JTAPI
An abstract telephony model, Java Telephony application Programming Interface
(JTAPI), can uniformly represent the characteristics of a wide variety of
telecommunication systems. Because JTAPI is defined without direct reference to
any particular telephony hardware or software, JTAPI offers a well suited method
for the task of controlling or observing nearly any telephone system. For instance,
a computer program that makes telephone calls by using an implementation of
JTAPI for modems might work without modification by using the Cisco JTAPI
implementation.
As powerful as an abstraction may be in theory, in practice, programmers often
need to know the details of how the JTAPI model represents the underlying
components of a particular telephony system. A modem represents a very simple
telephony device with limited features. In contrast, the Cisco IP Telephony
Solutions product family offers its users a comprehensive list of features and
configuration capabilities. Programmers can best leverage the rich features of
Cisco IP Telephony Solutions systems by understanding how it fits into the
Cisco JTAPI model.
The following sections outline the deviations, if any, from the JTAPI v 1.2
specification or the specifics of the Cisco JTAPI implementation. Cisco JTAPI
also provides extensions to the JTAPI v 1.2 specification. These extensions offer
additional functionality to the Cisco implementation that is not defined in the
specification. The com.cisco.jtapi.extensions package includes the classes and
interfaces for the extensions, and Chapter 2, “Cisco JTAPI Extensions,” explains
them in detail.

OL-7242-02 1-3
Chapter 1 Overview
CiscoObjectContainer
The CiscoObjectContainer interface allows applications to associate an
application defined object to objects that implement this interface. In
Cisco JTAPI, the following interfaces extend the CiscoObjectContainer interface:
• CiscoJTAPIPeer
• CiscoProvider
• CiscoCall
• CiscoAddress
• CiscoTerminal
• CiscoConnection
• CiscoTerminalConnection
• CiscoConnectionID
• CiscoCallID
JtapiPeer and Provider

The Provider object, which gets created through the implementation of the
JtapiPeer object, acts as the main point of contact between applications and JTAPI
implementations. The Provider object serves as a repository that contains the
entire collection of call model objects, Addresses, Terminals, and Calls,
controllable at any time by an application.
The JTPREFS applications administer JtapiPeer.getServices(), which returns
server names.
The Provider entails two basic processes: initialization and shutdown.
Ensure that the following information is passed in the JtapiPeer.getProvider()
method for applications to obtain a CiscoProvider:
• Hostname or IP address for the Cisco CallManager server
• Login of user administered in the directory
• Password of user specified

1-4 OL-7242-02
Chapter 1 Overview
• (Optional) Application information (this parameter may be a string of any

length)
Applications must include enough descriptive information, so if the appinfo
were logged in an alarm, administrators would know which application
caused the alarm. Applications should not include hostname or IP address
where they reside, nor the time at which they were spawned. Also, ensure that
no “=” or “;” characters are included in the appinfo string because they
delimit the getProvider () string. When the appinfo is not specified, you can
use a generic and quasi-unique name (JTAPI[XXXX]@hostname, where
XXXX represents a random four digit number) instead.
The parameters get passed in key value pairs concatenated in a string as follows:
JtapiPeer.getProvider(“CTIManagerHostname;login=user;passwd=userpasswor
d;appinfo=Cisco Softphone”)
Initialization
The JtapiPeer.getProvider() method returns a Provider object as soon as the TCP
link, the initial handshake with the Cisco CallManager, and device list
enumeration are complete. The provider now exists in the OUT_OF_SERVICE
state. Cisco JTAPI applications must wait for the provider to go to the
IN_SERVICE state before the controlled device list is valid. A ProvInServiceEv
event gets delivered to an object that is implementing the ProviderObserver
interface. Upon an orderly Cisco CallManager shutdown.
Note Implementing only the CiscoProviderObserver does not do enough; the

observer must also get added to the provider with
provider.addObserver(..). Applications must wait for a notification that
the Provider is in service.
Shutdown
When an application calls provider.shutdown(), JTAPI loses communications
permanently with the Cisco CallManager, and a ProvShutdownEv event gets
delivered to the application. The application can assume that the Provider will not
come up again and the application must handle a complete shutdown.

OL-7242-02 1-5
Chapter 1 Overview
Provider.getTerminals()
This method returns an array of terminals that are created for the devices that are
administered in the user control list in the directory. Refer to the
Cisco CallManager Administration Guide to administer the user control list.
Provider.getAddresses()
This method returns an array of addresses that are created from the lines that are
assigned to the devices that are administered in the user control list in the
directory.
Changes to the User Control List in the Directory

If a device is added to the user control list after the JTAPI application starts, a
CiscoTermCreatedEv, and the respective CiscoAddrCreatedEv, gets generated
and sent to observers that are implementing the CiscoProviderObserver. In
addition, applications can monitor the current registration state of the controlled
devices, and dynamically track the availability of these devices. The events for an
in-service Address or Terminal get delivered to observers that are implementing
the CiscoAddressObserver and the CiscoTerminalObserver.
Note Implementing only the observers does not do enough; the observers must
also get added by address.addObserver(..) and, similarly, for the terminal
by the terminal.addObserver(..) method.
Note Before invoking the call.connect() method, add a CallObserver to the

address or terminal that is originating the call. Otherwise, the method
returns an exception.

1-6 OL-7242-02
Chapter 1 Overview
Addresses and Terminals

The Cisco IP Telephony Solutions architecture includes three fundamental types
of endpoints: telephone sets, virtual devices (media termination points and route
points), and gateways. Of these endpoints, only telephones and media termination
points get exposed through the Cisco JTAPI implementation.
Note The maximum number of lines supported for route points is 34.
Cisco CallManager allows users to configure telephones to have one or more

lines, dialable numbers, which multiple telephones may share simultaneously, or
lines can be configured for exclusive use by only one telephone at a time. Each
line on a telephone can terminate two calls simultaneously, one of which must be
on hold.
This operation acts in a similar way to the operation of the “call waiting” feature
on home telephones. Figure 1-1 “Telephone Diagram” shows two configurations,
Peter and Mary share one telephone line, 5001, while Paul has his own telephone
line, 5002.
Figure 1-1 Telephone Diagram
"Peter" "Mary"
5000 5001
5001
"Paul"
5002
33324

OL-7242-02 1-7
Chapter 1 Overview
Address and Terminal Relationship

A unique name identifies all types of Cisco CallManager endpoints. Telephone
terminal hardware Media Access Control (MAC) address (such as,
“SEP0010EB1014”) identifies it, whereas the system administrator may assign
any name to a media termination point, so long as its name is distinct. For each
endpoint that a Provider controls, the Cisco JTAPI implementation uses its
administered name to construct a corresponding Terminal object. Terminal
objects in turn have one or more Address objects, each of which corresponds to a
line on the endpoint. Figure 1-2 “Address and Terminal Relationship” shows a
graphical representation of the relationship between Addresses and Terminals.
Figure 1-2 Address and Terminal Relationship
Addresses 5000 5001 5002
Terminals
33226
"Peter" "Mary" "Paul"
If two or more endpoints share a line (directory number), the corresponding

Address object will be related to more than one Terminal object.
Unobserved Addresses and Terminals

Cisco JTAPI learns about calls only when a CallObserver attaches to the
terminals/addresses of the Provider. This means that methods such as
Provider.getCalls() or Address.getConnections() will return null, even when calls
exist at the address, unless a CallObserver attaches to the address. The system also
requires adding a CallObserver to the Address or Terminal that is originating a
call via the Call.connect(..) method.

1-8 OL-7242-02
Chapter 1 Overview
Connection
Connection
Connections retain their references to calls and addresses forever. So, a
connection reference that is obtained from a call event can always be used to
obtain the connection call (getCall()) and address (getAddress()).
TerminalConnection
TerminalConnections always retain their references to terminals and connections.
So, a terminal connection reference that is obtained from a call event can always
be used to obtain the terminal connection terminal (getTerminal()) and connection
(getConnection()).
CiscoConnectionID
The CiscoConnectionID object represents a unique object that is associated with
each connection in Cisco JTAPI. Applications may use the object itself or the
integer representation of the object.
CiscoCallID
The Cisco CallID object represents a unique object that is associated with each
connection in Cisco JTAPI. Applications may use the object itself or the integer
representation of the object.
Threaded CallBacks
The Cisco JTAPI implementation design allows applications to invoke blocking
JTAPI methods such as Call.connect() and TerminalConnection.answer() from
within their observer callbacks. This means that applications do not get subjected
to the restrictions imposed by the JTAPI 1.2 specification, which cautions
applications against using JTAPI methods from within observer callbacks.

OL-7242-02 1-9
Chapter 1 Overview
Threaded CallBacks
CiscoSynchronousObserver Interface
Applications can selectively disable the queuing logic of the Cisco JTAPI
implementation by implementing the CiscoSynchronousObserver interface on
their observer objects.
This asynchronous behavior does not adversely affect many applications.
Applications that would benefit from a coherent call model during observer
callbacks, however, can selectively disable the queuing logic of the Cisco JTAPI
implementation. By implementing the CiscoSynchronousObserver interface on
its observer objects, an application declares deliver synchronous events to its
observers. Events that are delivered to synchronous observers will match the
states of the call model objects that are queried from within the observer callback.
Note Objects that implement the CiscoSynchronousObserver interface must

invoke blocking JTAPI methods from within their event callbacks. The
consequences of doing so are unpredictable and may include deadlocking
the JTAPI implementation. However, they may safely use the accessor
methods of any JTAPI object, for instance Call.getConnections() or
Connection.getState().
Querying Dynamic Objects

Beware of querying dynamic objects such as call objects. By the time you get an
event, the object (such as, call) may be in a different state than the state that is
indicated. For example, by the time you get a CiscoTransferStartEV, the
transferred call may have removed all its internal connections.
callChangeEvent()
When the callChangedEvent() method is called, the validity remains guaranteed
for any references that are contained in the event. For example, if the event
contains a getConnection() method, the application can call this method and get a
valid connection reference. Likewise, a getCallingAddress() method guarantees
to return a valid Address object.

1-10 OL-7242-02
Chapter 1 Overview
Alarm Services
CiscoConsultCall
For the CiscoConsultCall interface, a reference to a consulting terminal
connection gets retained forever.
For example, when processing a CiscoConsultCallActive event,
getConsultingTerminalConnection() guarantees to return a valid terminal
connection reference. Further, the terminal connection guarantees to provide
access to the consulting connection and thus the consulting call.
CiscoTransferStartEv
For the CiscoTransferStartEv, the references to the transferred call, transfer
controller and final call in the event will be valid when callChangedEvent() is
called. However, getConnections() may or may not return the connections on
these calls.
Alarm Services
Part of the general serviceability framework for Cisco IP telephony applications
includes support for sending alarms to a service. The com.cisco.services.alarm
package defines the alarm components.
An alarm interface and framework support the sending of alarm notifications in
XML over TCP to an Alarm Service that is available on the network in a Cisco
JTAPI application. The alarm package includes the following features:
• · XML definition of alarms, resolved by a catalog in the alarm service
• · A bounded rollover queue to buffer alarms at the sender
• · Alarm sending on a separate thread to avoid blocking at the sending
application
• · A TCP-based reconnection scheme to the alarm service
The overall framework of the Cisco JTAPI alarm system is similar to the existing
JTAPI tracing package. Applications must instantiate an AlarmManager for a
particular facility code from which alarm objects can be created. Part of the
implementation includes DefaultAlarm and DefaultAlarmWriter implementation
classes.

OL-7242-02 1-11
Chapter 1 Overview
Application Control of JTAPI Parameters

The jtapi.ini file includes the various parameters that are required for configuring
Cisco JTAPI. Cisco JTAPI looks for the presence of this file in the current Java
classpath.
Cisco JTAPI also supports application setting of all the parameters Cisco JTAPI
requires. This system allows a single point of application administration,
independent of jtapi.ini. The jtapi.ini file provides a starting point for default
values but client applications can modify different values without having to
specifically modify the jtapi.ini file.
Applications obtain a CiscoJtapiProperties object from the CiscoJtapiPeer and
make changes to the parameters by using the accessor and mutator methods.
These properties, which apply peer-wide to all the providers that are derived from
a CiscoJtapiPeer, must be set prior to the first getProvider () call on that peer.
Different instances of client applications, however, can impose different settings
for these parameters. The com.cisco.jtapi.extensions package defines the
CiscoJtapiProperties interface.
Jtapi.ini Parameters
Cisco JTAPI gets configured by using parameters in the jtapi.ini. These
parameters get modified by using the Jtprefs application, which the Cisco JTAPI
installer installs.
The following parameters apply to Cisco JTAPI:
PROTOCOL_DEBUGGING=1
UseSameDirectory=1
JTAPIIMPL_DEBUGGING=1
UseSystemDotOut=0
QueueStatsEnabled=0
PeriodicWakeupInterval=50
RouteSelectTimeout=5000
UseTraceFile=1
ProviderOpenRequestTimeout=200

1-12 OL-7242-02
Chapter 1 Overview
CtiManagers=cm-server1;cm-server2
Directory=SEAVIEWTraces
DEBUG=1
DesiredServerHeartbeatInterval=30
AlarmServicePort=1444
CTI_DEBUGGING=1
SyslogCollector=
JTAPI_DEBUGGING=1
PeriodicWakeupEnabled=0
NumTraceFiles=10
AlarmServiceHostname=
MISC_DEBUGGING=1
TracePath=.
UseAlarmService=0
CTIIMPL_DEBUGGING=1
WARNING=1
Traces=WARNING;INFORMATIONAL;DEBUG
INFORMATIONAL=1
UseSyslog=0
JtapiPostConditionTimeout=15
JTAPINotificationPort=789
FileNameBase=seaview
CtiRequestTimeout=30
TraceFileSize=1048576
Debugging=JTAPI_DEBUGGING;JTAPIIMPL_DEBUGGING;CTI_DEBUGGI
NG;CTIIMPL_DEBUGGING;PROTOCOL_DEBUGGING;MISC_DEBUGGIN
G
FileNameExtension=log
QueueSizeThreshold=25

OL-7242-02 1-13
Chapter 1 Overview
Supported Device Types
ProviderRetryInterval=30
SyslogCollectorUDPPort=514
UseProgressAsDisconnectedDuringErrorEnabled=0
AllowNetworkEventsAfterOffered=0
Dynamic Trace Enabling Using Jtprefs

You will generally want to turn off high-level debugging traces. Typically, tracing
at full debug levels imposes a load on the system that is not desirable during
normal system operation. For troubleshooting purposes, an administrator can turn
tracing on or off dynamically.
Cisco JTAPI supports the dynamic enabling of traces from the Jtprefs
administrative application. The application communicates with JTAPI by using a
TCP socket and sends a signal to enable or disable the traces. For more details on
dynamic tracing, refer to the Cisco CallManager Administration Guide. Ensure
that the trace file generation is turned on before using dynamic tracing. If no trace
files are being generated, dynamic tracing does not enable file generation.
Dynamic tracing only enables or disables traces on an existing log file stream. By
default, JTAPI enables file writing with all tracing levels off.
Supported Device Types

Cisco JTAPI supports the following device types:
• 30 SP+ (This device has spurious off hook problems—not recommended.)
• 12 SP+ (This device has spurious off hook problems—not recommended.)
• 12 SP (This device has spurious off hook problems—not recommended.)
• 7902
• 7905
• 7910
• 7912
• 7920
• 7935

1-14 OL-7242-02
Chapter 1 Overview
Call Forward Setting
• 7936
• 7960
• 7940
• 7970
• CTI Route Points
• CTI Ports
• VG248 Analog Devices
• ATA 186 Analog Devices
Call Forward Setting

Cisco JTAPI supports setting the Call Forward feature according to the JTAPI
Specification. Cisco JTAPI implementation does not support all the forwarding
characteristics but supports only the FORWARD_ALL attribute for the Address.
Applications can invoke setForwarding, getForwarding, and cancelForwarding
methods on a CallControlAddress object, but the CallControlForwarding
instruction can only be of type FORWARD_ALL.
Call Park
Cisco JTAPI supports user interactions with Call Park and reports the appropriate
events to the applications. When a call is parked from an IP phone, the connection
that belongs to the parking address moves into Disconnected state, and the
associated TerminalConnection moves into Dropped state. A new connection in
queued state for the park number gets created.
If an application is monitoring only the address that parked the call, then all
existing connections get Disconnected, TerminalConnections get Dropped, and
the call moves to Invalid state.

OL-7242-02 1-15
Chapter 1 Overview
Call Park
Park Retrieval
When a call is parked from an IP phone, the park number displays on the phone.
Any terminal can unpark the call by dialing the park number. When a call is
unparked, a new call gets created with connections to unparked address. The
CallControlConnection for the park number in the original call, which is in the
Queued state, moves to the Disconnected state.
Park Reminder
When a parked call is not retrieved for a specified time, a reminder call returns to
the address that parked the call, and Park Number connection moves to the
Disconnected state. The call reconnects and moves to the Established state. A
terminal connection in Talking state gets created for the address that parked the
call.
Park DN Monitor
Cisco JTAPI applications can register to receive events when calls are parked and
unparked. CiscoProvCallParkEv events will be delivered to provider observer
when the application registers for this feature. To successfully register for this
feature the “call park retrieval allowed” flag for the user should be turned on. This
flag is available with the user configuration on Cisco CallManager
Administration. After registering for this feature, the application will receive
CiscoProvCallParkEv events when ever a call is parked or unparked from any
device in the cluster.
The following new interfaces allow applications to register and unregister for this
feature:
public interface CiscoProvider {
public void registerFeature ( int featureID ) throws
InvalidStateException, PrivilegeViolationException;
public void unregisterFeature ( int featureID ) throws
InvalidStateException;
}
The featureID is CiscoProvFeatureID.MONITOR_CALLPARK_DN

1-16 OL-7242-02
Chapter 1 Overview
CiscoJtapiExceptions
CiscoJtapiExceptions
Cisco JTAPI notifies application of CTI-generated error codes. These codes
return when an exception or error occurs in the CTIManager. The CTI returned
error code propagates to the application separately. The application can extract the
error code by invoking getErrorCode() method on the exception object, can get
CTI error code name by invoking getErrorName() method, and can get error
description by invoking method getErrorDescription().
The methods getErrorName(int errorCode) and getErrorDescription (int
errorCode) deprecate and get’ removed in future releases. Cisco recommends that
application users do not use these methods.
Cisco JTAPI Install Internationalization

Cisco JTAPI supports multiple languages for the JTAPI installation and user
preference UI. When JTAPI launches, you receive options for choosing languages
for the installation. After choosing a language, further installation instructions
display in the chosen language. The first option always specifies English. If
certain phrases are missing in the locale language, the instructions default to
English. Refer to the Cisco JTAPI Installation Guide for more installation
information.
Clear Calls Interface

Cisco JTAPI applications can clear phantom calls without dropping active calls.
The CiscoAddress provides a clearCallConnections message to allow applications
to clear the calls when no active calls exist on the Cisco CallManager.
Device Recovery
Cisco JTAPI supports automatic device recovery.

OL-7242-02 1-17
Chapter 1 Overview
Device Recovery
Device Recovery for phones

For devices such as the Cisco IP Phone 7960, the re-homing feature represents
part of the device firmware. On a primary Cisco CallManager failure, the phone
attempts to connect to the backup Cisco CallManager when it is no longer on a
call. This transition gets communicated to applications in the form of
out-of-service and in-service events that are described in the CTIManager Failure
section.
For virtual devices with no firmware such as CTI Ports and CTI RoutePoints, the
the CTIManager or Cisco JTAPI performs the failover.
CTI RoutePoints
On a Cisco CallManager server failure, the CTIManager recovers the device from
the Cisco CallManager server group as defined in the device pool administration
for the CTI RoutePoint. When the primary Cisco CallManager server recovers,
the CTIManager attempts to recover the device on its primary Cisco CallManager.
This re-homing happens when no more calls exist on the device, (similar to
physical devices). On a CTIManager failure, Cisco JTAPI recovers the device on
the backup CTIManager. The application receives notification the availability of
a device with the CiscoAddrOutOfServiceEv and CiscoAddrInServiceEv events.
CTI Ports
CTI Ports that are registered by an application include a mechanism similar to
phone devices. When the Cisco CallManager that is handling signaling for a
CTIPort fails, the CTIManager recovers its services according to the device pool
administration for this device. On a CTIManager failure, Cisco JTAPI reregisters
the CTI Port after it connects to the backup CTIManager. The
CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv events and the
corresponding in service events get sent after recovery of the CTI Port.
The application controls media streaming for these devices, and streaming
continues even when the port is out of service. The application has responsibility
to ensure that new calls do not get presented to the device until it is ready to accept
them.

1-18 OL-7242-02
Chapter 1 Overview
Directory Change Notification
Directory Change Notification

Applications require notification asynchronously of device additions or deletions
from the user control list and device deletions from the Cisco CallManager
database. Applications also receive notification about line changes to a device.
This notification gets sent to Cisco JTAPI, propagates to applications with
CiscoAddrCreatedEv, CiscoAddrRemovedEv, CiscoTermCreatedEv, and
CiscoTermRemovedEv on the AddressObserver and TerminalObservers,
respectively.
Note Ensure that the device is registered for CTIPorts and CTIRoutePoints to receive
the line change notification.
Enable or Disable Ringer

The CiscoAddress extension allows applications to set the status of the ringer for
all lines on a device. No events generate when the ringer setting gets changed from
the administration pages or anywhere else.
Transfer and Conference Extensions

You may find that transfer and Conference events are difficult to understand in
JTAPI. This happens because the participants are moved from one call to the
other, JTAPI represents this action by deleting the parties from one call and
adding them to the other call. It may confuse you for an application to receive an
indication that a party dropped from the call when, in reality, it is in the process
of being moved. The Cisco JTAPI implementation defines some extra events that
make it easier for applications to deal with these functions.
Transfer
The transfer feature moves the participants of one call, the transferred call, to
another call, the final call. Moving participants in a call results in their associated
Connections transitioning to the DISCONNECTED state in the transferred call

OL-7242-02 1-19
Chapter 1 Overview
and new Connections for these participants being created in the final call.
Similarly, any associated TerminalConnections transition into the DROPPED
state in the transferred call and get created in the final call. Cisco extensions have
by definition to mark the start and the end of the events that relate to transfer.
You can correlate the newly created connection objects with the old connection
objects by use of the CiscoConnection.getConnectionID() method to obtain the
CiscoConnectionID for the old and new connections. Matching connections have
identical CiscoConnectionID objects when compared by using the
CiscoConnectionID.equals() method.
This event indicates that the transfer operation started, and the events that follow
relate to this operation. Specifically, Connections and TerminalConnections get
both removed and added as a result of the transfer.
Applications may obtain the two calls that are involved in transfer−transferred call
and final call and the transfer controller information from this event. If the JTAPI
application is not observing the transfer controller, the transfer controller
information does not get made available in this event.
CiscoTransferEndEv
This event indicates that the transfer operation has ended. After this event is
received, the application can assume that all involved parties have transferred, and
all Connections and TerminalConnections have moved to the final call.
Transfer Scenarios
In the following scenarios, A, B, and C represent three parties that are involved in
the transfer.
Consult Transfer, Where B is the Transfer Controller
In a consult transfer, applications can redirect calls to a different address and the
transferrer can “consult” with the transfer destination before redirecting.
• A calls B on call Call1.
• B answers and consults to C on call Call2.

1-20 OL-7242-02
Chapter 1 Overview
• B transfers call Call2 to call Call1.

To do this type of transfer, use the following JTAPI methods:
• Call2.setTransferEnable(true) (This optional method means transfer is
enabled in the call object by default.)
• Call2.consult(TermConnB, C)
• Call1.transfer(Call2)
Note During consult transfer, Call1.transfer(Call2) will transfer the call but not
Call2.transfer(Call1).
Table 1-2 lists the core events that observers of A and B receive between the
CiscoTransferStartEv and the CiscoTransferEndEv:
Table 1-1 Core Events for Observers of A and B
Meta Event Cause Call Event Fields

META_UNKNOWN Call1 CiscoTransferStartEv transferredCall=Call2
finalCall=Call1 trans-
ferController=
TermConnB
META_CALL_TRANSFER Call1 TermConnDroppedEv B CallCtlTer-
RING mConnDroppedEv B ConnDiscon-
nectedEv B
CallCtlConnDisconnectedEv B
META_CALL_TRANSFER Call1 ConnCreatedEv C ConnConnect-
RING edEv C CallCtlConnEstablishedEv C
TermConnCreatedEv C TermCon-
nActiveEv C CallCtlTerm-
ConnTalkingEv C
nectedEv B

OL-7242-02 1-21
Chapter 1 Overview
Table 1-1 Core Events for Observers of A and B (continued)

META_CALL_TRANSFER Call2 TermConnDroppedEv C CallCtlTer-
RING mConnDroppedEv C ConnDiscon-
nectedEv C
CallCtlConnDisconnectedEv C Call-
InvalidEv C
META_UNKNOWN Call2 CallObservationEndedEv
META_UNKNOWN Call1 CiscoTransferEndEv transferredCall=Call2
FinalCall=Call1 Trans-
ferController=
TermConnB
Arbitrary Transfer, Where A is the Transfer Controller
In an arbitrary transfer, one call can get transferred to another call, irrespective of
how either call was created. Unlike consult transfer, no need exists to first create
one of the calls by using the consult method.
• A calls B on call Call1.
• A puts Call1 on hold.
• A calls C on call Call2.
• A transfers Call1 to Call2.
To do this type of transfer, use the following JTAPI methods:
• Call2.transfer(Call1) to transfer call Call1 to final call Call2, or
• Call1.transfer(Call2) to transfer call Call2 to final call Call1
Assuming Call1.transfer(Call2) was called, Table 1-3 lists the core events that
observers on A and C receive between CiscoTransferStartEv and
CiscoTransferEndEv:

1-22 OL-7242-02
Chapter 1 Overview
Table 1-2 Core Events for Observers of A and C

META_UNKNOWN Call1 CiscoTransferStartEv transferredCall=Call2
finalCall=Call1 trans-
ferController=
TermConnB
nectedEv B
META_CALL_TRANSFER Call1 ConnCreatedEv C ConnConnect-
RING edEv C CallCtlConnEstablishedEv C
ConnTalkingEv C
nectedEv B
META_CALL_TRANSFER Call2 TermConnDroppedEv C CallCtlTer-
RING mConnDroppedEv C ConnDiscon-
nectedEv C
CallCtlConnDisconnectedEv C Call-
InvalidEv C
Conference
When conferencing two calls together, JTAPI specifies that all the parties from
one call be moved to the other call. The call whose parties are moved away and
that subsequently becomes invalid gets identified as the “merged” or “consult”
call. The call to which the merged parties move gets identified as the “final” call
hereafter. When parties move from the merged call to the final call, the application
receives events that indicate that all parties dropped from the merged call and
events that indicate that the parties reappeared on the final call.

OL-7242-02 1-23
Chapter 1 Overview
To correlate the newly created connection objects with the old connection objects,
use the CiscoConection.getConnectionID() method to obtain CiscoConnectionID
objects for all old connections and all new connections. Matching connections
will have identical CiscoConnectionID objects when compared by using the
CiscoConnectionID.equals() method.
Conference support exists for the following methods:
• javax.telephony.callcontrol.CallControlCall.conference(Call)
• javax.telephony.callcontrol.CallControlCall.getConferenceController()
• javax.telephony.callcontrol.CallControlCall.getConferenceEnable()
• javax.telephony.callcontrol.CallControlCall.setConferenceController(Terminal
Connection)
• javax.telephony.callcontrol.CallControlCall.setConferenceEnable(boolean)
Cisco Extensions
Cisco JTAPI implementation provides two extra events that signal the Start and
End of Conference: CiscoConferenceStartEv and CiscoConferenceEndEv. These
events get sent when Conference initiates and when it completes. They give
handles to the final call, the merged conference (consult) call, and the two
controlling TerminalConnections (in HELD and TALKING state).
CiscoConferenceStartEv
This event gets sent when call1.conference(call2) is invoked or if the Conference

button is pressed for the second time on an IP phone. The ConferenceStartEv
signifies the start of the merging process. A sequence of merging events that are
reflected by the Conference process in Cisco CallManager follows.
CiscoConferenceEndEv
This event gets sent at the end of the merge process after a ConferenceStartEv is
sent. It signifies the completion of the merge of the Consult (or Merged) call into
the Final Conference Call. The Merged call specifies in INVALID state and an
ObservationEndedEv gets sent for the call observer.

1-24 OL-7242-02
Chapter 1 Overview
CiscoCall.setConferenceEnable()
The Cisco JTAPI implementation uses the CiscoCall.setConferenceEnable() and

the CiscoCall.setTransferEnable() methods to control whether the consult call
will be initiated via the conference or the transfer feature. If none of the features
is enabled explicitly, transfer gets used by default.
Conference Scenarios
The following scenarios describe the two typical types of Conference that can be
invoked.
Consult Conference with B as the Conference Controller
The following sequence of steps typically describes this scenario:

• A calls B (Call 1).
• B answers.
• B Consults C (Call 2).
setConferenceEnable()
call2.consult(tc, C)
• C answers.
• B Completes Conference.
Call1.conference(Call2)
Note You must invoke the conference() method on the original call to complete
a conference after a consultation. Invoking conference in the consult call
object throws an exception.
Arbitrary Conference with B as the Conference Controller
The following sequence of steps typically describe this scenario:

• A calls B (Call 1).
• B answers.
• B places the call on hold.

OL-7242-02 1-25
Chapter 1 Overview
• B calls C (Call 2).

• C answers.
• B Completes Conference.
Call1.conference(Call2) or
Call2.conference(Call1)
Conference Events
Table 1-4 provides the sequence of Core, Call control, and Cisco Extension events
when Call1.Conference(Call2) is called:
Table 1-3 Sequence of Events

META_UNKNOWN Call1 CiscoConferenceStartEv consultCall = Call2
finalCall = Call1
conferenceControl-
ler=TermConnB
META_CALL_MERGING Call1 CallCtlTermConnTalkingEv B
META_CALL_MERGING Call1 ConnCreatedEv C ConnConnect-
edEv C CallCtlConnEstablishedEv C
ConnTalkingEv C
META_CALL_MERGING Call2 TermConnDroppedEv B CallCtlTer-
mConnDroppedEv B ConnDiscon-
nectedEv B
META_CALL_MERGING Call2 TermConnDroppedEv C CallCtlTer- consultCall=Call2
mConnDroppedEv C ConnDiscon- finalCall=Call1
nectedEv C conferenceControl-
CallCtlConnDisconnectedEv C Call- ler=TermConnB
InvalidEv
META_UNKNOWN Call2 CallObservationEndedEv

META_UNKNOWN Call1 CiscoConferenceEndEv

1-26 OL-7242-02
Chapter 1 Overview
Transfer and Conference Enhancement

All parties who are involved in the call transfer get sent CiscoTransferStartEv and
CiscoTransferEndEv. All parties involved in the call conference get sent
CiscoConferenceStartEv and CiscoConferenceEndEv. A call transfer still
generates two events—the dropping of a connection to the first call and the
creation of a connection to the second call. Cisco CallManager Release 3.1
changed this order of events. Connections first get created in the final call and
then get dropped in the consult call.
Note In Cisco CallManager Release 3.0, not all parties who are involved in the transfer
of calls received these events
Note Applications should not rely on the order of events between CiscoTransferStartEv
and CiscoTransferEndEv or between CiscoConferenceStartEv and
CiscoConferenceEndEv for transferring and conferencing when porting
applications from Cisco CallManager Release 3.0 to 3.1.
Consult Without Media

Applications can inform Cisco CallManager that a consultation call for a transfer
is being placed without establishing the media path. The system does not require
establishing the media path for the intermediate call, if the consultation call is
being placed to determine whether an agent is available before the actual transfer.
The consultWithoutMedia method as defined in the CiscoConsultCall interface
creates a consultation call without establishing the media path.
Note The consultation call may only be transferred. It cannot be conferenced.

OL-7242-02 1-27
Chapter 1 Overview
Media Termination Extensions

The media termination feature allows applications to transmit and capture the
bearer of a call, for example, audio or video. This action sometimes gets referred
to as “rendering and recording” or “sourcing and sinking” media. It remains
distinct from call control because media termination concerns the data that flows
between endpoints in a call, not the details of setting up or tearing down calls. For
example, an automatic call distributor (ACD) uses call control to route calls
among available agents but does not terminate media. An interactive voice
response (IVR) application, on the other hand, uses call control to answer and
disconnect calls and uses media termination to play sound files to callers.
Although no telephony applications are solely interested in media termination,
this feature always gets used in combination with call control. JTAPI 1.2 primarily
represents a call control specification and offers very limited support for
applications that require media termination. Because the Cisco IP Telephony
Solutions platform supports media termination to a much greater degree than
JTAPI standard, the Cisco JTAPI implementation extends JTAPI to add full
support for this feature.
In Cisco JTAPI, software-based media termination occurs by using Computer
Telephony Integration (CTI) ports. They include one or more lines (dialable
numbers) that can be used to originate or receive calls. They however need a
controlling application to provide the source and sink of the media. An
application registers its interest in the media termination port with the
Cisco CallManager. The Cisco CallManager then delivers all the events that relate
this virtual device to the application. In Cisco JTAPI, CTI Ports get referred to as
CiscoMediaTerminals. Figure 1-3 shows the CTI port configuration. For details
about administering and configuring a CTI port, refer to the Cisco CallManager
Administration web pages.

1-28 OL-7242-02
Chapter 1 Overview
Figure 1-3 CTI Port Diagram
CTI Port
Softphone "5000"
Call (selective)
Call (on hold)
33325
To implement a softphone application (where the PC acts as the telephone set, for
example), the Cisco JTAPI application would manage a CTI port.
Cisco CallManager Media Endpoint Model

Endpoints represent the entities within the Cisco IP Telephony Solutions platform
that terminate media, such as IP telephones and gateways. A call from one
endpoint to another results in media flowing between the two endpoints. All
endpoints in the Cisco IP Telephony Solutions platform transmit voice data by
using real-time protocol (RTP). The Cisco IP Telephony Solutions telephones and
gateways, for example, include built-in RTP stacks. Applications may also act as
endpoints in a Cisco IP Telephony Solutions system; that is, they may terminate
media. Because all Cisco IP Telephony Solutions endpoints use RTP, applications
also must be able to transmit and receive RTP packets.
Payload and Parameter Negotiation

In addition to bearer data, payload, each RTP packet contains a header that helps
endpoints to determine how to reassemble and decode a sequence of such packets
into a media stream. RTP does not provide, however, a means for endpoints to
negotiate which payload type to use for a particular stream. For example, audio
data that is encoded by using the G.711 standard. Furthermore, RTP does not offer
a means of negotiating unique payload type parameters such as the sampling rate
of the encoded data or the number of samples that are to be transferred in each
RTP packet. Instead, RTP usually gets used in conjunction with another protocol
such as H.323, which specifies its own method for endpoints to negotiate these
parameters. All such negotiation occurs prior to transmitting RTP packets
between endpoints.

OL-7242-02 1-29
Chapter 1 Overview
Cisco CallManager, not the endpoints, has responsibility for selecting the
payload and encoding parameters for RTP streams. The following five steps that
are involved in a typical bidirectional audio telephone call apply:
• Initialization
• Payload Selection
• Receive Channel Allocation
• Starting Transmission and Reception
• Stopping Transmission and Reception
Initialization
Upon startup, each endpoint informs Cisco CallManager of its media capabilities,
that is, G.711, G.723, G.729a, and so on. Startup for an IP phone for example,
occurs when the phone is first turned on, or after it recontacts Cisco CallManager
after losing its former connection. The endpoint cannot express a preference for
one payload type versus another, but it can specify certain parameters for each
payload type, such as, packet size.
The capability list that the endpoint registers remains exclusive and immutable. If
the endpoint specifies that it can support both G.711 and G.723, it implicitly
declares that it cannot support G.729a. Moreover, the endpoint must disconnect
from Cisco CallManager and reinitialize to change the list of capabilities that it
supports.
JTAPI applications perform this step by registering a CiscoMediaTerminal with
Cisco CallManager. The CiscoMediaTerminal.register() method allows
applications to supply an array of media capability objects for registration with
Cisco CallManager. This step informs Cisco CallManager that the application
will act as the endpoint for all calls to or from a particular directory number, as
determined by the device configuration in the Cisco CallManager configuration.
Payload Selection
When a bidirectional media stream is about to be created between two endpoints,
for instance, when a call is answered at an endpoint, Cisco CallManager selects
an appropriate payload type (codec) for the media stream. Cisco CallManager
compares the media capabilities of both endpoints that are involved in the call and
selects the appropriate common payload type and payload parameters to use.

1-30 OL-7242-02
Chapter 1 Overview
The basis for payload selection includes endpoint capabilities and location,
although other criteria may get added to this selection logic in the future.
Endpoints do not get dynamically involved in selecting payload types on a
call-by-call basis.
Receive Channel Allocation

If Cisco CallManager can find a common payload type for the RTP stream
between the two endpoints, it requests that each endpoint create a logical “receive
channel;” that is, a unique IP address and port at which the endpoint will receive
RTP data for the call. Each endpoint returns an IP address and port to
Cisco CallManager in response to this request.
Currently, only IP phones and gateways perform this step. Cisco CallManager
requires JTAPI applications to specify a fixed IP address and port during
initialization. Therefore, JTAPI applications cannot terminate more than one
media stream simultaneously for the same endpoint. Applications that want to
terminate multiple media streams must register multiple endpoints
simultaneously.
If the endpoint does not respond to the open receive channel request quickly
enough, Cisco CallManager disconnects the call. Because JTAPI applications
always supply an IP address when registering CiscoMediaTerminals, calls to
application-controlled endpoints do not get disconnected for this reason.
However, if Cisco CallManager cannot find a common payload type between the
two endpoints that are involved in the call, Cisco CallManager disconnects the
call.
Starting Transmission and Reception

After Cisco CallManager receives channel information for both parties, it informs
each endpoint of the codec parameters that it selected for the RTP stream and the
destination address for the other endpoint. This information gets conveyed in two
messages to each endpoint: a start transmission message and a start reception
message.
JTAPI applications receive the CiscoRTPOutputStartedEv and
CiscoRTPInputStartedEv events that contain all the codec parameters that are
necessary for sending and receiving RTP data.

OL-7242-02 1-31
Chapter 1 Overview
Stopping Transmission and Reception

When the RTP stream must be interrupted because of a feature such as hold or
disconnect, Cisco CallManager requests that each endpoint stop its transmission
and reception of RTP data. Just as when the media flow is started, the stop
transmission and stop reception messages get sent separately.
JTAPI applications receive the CiscoRTPOutputStoppedEv and
CiscoRTPInputStoppedEv.
CiscoMediaTerminal
In JTAPI, the terminal object represents the logical endpoint for a call and is
presumed to be able to receive and transmit data (digital encoded voice samples,
for example). Thus, terminals in JTAPI represent Cisco IP Phones. Even though
gateways terminate media, terminals do not represent them. The
CiscoMediaTerminals in particular represent a special kind of endpoint for which
applications take responsibility for media termination.
The following four steps associate with using CiscoMediaTerminals:
• Provisioning
• Registration
• Adding Observers
• Accepting Calls
Provisioning
CiscoMediaTerminals, which are analogous to physical terminals, must be
provisioned accordingly in Cisco CallManager, even though they do not represent
actual hardware IP phones or gateways. Just as IP phones must be added to
Cisco CallManager database by using the Device Wizard, CiscoMediaTerminals
get added the same way, so Cisco CallManager can associate the application
endpoint with a directory number and other call control properties such as call
forwarding. No device type called “CiscoMediaTerminal” exists in the
DeviceWizard. Instead, Cisco CallManager has one or more device types that
support application registration—each of these types get exposed as a
CiscoMediaTerminal through JTAPI. Currently, only the device type “CTI port”
represents a CiscoMediaTerminal in JTAPI.

1-32 OL-7242-02
Chapter 1 Overview
The following procedure lists the steps for provisioning a CTI port for use as an
application-controlled endpoint.
Procedure
Step 1 Within the Cisco CallManager configuration web pages, add a “CTI port” device
from the Device-Phone web page by using the Device Wizard. The CTI port
device name specifies the name of the corresponding CiscoMediaTerminal in
JTAPI.
Step 2 Add the new CTI port device, by using the User-Global Directory web page, to
the list of devices that the application controls by using the User web page.
For more information, refer to the Cisco CallManager Administration Guide.
Registration
After a media termination device is properly provisioned in Cisco CallManager,
the application may obtain a reference to the corresponding CiscoMediaTerminal
object by using either the Provider.getTerminal() method or
CiscoProvider.getMediaTerminal() method. The the two methods differ in that the
CiscoProvider.getMediaTerminal() method only returns CiscoMediaTerminals,
whereas Provider.getTerminal() will return any terminal object that is associated
with the provider, including those representing physical IP phones.
Use the CiscoMediaTerminal.register() method to notify Cisco CallManager of
their intent to terminate RTP streams of certain payload types. The
CiscoMediaTermina.register() method takes an IP address, a port number, and an
array of CiscoMediaCapability objects that indicate the types of codecs that are
supported by the application as well as codec-specific parameters.
The IP address and port indicate the address where the application desires to
receive media streams. The following sample code demonstrates how to register
a CiscoMediaTerminal and bind it to a local address, port number 1234:
CiscoMediaTerminal registerTerminal (Provider provider, String
terminalName) {
final int PORT_NUMBER = 1234;
try {
CiscoMediaTerminal terminal = provider.getTerminal
(terminalName);

OL-7242-02 1-33
Chapter 1 Overview
CiscoMediaCapability [] caps = new CiscoMediaCapability [1];

caps[0] = CiscoMediaCapability.G711_64K_30_MILLISECONDS;
terminal.register (InetAddress.getLocalHost (), PORT_NUMBER,
caps);
}
catch (Exception e) {
return null;
}
}
For this sample code to work, the specified provider must be IN_SERVICE.
Further, note that this code uses the constant
CiscoMediaCapability.G711_64K_30_MILLISECONDS. This actually
represents a static reference to a CiscoG711MediaCapability object that specifies
a 30-millisecond maximum RTP packet size. The CiscoMediaCapability class
predefines this and other common media formats.
To specify a media payload that is not listed in the CiscoMediaCapability class,
two options exist. If the desired payload type is a simple variation of one of the
existing subclasses of CiscoMediaCapability, you only need to construct a new
instance of the subclass. For instance, if an application is willing to support G.711
payloads with a 60-millisecond maximum RTP packet size, it can construct the
CiscoG711MediaCapability object directly, specifying 60 milliseconds in the
constructor.
On the other hand, if no existing subclass of CiscoMediaCapability that matches
the desired payload type exists, construct an instance of the
CiscoMediaCapability class directly. The maximum packet size, for example,
30-milliseconds, represents the only other parameter that may be specified when
constructing a CiscoMediaCapability. The following code illustrates registering a
custom payload capability:
CiscoMediaTerminal registerTerminal (Provider provider, String

terminalName) {
final int PORT_NUMBER = 1234;
try {
CiscoMediaTerminal terminal = provider.getTerminal
(terminalName);
CiscoMediaCapability [] caps = new CiscoMediaCapability [1];
caps[0] = new CiscoMediaCapability (
RTPPayload.G728,
30 // maximum packet size, in milliseconds
);
terminal.register (InetAddress.getLocalHost (), PORT_NUMBER,
caps);

1-34 OL-7242-02
Chapter 1 Overview
}
catch ( Exception e) {
return null;
}
}
The payload type parameter that is used for constructing the

CiscoMediaCapability object corresponds to the payload field in the RTP header.
The RTPPayload interface defines a number of well-known payload types for this
purpose.
Adding Observers
To receive events that indicate where and when to transmit and receive RTP data,
place a CiscoTerminalObserver on the CiscoMediaTerminal. The
CiscoTerminalObserver extends the standard JTAPI TerminalObserver interface
without defining any new methods; it provides a marker interface that signals the
application interest in receiving RTP events.
Note Because this is a TerminalObserver, not a CallObserver, it must be added by using

the Terminal.addObserver() method, not the Terminal.addCallObserver() method.
Additionally, add a CallControlCallObserver to the Address object that is

associated with the CiscoMediaTerminal. This guarantees that the application will
get notified when calls are offered to the CiscoMediaTerminal. Unlike regular IP
phones, which automatically accept any offered call, CiscoMediaTerminals
accept, disconnect (reject), or redirect any call that is offered to it. Because the
CallCtlConnOfferedEv is only presented to CallControlCallObservers that are
placed on Address objects, not Terminal objects, the application places its
CallControlCallObserver in the correct place.
Note Be sure to implement the CallControlCallObserver interface, not just the

CallObserver interface; the CallCtlConnOfferedEv will not get delivered to
observers that implement only the core CallObserver interface.

OL-7242-02 1-35
Chapter 1 Overview
Accepting Calls
When an inbound call arrives at the CiscoMediaTerminal address, it must be
accepted by using the CallControlConnection.accept() method before a terminal
connection gets created. This process does not apply for outbound calls —the
connection will occur in the CallControlConnection.ESTABLISHED state as
soon as the call progresses beyond digit recognition. After the connection is
accepted, answer the ringing terminal connection to start media flow. Assuming
that Cisco CallManager can match the capabilities that were registered with the
capabilities of the calling endpoint, Cisco CallManager sends the Media Flow
events, so the application can begin transmitting and receiving RTP data.
Receiving and Responding to Media Flow Events

Whenever a media stream must be created between two endpoints,
Cisco CallManager issues start transmission and start reception events to both
endpoints. In JTAPI, the CiscoRTPOutputStartedEv and
CiscoRTPInputStartedEv events represent the start transmission and start
reception events. The CiscoRTPOutputStartedEv.getRTPOutputProperties()
method returns a CiscoRTPOutputProperties object, from which the application
can determine the destination address of its peer endpoint in the call, as well as
the other RTP properties for the stream such as payload type and packet size.
Similarly, the CiscoRTPInputStartedEv.getRTPInputProperties() method returns
a CiscoRTPInputProperties object that informs the application of the RTP
characteristics for the inbound stream.
At any time while media is flowing, the current CiscoRTPOutputProperties and
CiscoRTPInputProperties also remain available from the
CiscoMediaTerminal.getRTPOutputProperties() and
CiscoMediaTerminal.getRTPInputProperties() methods as well. These methods
throw an exception if the CiscoMediaTerminal is not currently supposed to
transmit or receive media.
When Cisco CallManager wants the application to stop sending or receiving
media as the result of a call disconnecting or being put on hold, for example, it
sends the CiscoRTPOutputStoppedEv and CiscoRTPInputStoppedEv events.
These events mean that the current RTP media stream that exists between the two
endpoints should be torn down.

1-36 OL-7242-02
Chapter 1 Overview
Inbound Call Media Flow Event Diagram

Table 1-5 illustrates the dialogue between Cisco CallManager and a JTAPI
application when a call is presented to an application-controlled endpoint. The
events in the left column represent JTAPI events that are sent to the CallObserver
of the application, and the requests in the left column represent methods that the
application invokes.
Table 1-4 Inbound Media Flow Event
JTAPI Event Direction Application Request

CallActiveEv
ConnCreatedEv −−−>
ConnProceedingEv
CallCtlConnOfferingEv
<−−− CallControlConnection.accept ()
CallCtlConnAlertingEv
TermConnCreatedEv −−−>
TermConnRingingEv
<−−− TerminalConnection.answer ()
ConnConnectedEv
CallCtlConnEstablishedEv
TermConnTalkingEv
CiscoRTPOutputStartedEv
CiscoRTPInputStartedEv
<−−− CallControlConnection.discon-
nect ()
CiscoRTPOutputStoppedEv
CiscoRTPInputStoppedEv −−−>
TermConnDroppedEv
CallCtlConnDisconnectedEv

OL-7242-02 1-37
Chapter 1 Overview
Redirect
Note Table 1-4 shows JTAPI events for the local connection, that is, for the application
endpoint. The actual JTAPI meta event stream will contain events that describe the
state of the calling party.
Cisco IP Telephony Solutions RTP Implementation

The Cisco IP Telephony Solutions architecture puts a premium on performance,
and thus Cisco IP Telephony Solutions phones and gateways do not implement
some of the features of RTP and its often-associated real-time control protocol
(RTCP). To ensure its compatibility, applications must consider the following
points:
• Because RTCP is not supported. Cisco IP Telephony Solutions endpoints will
not send RTCP messages, and they will ignore any such messages that are
sent to them.
• Cisco IP Telephony Solutions endpoints do not currently make use of the
synchronization source (SSRC) field in the RTP header but may in the future.
Applications must not multiplex RTP streams by using the SSRC field, or
phones and gateways may not correctly decode and present the media.
Redirect
JTAPI 1.2 specifies that one of the preconditions of the
CallControlConnection.redirect() method is for the state of the connection to be
in either the CallControlConnection.OFFERING or the
CallControlConnection.ALERTING state. Cisco JTAPI also allows a connection
in the CallControlConnection.ESTABLISHED state to be redirected.
The redirect() method includes the following overloaded form in the
CiscoConnection interface. It allows applications to specify the behavior that is
desired when a failure occurs while redirecting a call, specifying the calling
search space, or resetting the original called field.

1-38 OL-7242-02
Chapter 1 Overview
Redirect
Applications choose the desired behavior, by passing one of the following INT
parameters in the overloaded redirect method from the CiscoConnection
interface:
• Redirect drop on failure—When a call is directed to a busy or an invalid
destination, Cisco CallManager can either drop the call if the redirect fails or
leave the call at the redirect controller. The JTAPI application then has a
chance to take corrective action, such as redirecting the call to another
destination. The option for the redirect mode parameter follow:
– CiscoConnection.REDIRECT_DROP_ON_FAILURE
– CiscoConnection.REDIRECT_NORMAL
• Calling Address search space—Redirect uses the calling search space
parameter to indicate which callingSearchSpace is used. Applications can
either use the calling party search space or the redirect controller search
space. The parameter options for this scenario follow:
– CiscoConnection.CALLINGADDRESS_SEARCH_SPACE
– CiscoConnection.ADDRESS_SEARCH_SPACE
• Resetting original called—The called address option parameter gets used to
reset the original called fields. The options for this scenario follow:
– CiscoConnection.CALLED_ADDRESS_UNCHANGED
– CiscoConnection.CALLED_ADDRESS_SET_TO_REDIRECT_DESTIN
ATION. This option affects the fields when the call arrives at the redirect
destination.
For more information, refer to the com.cisco.jtapi.extensions.CiscoConnection
documentation.

OL-7242-02 1-39
Chapter 1 Overview
Routing
Routing
Routing in JTAPI requires the configuration of a CTI Route Point on the
Cisco CallManager. Multiple calls can be queued to this Route Point, but only a
single line can be configured on a CTI Route Point device.
JTAPI implementation of adjunct Routing as described in the call center package
includes the following actions:
• Registering route callbacks on Route Addresses
• Creating appropriate handlers in response to the various routing events
(routeSelect, routeEnd)
Note CTI Route Points represent devices that can process any number of
incoming calls simultaneously on the same line. Calls may be routed by
using the methods in the javax.telephony.callcenter package, or calls may
be accepted, redirected, or disconnected by using the methods in the
javax.telephony.callcontrol package. Each CTI Route Point may be
configured with only one line in the Cisco CallManager. A single CTI
Route Point supports a maximum of 34 lines. To support more than 34
lines, provision additional route points. For details on how to configure
and administer the CTI Route Point, refer to the Cisco CallManager
Administration Guide.
Figure 1-4 shows the CTI Route Point configuration.
Figure 1-4 CTI Route Points
CTI Route Point

"5001"
IVR Simultaneously
active calls
35938

1-40 OL-7242-02
Chapter 1 Overview
Routing
Cisco Route Session Implementation

When a call comes in to the RouteAddress, the implementation starts a Route
Session thread and sends the application a RouteEvent. This thread in turn starts
a timer thread to time the application response to a RouteEvent with either a
routeSelect() or an endRoute(). If the application responds with a routeSelect
(String[] selectedRoutes), JTAPI verifies that all preconditions are satisfied and
then attempts to route the call to the first destination that is specified in the array.
If the destination is a valid and available number, the call gets routed, and the
application gets a RouteUsedEvent followed by a RouteEndEvent. Otherwise, if
an error occurs in routing (which may be caused by an invalid/busy/unavailable
destination), the application gets a ReRouteEvent. JTAPI starts the Timer Thread
again before it sends the re-Route Event. Because Cisco CallManager does not
support re-Routing, if the routing was unsuccessful, the caller will either receive
a busy tone, or the call will get dropped. The application can clean up all failure
instances and/or send JTAPI an endRoute to clean up the RouteSession. If the
application does not respond with an endRoute(), the JTAPI timer once again
expires, and JTAPI cleans up the Route Session by sending the application a
RouteEndEvent().
If the routing timer expires before the application returns with a selectRoute() or
an endRoute() method, the Cisco CallManager applies same treatment as when a
call is made to an unregistered phone (that is play fast busy). If ForwardNoAnswer
is configured on the Route Point, the call immediately forwards to that number
when the timer expires.
If the application cannot respond with a valid address to which to route the call,
the application may choose to call endRoute with an error. The JTAPI
specification defines three errors in the RouteSession interface:
ERROR_RESOURCE_BUSY, ERROR_RESOURCE_OUT_OF_SERVICE, and
ERROR_UNKNOWN. If an endRoute is invoked on the RouteSession, the
implementation currently accepts() the call at the RouteAddress, so the caller may
begin to receive ringback. Thereafter, if forwarding is configured for the Route
Point, the call gets forwarded when the Forwarding Timer expires.

OL-7242-02 1-41
Chapter 1 Overview
Routing
Select Route Timer

Configure this timer via the JTAPI.ini configuration file that has a key called
RouteSelectTimeout=5000. Use milliseconds as the unit. The default value for
this timer specifies 5 seconds; however, depending on the needs of the application,
you can extend or decrease this timer to improve Route Session cleanup
efficiency. This timer should not be unreasonably large. Each Route Session as a
thread represents a call to the Route Point, and these Route Sessions should be
cleaned up. Should an application expect significant delays between receiving the
Route Event and responding with a routeSelect/endRoute event, the application
would want to appropriately extend this timer.
Forwarding Timer
The timer for Forward on No Answer that is currently system wide (that is, it
applies to all devices on Cisco CallManager) can be configured via the
Cisco CallManager Service Parameters configuration. The default value for this
timer specifies 12 seconds. In future releases, a separate timer for CTI Route
Points will be included, so Forwarding for the Route Point takes effect
immediately after JTAPI accepts the call (when the application calls an endRoute
or if the routing timer expires).
RouteSession Extension
CiscoRouteSession acts as a Cisco Extension to the JTAPI specification. Most
importantly, this extension exposes the underlying Call object to the Applications.
CiscoRouteSession.getCall() returns CiscoCall, and this call exposes other Call
Model Objects such as the associated Addresses, Connections, and so on. The
extension also defines additional errors for the application.
Caller Options Summary

In the absence of a callback or in the scenario RouteSession.routeSelect() or
endRoute() has not responded to a routeEvent, the caller receives nothing until
• The application can disconnect() or reject() the connection on the Route Point
and thereby the caller receives a busy tone.

1-42 OL-7242-02
Chapter 1 Overview
Routing
• The application can accept the call, and then the Forward No Answer, if
configured, will kick-in.
• The application can drop the call. The caller holds the receiver with no clue
about what happened.
With a callback, if the application chooses to call an endRoute(), after endRoute()
returns, the caller receives a ringback until:
• client calls a disconnect() that would drop the call.
• The client redirects() the call.
• The forward on no answer timer that is configured via the scm.ini will kick
in and forward the call unless the preceding two options have already kicked
in.
• If no forwarding is configured for the Route Point, the caller continues to
receives a ringback unless the first two options kick in.
Fault Tolerance When Using Route Points

One way for an application that uses route points to deal with fault tolerance
requires connecting two JTAPI applications to two different Cisco CallManagers,
each registering a different RouteAddress. For example, Application1 manages
RouteAddress1 by using CallManager1. Application2 manages RouteAddress2
using CallManager2. In Cisco CallManager Administration, the
ForwardNoAnswer configuration for these CTI Route Points must be
administered so they point to each other. In this example, RouteAddress1 would
have FNA=RouteAddess2, and RouteAddress2 would have FNA=RouteAddress1.
If CallManager1 goes down, calls forward to RouteAddress2, so Application2
takes over. Furthermore, both applications could be configured to reconnect to the
proper Cisco CallManager server when they receive a ProviderShutdown event.

OL-7242-02 1-43
Chapter 1 Overview
Redundancy
Redundancy
Configuration requires that devices are configured into device pools and are
assigned static Cisco CallManager groups. Devices register with a particular
Cisco CallManager server that handles call control signaling. When a
Cisco CallManager server fails, the devices failover to the backup
Cisco CallManager server in the group. When the primary Cisco CallManager
comes back online, it waits until no active calls exist on the device, then re-homes
to the primary Cisco CallManager server. Cisco JTAPI informs the applications
of this transition by sending a temporary out-of-service message while registering
to the backup Cisco CallManager server.
Cluster Abstraction
The CTIManager provides a virtual representation of all the Cisco CallManagers
in a cluster. Cisco JTAPI applications communicate with the CTIManager instead
of with a specific Cisco CallManagers. The CTIManager also maintains
connection between Cisco CallManagers in a cluster. This allows a provider to
represent any devices in the cluster under the CTIManager. Figure 1-5 illustrates
“Single-box Configuration with JTAPI, Cisco CallManager, and CTIManager in
One Box.” Figure 1-6 illustrates “Redundant Cisco CallManager and
CTIManagers with JTAPI Deployed as a Separate Client.”
For more details about the cluster administration and device pool settings, refer to
the Cisco CallManager help pages.

1-44 OL-7242-02
Chapter 1 Overview
Redundancy
Figure 1-5 Single-box Configuration with JTAPI, Cisco CallManager, and

CTIManager in One Box
IP
IP
JTAPI IP
CTIManager
Cisco CallManager
IP
63168
Devices registered on
Cisco CallManager

OL-7242-02 1-45
Chapter 1 Overview
Redundancy
Figure 1-6 Redundant Cisco CallManager and CTIManagers with JTAPI

Deployed as a Separate Client
JTAPI
deployed here
CTIManager 2
CallManager 2
CTIManager 1
CallManager 1
IP
IP IP
IP IP
Devices registered Devices registered
63169
on CallManager 1 on CallManager 2
Note In previous releases of Cisco CallManager, applications that are running on

Cisco JTAPI could only control or monitor devices that are registered under a
single Cisco CallManager. If a Cisco CallManager server went down, the
connection between the Cisco CallManager server and JTAPI would terminate
and the Provider would shut down. Cisco CallManager Release 3.1, introduced
CTIManager service.
Cisco CallManager Server Failure

If a Cisco CallManager server fails, the associated devices re-home to the next
Cisco CallManager server in the group. The prioritized list of
Cisco CallManagers in the device pool information configuration for each device
defines this process.

1-46 OL-7242-02
Chapter 1 Overview
Redundancy
Failure of a Cisco CallManager server only results in a partial outage of devices

in the cluster. Those devices remain available following a successful
Cisco CallManager failover and registration with a secondary
Cisco CallManager.
Note A device such as a Cisco IP Phone 7960 fails over to a secondary

Cisco CallManager server only when no active calls exist on that device. The
failure of a Cisco CallManager server during a call results only in termination of
observation of that device. The media path continues to exist but without any
further call control features.
Cisco JTAPI communicates this partial outage to applications by using

CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv events. When the
Cisco CallManager fails over, the device must successfully register to the
secondary Cisco CallManager before the device is available to the JTAPI
applications. Cisco JTAPI will send the CiscoAddrInServiceEv and
CiscoTermInServiceEv events.
The Provider remains in service during this time. Devices on other
Cisco CallManager servers remain available for call control. The events get sent
on callbacks of the respective Address or Terminal observer objects.
CiscoAddrOutOfServiceEv and CiscoAddrInServiceEv events get sent to an
object that is implementing the AddressObserver and get added to an Address
using the addressChangedEvent() callback object method. The
CiscoTermOutOfServiceEv and CiscoTermInServiceEv events get sent to an
object implementing the TerminalObserver interface and get added to a Terminal
that is using the terminalChangedEvent( ) callback method.
If the devices are currently in a call, a CallObservationEnded message is sent on
the CallObserver callChangedEvent() callback, followed by the
CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv messages.
Note Applications must monitor for and respond to the CiscoAddrOutOfServiceEv,

CiscoTermOutOfServiceEv, CiscoAddrInServiceEv, and CiscoTermInServiceEv
events before the calling call control functions on the Address or Terminal.
Applications that do not support this may encounter unexpected errors because
the applications do not know the exact state of the system.

OL-7242-02 1-47
Chapter 1 Overview
Redundancy
Redundancy in CTIManagers
Cisco JTAPI also offers transparent applications for redundancy via the
CTIManager. When the primary CTIManager fails, Cisco JTAPI automatically
connects to the backup CTIManager and communicates the reconnection to
applications. Instead of connecting to a single Cisco CallManager server,
applications now connect to a set of CTIManagers. The applications supply the
CTIManager server names when invoking JTAPI.
Cisco JTAPI and the CTIManager maintain bidirectional heartbeat signals to
detect a loss of connectivity between them. The CTIManager detects when an
application is no longer running and cleans up its allocated resources. Figure 1-7
illustrates the“Logical Representation of JTAPI, CTIManager and
Cisco CallManager in a Cluster”
Note After Cisco JTAPI successfully connects to the primary CTIManager, it will
alternately attempt to reconnect to the primary or backup CTIManager if the
JTAPI connection to the CTIManager fails.
Figure 1-7 Logical Representation of JTAPI, CTIManager and

Cisco CallManager in a Cluster
CTIManager 1
(primary)
Cisco JTAPI CallManager 1
JTAPI application
CallManager 2
CallManager 3
CTIManager 2
(secondary-backup)
Connection is made to the backup when
63170
the primary CTIManager connection fails

1-48 OL-7242-02
Chapter 1 Overview
Redundancy
Invoking CTIManager Redundancy

When getProvider() method on the CiscoJtapiPeer is called during the application
startup, Cisco JTAPI attempts a connection to the first CTIManager in the list and
tries a connection to the next CTIManager if connection attempt fails with the
first. If all the CTIManagers in the list are not available or if connection is refused
by all CTIManagers, an exception gets sent to the application and no further
reconnection attempts occur. After the first successful connection, Cisco JTAPI
alternatively attempts to connect to the backup or primary CTIManager when a
failure to CTIManager or connection to CTIManager is detected.
The list of redundant CTIManagers designates a comma-separated list that is
passed into the CiscoJtapiPeer.getProvider(String providerString) method as a
String. The usage for the providerString follows:
• providerString = CTIManager;login=XXX;passwd=YYY;appinfo=ZZZ
(Non-redundant feature)
• providerString =
CTIManager1,CTIManager2;login=XXX,passwd=YYY;appinfo=ZZZ
(Redundant feature)
Note Because the appinfo parameter is optional, the application provides no specific
appinfo parameter. Cisco JTAPI generates one from a JTAPI instance ID and the
local host name.
Additionally, the jtapi.ini file may define different CTIManager lists to support
the CiscoJtapiPeer.getServices() method. Cisco JTAPI accepts the following
definition:
CtiManagers=<CTIManager1>,<CTIManager2>;<CTIManager3>
where
<CTIManager1>,<CTIManager2> specifies a redundant group.
<CTIManager3> specifies a nonredundant group.

OL-7242-02 1-49
Chapter 1 Overview
Redundancy
CTIManager Failure
When Cisco JTAPI detects a loss of connection to a CTIManager, the application
receives notification of this loss in service. The following events get sent to the
application on the appropriate Observers:
• A CallObservationEndedEv event gets sent to all Call Observers on an
Address and calls in progress end. The calls get physically connected, but the
application observation of the call ends because Cisco JTAPI cannot send call
state changes.
• A CiscoAddrOutOfServiceEv event gets sent to all Addresses on a Terminal
and a CiscoTermOutOfServiceEv event gets sent to the Terminal.
• This process repeats for all Terminals in the Provider user-controlled list. (A
CiscoAddrOutOfServiceEv event gets sent only to the Addresses that have an
active AddressObserver, and a CiscoTermOutOfServiceEv event gets sent
only to Terminals with an active TerminalObserver.)
• The Provider gets set in the out-of-service state, and the ProvOutOfServiceEv
event gets delivered on any ProviderObserver callbacks present on the
Provider.
Cisco JTAPI attempts a connection to the next CTIManager in the list and the
ProvInServiceEv gets sent to the ProviderObserver, The devices previously
registered under the application control get reinstated in the new CTIManager
After the device is reinstated, CiscoAddrInServiceEv and CiscoTermInServiceEv
events get sent to the application via the respective Observers. All previously
added Observers are maintained. If any calls exist on the devices, a snapshot of
the call gets sent to the respective CallObservers.
CTIPorts that were previously registered are reregistered with the same media
parameters. RouteAddress call backs are maintained as before and these are
recovered on the new CTIManager. No call snapshot, however, gets delivered to
the RouteAddresses.

1-50 OL-7242-02
Chapter 1 Overview
Display Name Interface
Heartbeats
Cisco JTAPI and the CTIManager maintain heartbeat signals to discover a failure
in either the CTIManager or JTAPI. The CTIManager server controls the
heartbeat parameters in the bidirectional heartbeat. Applications can request a
desired server heartbeat interval when initializing Cisco JTAPI, but the
CTIManager can override it.
Applications specify the desired heartbeat parameter by using
DesiredServerHeartbeatInterval in the jtapi.ini setting.
Cisco JTAPI specifies the client's desired heartbeat interval during initialization.
The CTIManager specifies to the client side heartbeat interval Cisco JTAPI and
specifies the interval at which the server (CTIManager) will send heartbeats. A
failure to receive heartbeat message over twice the server-specified interval
results in a client-initiated tear-down of the connection. To minimize heartbeat
traffic, any messages from the client to the server or events from the server to the
client substitute for a heartbeat.
Display Name Interface

The CiscoCall interface provides methods to get name displays of the calling
party and the called party in a call. Applications can use
getCurrentCallingPartyDisplayName() to get the display name of the calling
party.
JTAPI applications can use the following interface to get the display names of the
calling party and the called party.
{
..
..
/**
*This interface returns the display name of the called party in
the call.
*It returns null if display name is unknown.
*/
public String getCurrentCalledPartyDisplayName();
/**
*This interface returns the display name of the calling party.
*It returns null if display name is unknown.
*/

OL-7242-02 1-51
Chapter 1 Overview
SetMessageWaiting Interface
public String getCurrentCallingPartyDisplayName();

}
The address objects store the display name internally and name gets updated when
currentCallingAddress and currentCalledAddress are updated. NULL returns if
the call is not in the active state and if currentCalling and currentCalled addresses
of the call are not initialized.
Note The system does not support Call.getCurrentCalledAddress() and

call.getCurrentCallingAddress() for conference calls. Also, the system does not
support call.getCurrentCalledPartyDisplayName() and
call.getCurrentCallingPartyDisplayName() for a conference call.
SetMessageWaiting Interface
SetMessageWaiting provides a method for applications gets to set the message
waiting lamp or indicator for an address. The method is invoked on an address that
is in the same partition as the destination.
The following interface specifies whether the message waiting indicator should be
activated or deactivated for the address that the destination specifies. If enable
is true, message waiting activates if not already activated. If enable is false,
message waiting deactivates if not already deactivated.
{
public void setMessageWaiting (java.lang.String destination, boolean
enable)
throws javax.telephony.MethodNotSupportedException,
javax.telephony.InvalidStateException,
javax.telephony.PrivilegeViolationException
}

1-52 OL-7242-02
Chapter 1 Overview
Quite Clear
Quite Clear
QuiteClear occurs at the other end when two parties are on a call and one address
goes OutOfService because of a network outage, the Cisco CallManager goes
down, application controlling CTIPort goes down, or CTIManager goes down. At
this stage, the other end of the call can only drop the call or disconnect the
connection. It cannot perform any other callControl operations.
For the party that went Out Of Service, applications will perceive
ConnDisconnected/TermConnDroppedEvs and the other end of the call receives
ConnFailedEv with CiscoCause of
CiscoCallEv.CAUSE_TEMPORARYFAILURE.
If applications try to invoke the following features during Quite Clear mode,
PlatformException with error code of
CiscoJtapiException.CTIERR_OPERATION_FAILER_QUIETCLEAR gets
thrown:
• Consult transfer
• Consult conference
• Blind transfer
• Hold
• Unhold
Note Applications may only drop the call in this mode.
GetCallInfo Interface on Address

GetCallInfo interface on address provides applications with the ability to query
CallInfo on an address. A query returns the CiscoAddressCallInfo object, which
contains information about the number of active or held calls, maximum number
of active or held calls, and the Call object for current calls on the address. This
interface also specifies what calls are at a specific address at a specific time.

OL-7242-02 1-53
Chapter 1 Overview
DeleteCall Interface
Use the following interface to get information about calls that are present at the
terminal:
{ public CiscoAddressCallInfo getAddressCallInfo(Terminal iterminal);
}
DeleteCall Interface
DeleteCall interface provides applications the ability to delete a call that was
created by using the createCall interface. This method accepts a call and throws
an InvalidStateException if a provider is not in service or if the call is not in the
IDLE state. DeleteCall moves the call to the INVALID state.
The following interface gets added to CiscoProvider:
{ public void deleteCall( Call call ) throws InvalidStateException;
}
Applications can use this interface to delete the call that was created by using
createCall interface. This method accepts a call and throws an
InvalidStateException if the provider is not in service or if the call is not in the
IDLE state. DeleteCall moves the call to the INVALID state.
To successfully delete a call, the application creates the call by using createCall,
and the call should be in the IDLE state.
GetGlobalCallID
GetGlobalCallID provides an interface on the CiscoCallID to get the nodeID and
the Global Call ID (GCID) of the call; this exposes the GCID information that is
available in the internal call object.
The following methods get added to the CiscoCallID interface:
{ /**
* returns the callmanager nodeID of the call
*/
public int getCallManagerID();
/**

1-54 OL-7242-02
Chapter 1 Overview
GetCallID in RTP Events
* returns the GlobalCallID of the call

*/
public int getGlobalCallID ();
}
GetCallID in RTP Events

GetCallID provides an interface on RTP events to access any call information,
such as calling party or called party, so applications can link RTP events with the
calls.
The callLegID that is received in the RTP events from CTIManager gets used to
determine the ICCNCall on the client side. This call passes on to the JTAPI layer,
and the CiscoCall gets determined from which CiscoCallID is obtained. This
information gets used to construct the RTP events that are delivered to the
application.
The following interface gets added to CiscoRTPInputStoppedEv,
CiscoRTPInputStartedEv, CiscoRTPOutputStoppedEv, and
CiscoRTPOutputStartedEv:
{ public CiscoCallID getCallID();
}
XSI Object Pass Through

Applications can pass XML objects through JTAPI and CTI interfaces to the
phone. The XML object can contain display updates, softkey
update/enable/disable, and other types of updates on the phone that are available
through IP phone services features. This allows applications to access IP phone
service capabilities through JTAPI and CTI interfaces without maintaining
independent connections to the phones.

OL-7242-02 1-55
Chapter 1 Overview
XSI Object Pass Through
CiscoTerminal Method
Applications can send an XSI object in the byte format to the Cisco IP Phone
through the CiscoTerminal interface method. The payload is limited to 2000 bytes
of data with this interface.
CiscoTerminal must be in the <CODE>CiscoTerminal.REGISTERED</CODE>
state, its Provider must be in the <CODE>Provider.IN_SERVICE</CODE> state.
Successful response indicates that the data that was pushed has arrived at the
phone. However, note that the application cannot receive any XML back from the
phone, including the CiscoIPPhoneResponse object from the push. If the
application request is not successful, PlatformException is thrown. Any request
with more than 2000 bytes of data is rejected.
public String sendData (String terminalData) throws
InvalidStateException, MethodNotSupportedException;
Before the application can make use of this feature, it must add TerminalObserver
on the Terminal.
Authentication and Mechanism

Sending an HTTP POST request to the phone web server, which requires the
phone IP address, performs an object push. The web server parses the request,
authorizes the request through the HTTP returned to the Cisco CallManager,
executes the request, and returns an XML response to the application indicating
the success or failure of the request.
With XSI, the IP phone services object gets sent directly to the phone by the
Skinny Client Control Protocol (SCCP). The phone does not authenticate the
request, since the JTAPI client is trusted, and does not require the phone IP
address. For more information on actual XML contents, please refer to the
Cisco IP Phone Services Application Development Notes.

1-56 OL-7242-02
Chapter 1 Overview
VG248 and ATA 186 Analog Phone Gateways
VG248 and ATA 186 Analog Phone Gateways

Cisco JTAPI supports control of analog phone that are connected to the VG248
and ATA 186 Analog Phone Gateways. By adding the VG248 and ATA 186
Analog Phone Gateways to the user-controlled list, applications can control the
devices.
Applications receive events for the devices in a way similar to other IP phones.
Applications can also initiate calls and invoke other features except answer
Request through APIs. Make call works only when the device goes physically
off-hook.
Applications cannot answer calls from APIs for the devices. If an application
attempts to answer () on TerminalConnection for the VG248 and ATA 186
Terminal, the system throws PlatformException with error
CiscoJtapiException.COMMAND_NOT_IMPLEMENTED_ON_DEVICE. To
answer calls, you must manually pick up the handset and then you can invoke
other call control features such as transfer, conference, blind transfer, and park
from the API.
Multiple Calls Per DN

Multiple calls per DN is the ability to support multiple calls on a line (DN) and
the features operation on these calls. Prior to Cisco CallManager Release 4.0(1),
only a maximum of two calls were supported. CiscoJtapi supports multiple calls
per line, which will enable applications to have multiple calls on the same line and
feature operation on that line.
There are no interface or message flow changes for Multiple Calls Per DN.
Shared Line Support

Shared line is the same DN appearances on multiple terminals. CiscoJtapi
provides support for Shared Line, which provides applications the ability to
control Shared DN terminals, hold a call on one Shared DN Terminal and unhold
the same call from another Shared DN Terminal, make calls between two Shared
Line, initiate a call from one Shared Line Terminal while there is another active
call on other Shared Line Terminal with the same DN.

OL-7242-02 1-57
Chapter 1 Overview
Shared Line Support
Share Line provides the following interfaces:

• CiscoAddress.getInServiceAddrTerminals()—Returns an array of terminals
for which the address is in service.
Terminal {} getInServiceAddrTerminals();
• CiscoAddrOutOfService.getTerminal()—Returns the terminal that is going

OutOfService.
Terminal getTerminal();
• CiscoAddrInService.getTerminal()—Returns the terminal that is going

InService.
Terminal getTerminal();
• CiscoConnection.setRequestController(TerminalConnection tc)—Allows an
application to select a terminalConnection associated with Connection on
which you can perform Park, Redirect, or Disconnect operations. This would
be needed in a situation where there is more than one active
TerminalConnection in SharedLine scenario.
• CiscoConnection.getRequestController()—Returns TerminalConnection set
by Application as request controller.
• CiscoAddrAddedToTerminalEv—Gets sent when the following conditions
occur:
– A Terminal/Device gets added into the user controlList that contains a
SharedDN, which sends the event to the application. In other words, if
user has an address in control list, and we add new device with same
address in control list, this event gets sent.
– An EM (Extension mobility) user logs into the terminal with a profile
that contains a SharedDN. In this scenario, this event notifies that a new
terminal is added to an already existing Address.
– A new SharedDN is added to a Device in a user control list
Interface getTerminal() returns the terminal that gets added to the Address.
Interface getAddress() returns the Address on which a new terminal is added.

1-58 OL-7242-02
Chapter 1 Overview
Shared Line Support
• CiscoAddrRemoveFromTerminalEv—Gets sent when the following

conditions occur:
– A user removes a Terminal/Device from the user controlList that contains
a SharedDN. In other words, if a user has a Shared address in a control
list, and one of the devices with same address gets removed, this event
gets sent.
– An EM(Extension mobility) user logs out from the terminal that had a
profile that containing a SharedDN. This event notifies applications that
one of the terminals is removed from an existing Address.
– A new SharedDN (SharedLine) is removed from a Device in a control
list.
Interface getTerminal() returns the terminal that gets removed from the
Address.
Interface getAddress() returns the address from where the terminal gets
removed.
The following are the changed or new behaviors for a SharedLine:
• Behavior changes for CiscoAddress event include:
– JTAPI Applications will receive multiple CiscoAddrInServiceEv for
Shared Line Addresses. Applications can use
CiscoAddrInServiceEv.getTerminal() to get the terminal on which
address goes InService.
– JTAPI applications receive multiple CiscoAddrOutOfServiceEv for a
Shared Line Addresses. Applications’ can use
CiscoAddrInServiceEv.getTerminal() to get terminal on which address
goes OutOfService.
– The Address State goes InService when a first Shared Line goes
InService, for example, when the first CiscoAddressInServiceEv gets
received.
– The Address State goes OutOfService when the last Shared Line goes
OutOfService, for example, when the last CiscoAddressOutOfServiceEv
gets received.
• For an incoming call, all the line appearances of a Shared line ring. To
applications, this gets presented as one active call (callActiveEv), one
Connection(ConnCreatedEv), and multiple
terminalConnection(TermConnCreatedEv one each for each Shared line).

OL-7242-02 1-59
Chapter 1 Overview
Shared Line Support
• Calls get presented to all terminals. When a call is in a ringing state, the state
of the terminal connection is Ringing. When one of the Shared Line answers,
the terminalConnection state goes to an Active state, while other
terminalConnections on the shared line go to a Passive state and
callControlTerminalConnection for all the shared lines at this point go into a
Bridged state. When a call is put on Hold, all the terminal connections go into
an Active state, and callControllTerminalConnection goes to a Held state. At
this point, any terminal can retrieve the call. The retrieving terminal
terminalConnection remains in an Active state and
callControlTerminalConnection goes to a Talking state while all other shared
terminals terminalConnections go into a Passive state. Simultaneously,
CallControlTerminalConnection changes from a Held state to a Bridged state.
• A Shared Line can make a call to another Shared Line of the same DN. In this
scenario, the call has only one Connection and multiple terminal
Connections.
• When a Shared Line makes a call to another Shared line of same DN, the post
condition for this would be only one connection.
• For a Shared Line Connection with two active terminalConnections (such as
Barge), Connection.Disconnect() does not result in disconnected connection.
• If an application is monitoring only a SharedDN Connection with only a
Passive or Bridged TerminalConnection, any API invoked on the connection
results in a PreConditionException.
• Similar to the previous scenario, if all the connections of a Call monitored by
an application have only a Passive or Bridged TerminalConnection, all APIs
on the call throw a PreConditionException (such as Call.Drop()).
• If there is more than one active TerminalConnection on a Shared Line,
Call.drop() does not return in CallInValid in the following scenarios:
– In the case of a normal two party call between A and B, where A is a
SharedLine with A' and A' has Barged into the Call. The application is
not monitoring A' and B. If the application issues a Call.drop(), A’s
TerminalConnection goes into a Passive state, but the call does not go
InValid.

1-60 OL-7242-02
Chapter 1 Overview
Shared Line Support
– Similar to above, if A, A' , A" and B are in a Conference Call. The

application is monitoring only A and A' and Call.drop() does not result
in call going InValid. Only A and A' terminal connections go Passive.
– A, A' and B, B' are a SharedLine address. A Calls B, B answers, and A'
and B' barge into the call. The application monitors only A and B. In this
scenario, Call.drop() results in a TerminalConnection of A and B going
Passive, but the call does not go InValid.
• If a TerminalConnection is in a Passive or Bridged state or Passive/InUse
state, all APIs on the TerminalConnection() throw a PreConditionExpection.
Only an API TerminalConnection.Join() (called Barge) gets allowed in a
Passive or Bridged state. Today, TerminalConnection.Join() is not supported.
• If there are more than one Active or Talking TerminalConnections in a
connection, applications may have to end one before issuing an API on the
connection like Redirect(), Park(), Disconnect(). A TerminalConnection can
be selected using API Connection.setRequestController
(TerminalConnection tc).
• If a call gets held on SharedLine Terminals and an application issues a
Connection.Disconnect (), the applications may set a particular
TerminalConnection through API
Connection.setRequestController(TerminalConnection tc). If
requestcontroller is not set, all HeldTerminalConnections get dropped, and
Connection goes to a Disconnected State. If only one HeldConnection gets
dropped, the call remains present on other SharedLines Terminals. The call
appearance disappears from the dropping terminal, which disallows the
terminal from Barging into the call or participating in feature operations on
the call.
For details on the interface changes, see Chapter 2, “Cisco JTAPI
Implementation.” To view the message flow for Shared lines, see Appendix A,
“Message Sequence Charts.”

OL-7242-02 1-61
Chapter 1 Overview
Transfer and DirectTransfer
Transfer and DirectTransfer

The Transfer feature provides the ability to transfer a call.
The Direct transfer feature is the ability to transfer any of the two calls present on
the line so that controller of the call drops out and other two parties remain active
on the call. This functionality gets supported with one enhancement, which is this
feature can be done in any state of the call and also redesign to work with new CTI
events. The following enhancements apply to the Transfer feature:
• The application can Transfer two held Calls.
• The application can have OneHeld and OneConnected call in any order.
• The application can Transfer any two calls present on the line.
The following are the changed or new behaviors for Transfer and DirectTransfer:
• CiscoTransferStarted. getTransferControllers()—This is a new interface
provided for SharedLine scenarios, as there will be multiple
terminalConnections if a SharedLine is a TransferController. When a
transferController is not a SharedLine, only a TerminalConnection occurs in
the list. This method returns null if the transfer controller is not being
observed.
• CiscoTransferStarted. getTransferController()—This is the current interface,
which behaves as it is for a normal transfer scenario, however, it may exhibit
a different behavior for SharedLines. When a transferController is a
SharedLine, multiple TerminalConnections exist. This method returns an
ACTIVE TerminalConnection, however, if the application is not observing
the ACTIVE TerminalConnection, this method returns one of the PASSIVE
TerminalConnections.
• CiscoTransferEnded isSuccess()—This is a new interface provided on the
CiscoTransferEnded event. It returns true if the transfer operation is
successful and false if Transfer failed. Transfer failure may result from the
following:
– Party Dropping the Call before CallProcessing could complete Transfer
– CallProcessing is unable to Complete transfer due to some reason.

1-62 OL-7242-02
Chapter 1 Overview
Conference and Join
The following are changed or new behaviors for JTAPI Transfer.

• No Hold or UnHold messages occur with an Arbitrary Transfer.
• If a Pre-Condition for a Transfer request has been modified, an application
can issue Transfer in any state of the call.
• If an application does not have an Active TerminalConnection passed as an
argument, Call.consult() throws a
PreConditionException/InvalidArgumentExcpetion.
• If controller does not have any Active TerminalConnection, Call.Transfer()
throws a PreconditionException/InvalidArgumentException.
Implementation.” To view the message flow for Transfer and DirectTransfer, see
Appendix A, “Message Sequence Charts.”
Conference and Join

The Conference Feature provides the ability to conference more than two people
into a single Call. Events at CTI layer change and Cisco JTAPI gets enhanced to
support the new CTI events.
Join Feature is ability to join multiple calls into one single conference call. This
functionality was limited to joining only two calls and called Arbitrary
Conference. Now it supports multiple calls. Applications need to pass an array of
calls to be conferenced together.
The following are new or changed interfaces for conference and Joining of
multiple calls into one conference call:
• The following interface allows Join to conference multiple calls into one
conference call:
Call.Conference(Call[] otherCalls)
Note A precondition requires all the otherCalls must have controller as one
leg of the call.

OL-7242-02 1-63
Chapter 1 Overview
Conference and Join
• The following are new or modified interfaces in CiscoConferenceStartEv:

– TerminalConnection getHeldConferenceController()—This is existing
interface, however, now useful only for Arbitrary Conference of two calls
and returns only one of the held calls.
– TerminalConnection[] getHeldConferenceControllers()—This is new
interface to get all the heldCalls when we are Joining multiple calls.
– TerminalConnection getTalkingConferenceController()—This is an
existing interface. This interface returns the talking conference
controller, however if there is no talking conference controller when all
the calls being joined into conference are held, this interface returns Null.
– Call getConferencedCall()—This is an existing interface. It returns only
one out of the many calls going to Join into a conference and may not
have any meaning for a Join conference when there are more than two
calls.
• New interface in CiscoConferenceEnded event boolean isSuccess():
This interface Returns True or False depending on whether Conference is
successful or failed. Application can use interface to find whether Conference
is successful. Following are defined as Conference Failure:
– If application issues request Call.conferece(otherCalls[]) this
Conference would be considered failed, if one or more than one Calls
could Join into Conference. Application can use interface
getFailedCalls() to find Failed Call.
– If no Conference Bridge available and conference could not be completed
at all. Again Application can use interface getFailedCalls() to get list of
Calls that couldn't Join into Conference.
– Party being Conferenced Dropped out, before conference could be
completed.
• A new interface on CiscoConferenceEnded event (Call[] getFailedCalls())
gets all the calls that failed to Join the conference when the conference fails.

1-64 OL-7242-02
Chapter 1 Overview
Conference and Join
The following are the new or changed behaviors for Conference:

• There will not be a Hold or UnHold message as applications see when
Arbitrary Conference occurs.
• The precondition for an Arbitrary Conference gets changed. There is no
longer a requirement that at least one call must be in a Talking state.
Note A precondition requires all the otherCalls must have a controller as

one leg of the call.
• Applications can Conference two or more Held Calls into a Conference Call.
In finalCall, the Controller automatically gets retrieved to a Talking state.
• Always include an active call in the request Call.Conference(otherCalls). If
an Active Call is not included in the Conference request, the request fails.
• If there is no Active Call at the Controller, the Call.Conference(otherCalls)
request remains successful. However if there is one active call, it must be
included in the request as previously stated.
• If the application does not have an Active TerminalConnection passed as an
argument, Call.consult() throws a
PreConditionException/InvalidArgumentExcpetion.
• If the Controller does not have an Active TerminalConnection,
Call.Conference()/Call.Conference(Call[]) throws a
PreconditionException/InvalidArgumentException.
Implementation.” To view the message flow for Conference and Join, see

OL-7242-02 1-65
Chapter 1 Overview
Barge and Privacy Event Notification
Barge and Privacy Event Notification

The Barge Feature provides the ability for Shared Addresses to Barge into an
established Call of Address on another terminal. This feature gets activated when
an address TerminalConnection is in the Passive State and
CallCtlTerminalConnection is in the Bridged State. This version of Cisco JTAPI
only supports feature activation manually on application-controlled terminals (IP
phones). For this release, the feature can not be activated through an API.
The Privacy Feature provides the ability to enable or disable other Shared
Addresses to Barge into Call. When Privacy is enabled, other Shared Addresses
can not Barge into a call and vice versa. Privacy is a Terminals property. IP phones
have a “Privacy” softkey and pressing it enables or disables the privacy. Privacy
can be dynamically enabled or disabled for the Active Calls on the terminal. When
Privacy is on for the call, the TerminalConnection for the call appearances on the
Shared Address are in the “InUse” State. If Privacy Status changes during the
CallProgress, CiscoTermConnPrivacyChangedEvent gets delivered to
application.
There are two types of Barge feature functionalities provided in
Cisco CallManager: one uses built-in Conference Bridge called “Barge”, while
another uses Shared Conference Bridge resources called “CBarge”. From the
application point of view, there are no interface changes between Barge and
CBarge, however, there are some behavioral changes, which are described in the
message flow diagram in Appendix A, “Message Sequence Charts.”.
The following are the new or changed interfaces for Barge, CBarge, and Privacy:
Interface CiscoTerminalConnection.getPrivacyStatus()
boolean getPrivacyStatus()
This interface returns the privacy status of a call on the terminal.
Interface CiscoTermConnPrivacyChangedEv
javax.telephony.TerminalConnection getTerminalConnection()
A new reason code, CiscoCall.CAUSE_BARGE gets added to CiscoCall for

Barge events.

1-66 OL-7242-02
Chapter 1 Overview
CallSelect and UnSelect Event Notification
JTAPI provides CallCtiCause as CiscoCall.CAUSE_BARGE when a SharedLine

TerminalConnection or CallCtiTerminalConnection goes to an Active or Talking
state as a result of Barge. This cause code also gets provided in CallCtiEvents for
dropping temporary calls created during the Barge operation.
This cause code is not provided for the CBarge scenario.
Implementation.” To view the message flow for Barge, CBarge, and Privacy, see
CallSelect and UnSelect Event Notification

You can Select or UnSelect Call on a phone for doing DirectTransfer or Join or
any other feature operation. When a SharedLine User Selects a Call, the
RemoteInUse Shares Line TerminalConection will go Passive and
CallCtlTermiCallConnection goes in InUse State. When Call is unselected, then
CallCtlTerminalConnection goes into a Bridged State. An Application can not
invoke any API on Passive/InUse TerminalConnection. Select/UnSelect operation
is also performed by CallProcessing during Features (such as
Transfer/Conference) operation. Applications will also see these events if the
RemoteInUse Terminal is monitored by Applications.
For example, if A and A' are SharedLine, and A “Selects” the call, then
CallCtlTerminalConnection of A' goes into a Passive or InUsed State. If A
“UnSelects” the call, then CallCtlTerminalConneciton of A' goes into the Passive
or Bridged State.
There are no interface changes for CallSelect or UnSelect.
To view the message flow for CallSelect or UnSelect, see Appendix A, “Message
Sequence Charts.”

OL-7242-02 1-67
Chapter 1 Overview
Dynamic CTIPort Registration Per Call

This feature enables applications to provide an IP address (ipAddress) and port
number (portNumber) for each call or whenever media is established. In order to
use this feature, applications must register the Media Terminal by supplying
media capabilities. When a call is answered at this Media Terminal,
CiscoMediaOpenLogicalChannelEv is sent to applications. This event gets sent
whenever media is established. Applications must react this event and specify the
IP address and port number where media gets established.
A CiscoMediaTerminal is a special kind of CiscoTerminal that allows
applications to terminate RTP media streams. Unlike a CiscoTerminal, a
CiscoMediaTerminal does not represent a physical telephony endpoint, which is
observable and controllable in a third-party manner. Instead, a
CiscoMediaTerminal is a logical telephony endpoint, which may be associated
with any application that terminates media. Such applications include voice mail
systems, interactive voice response (IVR), and softphones.
Note Only CTIPorts appear as CiscoMediaTerminals through Cisco JTAPI.
Terminating media is a two-step process. To terminate media for a particular

terminal, an application adds an observer that implements the
CiscoTerminalObserver interface using the Terminal.addObserver method.
Finally, the application registers its IP address and port number to which the
terminal incoming RTP streams are directed using the
CiscoMediaTerminal.register method.
In order to register supply the ipAddress and portNumber dynamically on a per
call basis, applications must register by only providing capabilities that they
support. Applications must react to CiscoMediaOpenLogicalChannelEv that gets
sent whenever media is established. If any features are performed before
applications react to CiscoMediaOpenLogicalChannelEv, the features may fail.
If the applications do not respond to this event during the time period that is
specified in the Media Exchange Timer in the Cisco CallManager Administration
windows, the call may fail.
Implementation.” To view the message flow for Dynamic CTIPort Registration
Per Call, see Appendix A, “Message Sequence Charts.”

1-68 OL-7242-02
Chapter 1 Overview
Note ChangeRTPDefaults interface has been removed from CiscoMediaTerminal

because this was never supported.
The following are the new or changed interfaces for Dynamic CTIPort
Registration Per Call:
Interface CiscoMediaOpenLogicalChannelEv Extends CiscoTermEv
int getpacketSize()
Returns the packet size of the far end in milliseconds.
int getPayLoadType()
Returns the payload format of the far end, one of the
following constants:
CiscoRTPHandle getCiscoRTPHandle ()
Returns the CiscoTerminalConnection object on which
applications must invoke the setRTPParams request.
Interface CiscoRTPHandle
int getHandle()
Returns an integer representation of this object, currently
the Cisco CallManager CallLeg ID.
CiscoProvider
CiscoCall getCall (CiscoRTPHandle rtpHandle)

Returns the call object with the rtpHandle associated with
a specific terminal. If no callobserver gets added to the
terminal at the time when the applications receive
CiscoRTPHandle in CallOpenLogicalChannelEv,
CiscoCall may be null.

OL-7242-02 1-69
Chapter 1 Overview
Media Termination at Route Point

This feature enables multiple active calls at the Route Point and applications can
terminate media for all active calls by specifying the IP Address and port number
for each call or whenever media is established. In order to use this feature,
applications must register the route point by supplying media capabilities. When
a call gets answered at this route point, CiscoMediaOpenLogicalChannelEv gets
sent to the applications. This event gets sent whenever media is established.
Applications must react to this event and specify the IP address and port number
to where they want to terminate media.
A CiscoRouteTerminal is a special kind of CiscoTerminal that allows applications
to terminate RTP media streams. Unlike a CiscoTerminal, a CiscoRouteTerminal
does not represent a physical telephony endpoint, which is observable and
controllable in a third-party manner. Instead, a CiscoRouteTerminal is a logical
telephony endpoint, which may be associated with any application that desires to
route calls and also terminate media. Unlike CiscoMediaTerminal,
CiscoRouteTerminal can have multiple active calls at the same time. Typically,
CiscoRouteTerminals get used to place calls in queue until an agent is available
to service the caller.
Note Only RoutePoint Terminals appear as CiscoRouteTerminal through JTAPI.
Terminating media is a three-step process.
Step 1 The application registers its media capabilities with this terminal using
CiscoRouteTerminal.register method.
Step 2 An application adds an observer that implements CiscoTerminalObserver
interface using the Terminal.addObserver method.
Step 3 The application must add addCallObserver on CiscoRouteTerminal or on
CiscoRouteAddress in order to receive CiscoCall object from the provider by
using CiscoRTPHandle.
Applications receive CiscoMediaOpenLogicalChannelEv for each call and must

supply the IP address and port number using setRTPParams method on
CiscoRouteTerminal.

1-70 OL-7242-02
Chapter 1 Overview
All applications written for or prior to CiscoJtapiClient 1.4(x) release must get
modified to register with CiscoRouteTerminal.NO_MEDIA_TERMINATION if
not interested in media termination.
Multiple applications can register with same route point as long as they are
registered with same media capabilities and registrationType. All applications, if
registered with CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION and
adds terminal observer, receive CiscoMediaOpenLogicalChannelEv, but only one
application will be able to invoke setRTPParams.
Note Applications that terminate media must use the CallControl package for
answering and redirecting calls. Applications that only route calls can use a
routing package.
Note Applications should be aware that if any features are performed before reacting to
CiscoMediaOpenLogicalChannelEv, the features may fail. If applications do not
respond to these events in the time period specified in the Media Exchange
Timeout parameter in the Cisco CallManager Administration windows, the call
may fail.
The following are the new or changed interfaces for Media Termination at Route
Point:
Interface CiscoRouteTerminal Extends CiscoTerminal
boolean isRegistered()
If the CiscoMediaTerminal gets registered, this method returns
true. Otherwise, it is false.
boolean isRegisteredByThisApp()
If the application issues a successful registration request, this
method returns true and remains true until the application
unregisters the device. This is valid even if the device is out of
service because of CTIManager failure.

OL-7242-02 1-71
Chapter 1 Overview
void register (CiscoMediaCapability[] capabilities, int

registrationType)
The CiscoRouteTerminal must be in the
CiscoTerminal.UNREGISTERED state and the Provider must be
in the Provider.IN_SERVICE state.
void setRTPParams (CiscoRTPHandle rtphandle, CiscoRTPParams

rtpParams)
Applications set the ipAddress and the RTP port number to
dynamically stream media for a call.
void Unregister()
The CiscoRouteTerminal must be registered and the Provider
must be in the Provider.IN_SERVICE state.
Interface CiscoMediaOpenLogicalChannelEv Extends CiscoTermEv
int getpacketSize()
following constants:
CiscoRTPHandle getCiscoRTPHandle ()
Returns the CiscoTerminalConnection object on which
applications must invoke the setRTPParams request.
Interface CiscoRTPHandle
int getHandle()
Returns an integer representation of this object, currently
the Cisco CallManager CallLeg ID.

1-72 OL-7242-02
Chapter 1 Overview
CiscoProvider
CiscoCall getCall (CiscoRTPHandle rtpHandle)

Returns the call object with the rtpHandle associated with
a specific terminal. If no callobserver gets added to the
terminal at the time when the applications receive
CiscoRTPHandle in CallOpenLogicalChannelEv,
CiscoCall may be null.

Implementation.” To view the message flow for Media Termination at Route
Point, see Appendix A, “Message Sequence Charts.”

OL-7242-02 1-73
Chapter 1 Overview
Redirect Set Original Called ID
Redirect Set Original Called ID

Cisco JTAPI applications can specify the preferred original called party DN in the
redirect request. The purpose of the Redirect Set Original Called ID is to allow
applications to redirect a call on a connection to another destination while
allowing the applications to set the OriginalCalledID to any value. This enables
applications to transfer the call directly to some another user voicemail. For
example, if A calls B and B wants to transfer the call to C VoiceMail, then
applications can specify in the enhanced redirect request C as the preferred
original called Party and destination party as C VoiceMail profile. With this
request, calls appear in C VoiceMail profile with the Cisco CallManager
originalCalledParty field as C. Typical voicemail applications look for
originalCalledParty information to identify a user voice mailbox.
However, this enhanced redirect request is not only restricted for transfer to
voicemail, but for any application that redirects a call to a party by modifying the
original called party
Note This feature also changes lastRedirectedAddress to preferredOriginalCalledParty

that gets specified in the redirect request.
The following is a change to the callControlConnection interface for Redirect Set

Original Called ID:
Interface CiscoConnection Extends callControlConnection With Additional

Cisco CallManager-Specific Capabilities
javax.telephony.Connection redirect (java.lang.String

destinationAddress, int mode, int
callingSearchSpace,
java.lang.String
preferredOriginalCalledParty)
This method overloads the
CallControlConnection.redirect() method.

Implementation.” To view the message flow for Redirect Set Original Called ID,
see Appendix A, “Message Sequence Charts.”

1-74 OL-7242-02
Chapter 1 Overview
Single Step Transfer

This interface allows applications to transfer a call to an address. Cisco JTAPI
continues to support this interface as defined in JTAPI 1.2 specification, but the
events delivered to applications are changed from the previous versions of
Cisco JTAPI.
In previous versions of Cisco JTAPI, the original call goes to a held state and a
new call gets created between the transfer controller and destination when
applications use this interface. After successful completion of transfer, both calls
on transfer controller go to an IDLE state. If a transfer fails, the original call
remains in a held state and applications retrieve the call. CiscoTransferStart and
End events get delivered to the applications at the start and completion of the
transfer operation.
Applications get the following changes:
• A new call is not created.
• CiscoTransferStartEv and CiscoTransferEndEv are not delivered to
applications.
• The state of the original call is retained if the transfer operation fails.
The pre and post conditions of this interface are not changed.
To view the message flow for Single Step Transfer, see Appendix A, “Message
Sequence Charts.”
Auto Update of API

When the Cisco CallManager is upgraded to a higher version, the APIs may or
may not be compatible with the new Cisco CallManager version. Hence, the APIs
must be upgraded to a compatible version so the applications work as expected.
Since the APIs are installed locally on the client server, the upgrade must be
performed on multiple machines. In the case of fewer client applications, this is
easily done by connecting to the Cisco CallManager Administration and
downloading and installing the Cisco CallManager compatible plug-in.
For multiple client applications, this feature provides a facility by which an
application at startup can identify itself to a web server via an HTTP request and
receives a response with the version of the required JTAPI API.

OL-7242-02 1-75
Chapter 1 Overview
Auto Update of API
The application compares the version available on the server to the local version
in the application classpath and determines whether an upgrade is necessary. This
allows applications to refresh the jtapi.jar component to match the
Cisco CallManager and provides a way to centrally deploy the jtapi.jar to which
applications can auto update.
The API required to perform this functionality is packaged in the form of an
updater.jar. The jtapi.jar and updater.jar are packaged with the standard manifest,
which can be used to compare versions.
Note This feature does not update JTAPI Preferences, JTAPITestTools, Updater.jar and
javadoc components. If applications require these components, then need to in
install JTAPI from Cisco CallManager plugin pages. Auto Update is applicable
only from JTAPI Release 2.0 and beyond.
Refer to the Cisco JTAPI Installation Guide for Cisco CallManager 4.0 for more
information.
The following are new or changed interfaces for Auto Update of APIs:
Class com.cisco.services.updater.ComponentUpdater
Component queryLocalComponentVersion (java.lang.String

componentName, java.lang.String path)
Throws an IOException, IllegalArgumentException.
Component queryServerComponentVersion (java.lang.String

componentName, java.lang.String urlString)
Throws an IOException, IllegalArgumentException, and
sends an http query to the server to determine the remote
server installed components version.
Interface com.cisco.services.updater.Component

1-76 OL-7242-02
Chapter 1 Overview
Auto Update of API
int compareTo (Component otherComponent)
Component fetchFromServer()
Performs an http fetch of the component from the server
and writes to the local file system with the file name
temp.jar in the local directory.
java.lang.String getBuildDescription ()
Returns the string 'Release' for a version of the form
'a.b(c.d) Release'.
int getBuildNumber ()
Returns 'd' for a version of the form a.b(c.d).
java.lang.String getLocation ()
The string form location of the component.
int getMajorVersion ()
Returns 'a' version for a version of the form a.b(c.d).
int getMinorVersion ()
Returns 'b' version for a version of the form a.b(c.d).
java.lang.String getName ()
Returns the name of the component.
int getRevisionNumber ()
Returns 'c' for a version of the form a.b(c.d).

OL-7242-02 1-77
Chapter 1 Overview
CiscoTerminal Filter and ButtonPressedEvents
CiscoTerminal Filter and ButtonPressedEvents

Prior to the JTAPI 2.0 release, Cisco JTAPI applications did not have direct
control over Terminal events. Applications will be able to receive button pressed
events by setting the appropriate filter in the terminal observer. Applications no
longer need to add call observer to get RTP events.
When setButtonPressedEv gets enabled using CiscoTermEvFilter, applications
receive CiscoTermButtonPressedEv when a digit gets pressed on the phone.
The following are the new or changed interfaces for CiscoTerminal Filter and
ButtonPressedEvents:
CiscoTerminal
void setFilter (CiscoTermEvFilter terminalEvFilter)

Allows an application to have more control over the events
that get delivered to the TerminalObserver.
CiscoTermEvFilter
boolean getButtonPressedEnabled()
Gets the enable or disable status of the button pressed events for
the terminal. The default value is disabled.
boolean getDeviceDataEnabled()
Gets the enable or disable status of the device data events for the
terminal. The default value is disabled.
boolean getRTPEventsEnabled()
Gets the enable or disable status of the RTP events for the
terminal. The default value is disabled.
void setButtonPressedEnabled (boolean enabled)

Enables or Disables the button pressed events for the terminal.

1-78 OL-7242-02
Chapter 1 Overview
Modifying Calling Number
void setDeviceDataEnabled (boolean enabled)

Enables or Disables the device data status events for the terminal.
void setRTPEventsEnabled (boolean enabled)

Enables or Disables the RTP events for the terminal.
CiscoTermButtonPressedEv
int getButtonPressed ()

Implementation.” To view the message flow for CiscoTerminal Filter and
ButtonPressedEvents, see Appendix A, “Message Sequence Charts.”

This feature enables applications to modify the calling party DN in the select
route API from the route point. Applications may pass an array of modifying
calling numbers in the selectRoute API and an array length of modifying calling
numbers may be equal to the length of the route selected. If there is no modifying
calling number element present for a corresponding routeSelected index or if the
element is null, then no modifying calling number gets set for that route selected
element.
Two new interfaces getModifiedCallingAddress () and
getModifiedCalledAddress () are exposed on the call object, which returns
modified calling or called number. If there is no modification, these interfaces
may return the same values as getCurrentCallingAddress () and
getCurrentCalledAddress () interfaces. If an application is only controlling the
route point and modifies the calling number using selectRoute API, it may not get
modified calling address in the getModifiedCallingAddress interface. If an
application is controlling any of calling or called parties, it may get correct values
once it receives call control events after the calling number is modified.

OL-7242-02 1-79
Chapter 1 Overview
A new interface, getRouteSelectedIndex (), exposed on the new class

CiscoRouteUsedEvent, an extension of RouteUsedEvent, which gives the index
of the selected route. Applications need to cast the RouteUsedEvent to the
CiscoRouteUsedEvent in order to get access to this method.
Example
routeSelected[0] = 133555
modifiedCallingNumber[0] =null
modifiedCallingNumber[1] =9721234567
modifiedCallingNumber[2] =9721234568
modifiedCallingNumber[3] =null
If routeSelected[0] or routeSelected[3] is selected for routing, the modifying

calling number may not be applied.
This feature may only be used after an administrator enables the modifying
calling number check box in the Cisco CallManager Administration for a
particular user, which by default is False. If it is not configured, then
RerouteEvent with cause as
RouteSession.CAUSE_PARAMETER_NOT_SUPPORTED gets sent to the
applications. The application that is modifying the calling number needs to be
aware that display name on the called party is affected and subsequent feature
interactions of the calling or called party may result in inconsistent behavior.
The following are new or changed interfaces for Modifying Calling Number:
CiscoRouteSession
void selectRoute (java.lang.String[] routeSelected, int

callingSearchSpace, String[]
modifiedCallingNumber)
This interface allows applications to modify the calling
party number to the routeSelected address. If there is no
modifiedCallingNumber element for the corresponding
routeSelected element, the calling number is not modified
if a call gets routed to that particular routeSelected element.

1-80 OL-7242-02
Chapter 1 Overview
CiscoCall
javax.telephony.Address getModifiedCalledAddress ()
This interface returns a modified called
address for the call if an application modifies
the calling party using from selectRoute API.
However, this information may not be
accurate if an application is only controlling
the route point that modifies the calling
number. If no modified calling number gets
performed, this is similar to the
getCurrentCalledAddress interface. Typically,
this gets varied from
getCurrentCalledAddress when a feature gets
invoked after modified calling number
modifications.
javax.telephony.Address getModifiedCallingAddress ()
This interface returns a modified calling
address for the call if an application modifies
the calling party using from selectRoute API.
However, this information may not be
accurate if an application is only controlling
the route point that modifies the calling
number. If no modified calling number gets
performed, this is similar to the
getCurrentCallingAddress interface.
CiscoRouteUsedEvent
int getRouteSelectedIndex ()
This method returns an array index of the route to where the
call gets routed.

Implementation.” To view the message flow for Modifying Calling Number, see

OL-7242-02 1-81
Chapter 1 Overview
AutoAccept Support for CTIPort and RoutePoint
AutoAccept Support for CTIPort and RoutePoint

This feature provides applications the ability to enable or disable AutoAccept for
the addresses on CTIPorts and Route Points. When AutoAccept status the changes
for the address, Cisco JTAPI provides the event to inform the application for
changes.
Note The maximum number of lines supported for route points is 34.
The new interface setAutoAcceptStatus(), provided on the CiscoAddress object,

allows the capability to set AutoAccept to ON or OFF. Interface
getAutoAcceptStatus(), also provided on the CiscoAddress object, allows
applications to query the current status of AutoAccept on the Address.
When AutoAccept status changes for the Address, applications get
CiscoAddrAutoAcceptStatusChangedEv on AddressObservers. This event has
interface getTerminal(), which returns Terminal on which the AutoAccept status
gets changed and interface getAutoAcceptStatus() returns integers specifying
whether AutoAccept is ON or OFF. If Address observer is not added, the event
will not be provided.
The following interfaces are for AutoAccept on CTIPort and RoutePoint:
CiscoAddress
int getAutoAcceptStatus (javax.telephony.Terminal

terminal)
Ciscoaddress.getAutoAccept(Terminal iterminal) returns
an AutoAccept status of Address on Terminal.
void setAutoAcceptStatus (int autoAcceptStatus,

javax.telephony.Terminal terminal)
This allows an application to enable AutoAccept for
Addresses on the CiscoMediaTerminal and or the
CiscoRouteTerminal.
CiscoAddrAutoAcceptStatusChangedEv
Public interface: CiscoAddrAutoAcceptStatusChangedEv

1-82 OL-7242-02
Chapter 1 Overview
CiscoTermRegistrationFailed Event
Extends com.cisco.jtapi.exension.CiscoAddrEv
The CiscoAddrAutoAcceptStatusChangedEv event gets sent to applications
whenever AutoAccept status for the address on the terminal gets changed. if an
address has multiple terminals, this event gets sent for the address AutoAccept
status on each individual terminals. This event provides the following interface:
int getAutoAcceptStatus ()
CiscoAddrAutoAcceptStatusChang
edEv.getAutoAcceptStatus returns
the following value of AutoAccept
status of address on terminal
CiscoAddress.AUTOACCEPT_OFF
CiscoAddress.AUTOACCEPT_ON.
com.cisco.jtapi.extensions.CiscoTerminal getTerminal ()
Returns the terminal at which this
address AutoAccept status gets
changed.

Implementation.” To view the message flow for AutoAccept on CTIPort and
RoutePoint, see Appendix A, “Message Sequence Charts.”
This event gets provided to the application when CiscoMediaTerminal or
CiscoRouteTerminal registration fails asynchronously. Usually when registration
fails, the application gets CiscoRegistrationFailedException. However, it is
possible that the registration request is successful, but the registration gets
rejected by the CTI. This event is provided for the cases where the Registration
request is successful, but the Registration gets rejected. The application should
have TerminalObserver to receive this event. Upon receipt of this event, the
applications should re-register with the new parameter depending on the error
code provided for this event.

OL-7242-02 1-83
Chapter 1 Overview
The following are the errors that get returned and the actions to take, by the
application, to resolve them.
Error Message CiscoTermRegistrationFailedEv.MEDIA_CAPABILITY_MISM

ATCH
Explanation Registration can not get done because the terminal is already
registered. Do the second registration with the same media capability.
Recommended Action Try re-registering with the same capability.
Error Message CiscoTermRegistrationFailedEv.MEDIA_ALREADY_TERMINA

TED_NONE
registered with Media termination type 'none'.
Recommended Action Try re-registering with Media termination type 'none'.

TED_STATIC
registered with Static media termination. For static registration, the second
registration is not allowed.
Recommended Action Wait until the terminal UnRegisters.

TED_DYNAMIC
registered with Dynamic media termination.
Recommended Action Try re-registering with Dynamic Media termination.

1-84 OL-7242-02
Chapter 1 Overview
SelectRoute Interface Enhancement
Error Message CiscoTermRegistrationFailedEv.OWNER_NOT_ALIVE
Explanation When trying to register the terminal, registration gets in a race

condition.
Recommended Action Try re-registering the terminal.
The following interface is defined for this event:
int getErrorCode ()
Returns the errorCode for this exception.

Implementation.”
There are no changes in the message flow.

The SelectRoute interface gets enhanced to take the parameters
“PreferedOriginalCalledNumber” and “PreferedOriginalCalledOption”. This
enables applications to reset the OriginalCalled value to a specified
“PreferedOriginalCalledNumber” when the call gets routed. This interface takes
a list of “PreferedOriginalCalledNumber”, “PreferedOriginalCalledOption”, and
corresponds them to the “RouteSelected” list. If the Call gets routed to Route at
index “I” in the RouteSelected list, the PreferedOriginalCalledNumber and
PreferedOriginalCalledOption at index “I” get used. Applications get the
following behavior with different values for these parameters.
Note Below x, point to the index where the Call is being Routed. For example, if the
call gets routed to Route n, then value of x will be n. If a
PreferedOriginalCalledOption at index x is invalid or out of range, JTAPI defaults
it to CiscoRouteSession.DONOT_RESET_ORIGINALCALLED. And if
PreferedOriginalCalledOption is null, all the Routing gets done with option
CiscoRouteSession.DONOT_RESET_ORIGINALCALLED.

OL-7242-02 1-85
Chapter 1 Overview
When PreferedOriginalCalledOption[x] is set to

CiscoRouteSession.RESET_ORIGINALCALLED
• If RouteSelected list contains Routes R1, R2 .. Rn, and
preferedOriginalCalled list contains O1, O2, … On. If R1 is available, then
Call will be routed to R1 and OriginalCalledNumber will be set to O1; if R1
is busy and R2 is available, then Call will be routed to R2 and
OriginalCalledNumber will be set to O2 … and so on.
preferedOriginalCalled list contains O1, O2, … Om. And m < n, If R1 is
available, then Call will be routed to R1 and preferedOriginalCalled will be
set to O1; if R1 is busy and R2 is available, then Call will be routed to R2 and
OriginalCalledNumber will be set to O2 and so on until m. And from Route
m+1, if Rm+1 is available, then Call will be routed to Rm+1 and
OriginalCalledNumber will be set to Rm+1, and so on. Lastly, if Rn is
available, the Call gets routed to Rn and OriginalCalledNumber gets set to Rn
".
preferedOriginalCalled list is NULL, then if R1 is available, then Call will be
routed to R1 and OriginalCalledNumber will be set to R1; if R1 is busy and
R2 is available, then Call will be routed to R2 and OriginalCalledNumber will
be set to R2 … and so on.
When PreferedOriginalCalledOption[x] is set to

CiscoRouteSession.DONOT_RESET_ORIGINALCALLED
preferedOriginalCalled list contains O1, O2,.. On, then Call will be routed to
one of the available Route and OriginalCalledNumber will remain
unchanged.
preferedOriginalCalled list contains O1, O2, … Om. And m < n, then Call
will be routed to one of the available Route and OriginalCalledNumber will
remain unchanged.
preferedOriginalCalled list is NULL, then Call will be routed to one of the
available Route and OriginalCalledNumber will remain unchanged.

1-86 OL-7242-02
Chapter 1 Overview
Note When OriginalCalled gets set to PreferedOriginalCalled, LastRedirectingParty

number also gets reset to PreferedOriginalCalled.
The following are new or changed interfaces for SelectRoute Interface

Enhancement:
int selectRoute (java.lang.String[] routeSelected, int

callingSearchSpace, java.lang.String[]
preferedOriginalCalledNumber, int[]
preferedOriginalCalledOption)
Selects one or more possible destinations for routing a call.
PreferedOriginalCalledOption takes one of the following values:
static int DONOT REESET_ORIGINALCALLED

Optional parameter value for
PreferedOriginalCalledOption that specifies not to reset
OriginalCalled.
static int REESET_ORIGINALCALLED

Optional parameter value for
PreferedOriginalCalledOption that resets OriginalCalled to
preferedOriginalCalledNumber.

Implementation.” To view the message flow for SelectRoute Interface
Enhancement, see Appendix A, “Message Sequence Charts.”

OL-7242-02 1-87
Chapter 1 Overview
Presentation Indicator (PI) for the Call

Presentation indicator on call provides Application with the ability to hide or
reveal Calling/Called/CurrentCalling/CurrentCalled/LastRedirecting parties
name and number to the end user. JTAPI provides get functions on CiscoCall to
get PI value for the party. Use this PI info to present the parties information to the
end user. These get functions return a value of true or false. A value of “True”
indicates that presentation in “Allowed” and a value of “False” indicates the
presentation is “Restricted”.
For a Conference Call, the interfaces on CiscoCall do not return a correct value.
Applications have to iterate through all the Connections in the call to get the PI
value associated with the address for which the connection gets created. The
interface provided on CiscoConnection is getAddressPI().
The following are new interfaces provided on CiscoCall to get PI values:
CiscoCall
boolean getCalledAddressPI()
Returns the PI associated with getCalledAddressPI. If it returns
true, the application displays the address name. If it returns false,
the application must not display the address name.
boolean getCallingAddressPI()
Returns the PI associated with getCallingAddressPI. If it returns
true, the application displays the address name. If it returns false,
the application must not display the address name.
boolean getCurrentCalledAddressPI()
Returns the PI associated with CurrentCalledAddressPI. If it
returns true, the application displays the address name. If it
returns false, the application must not display the address name.
boolean getCurrentCalledDisplayNamePI()
Returns the PI associated with CurrentCalledDisplayNamePI. If it

1-88 OL-7242-02
Chapter 1 Overview
boolean getCurrentCallingAddressPI()
Returns the PI associated with getCurrentCallingAddressPI. If it
boolean getCurrentCallingDisplayNamePI()
Returns the PI associated with getCurrentCallingDisplayNamePI.
If it returns true, the application displays the address name. If it
boolean getLastRedirectingAddressPI()
Returns the PI associated with getLastRedirectingAddressPI. If it
The following interface gets provided on CiscoConnection to get the PI value for
the address associated with the Connection:
CiscoConnection
boolean getAddressPI()
Returns the PI associated with the address on which the
connection gets created. If it returns true, the application
displays the address name. If it returns false, the application
must not display the address name.

Implementation.”
There is no change in the message flow.

OL-7242-02 1-89
Chapter 1 Overview
Progress State Converted to Disconnect State
Progress State Converted to Disconnect State

If an outbound call is initiated through the API to an unallocated directory number
across the European PSTN, the application will see the ConnFailedEv event with
the cause as CiscoCallEv.CAUSE_UNALLOCATEDNUMBER. For the US
PSTN, on the other hand, the application may not see any event.
In order to make the behavior consistent across the European and American
PSTNs and also to address backward compatability issues, a new service
parameter UseProgressAsDisconnectedDuringErrorEnabled is added in the
jtapi.ini file from JTAPI Version 1.4(3.21), which, when enabled ( 1=enable,
0=disable, default is disable), will cause applications to see ConnFailedEv in both
the cases
Device State Server

Device State Server provides the cumulative state of all the addresses on a
terminal. These events are delivered as TerminalEvent. Applications need to add
TerminalObserver to get these events.
States are defined as follows
• IDLE—If there are no calls on any of the addresses on the terminal, then the
DeviceState is considered IDLE, and Cisco JTAPI sends
CiscoTermDeviceStateIdleEv toapplications.
• ACTIVE—If any of the addresses on the terminal have an outgoing call (in
CTI State Dialtone, Dialing, Proceeding, Ringback, or Connected) or an
incoming call (in CTI State Connected), then the DeviceState is ACTIVE and
Cisco JTAPI sends CiscoTermDeviceStateActiveEv to the
application.
• ALERTING—If none of the addresses on the terminal have an outgoing call
(in CTI State Dialtone, Dialing, Proceeding, Ringback, or Connected) or an
incoming call (in CTI State Connected) and at least one of the addresses on
the terminal has an unanswered incoming call (in CTI State Offering,
Accepted, or Tinging), then the DeviceState is ALERTING and Cisco JTAPI
sends CiscoTermDeviceStateAlertingEv to the application.

1-90 OL-7242-02
Chapter 1 Overview
Device State Server
• HELD—If all the calls on any of the address on the terminal are held (in CTI
State OnHold) the DeviceState is HELD and Cisco JTAPI sends
CiscoTermDeviceStateHeldEv to the application.
New Events
• CiscoTermDeviceDeviceStateIdleEv
• CiscoTermDeviceStateActiveEv
• CiscoTermDeviceStateAlertingEv
• CiscoTermDeviceStateHeldEv
New and Changed Interfaces

public int getDeviceState()
Returns the device state of the terminal.
The following new interfaces are provided on CiscoTermEvFilter to set and get
the device state.
void setDevideStateActiveEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceStateActiveEv filter.
The default value is disable.
void setDeviceStateAlertingEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceAlertingEv filter. The
default value is disable.
void setDeviceStateHeldEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceHeldEv filter. The
void setDeviceStateIdleEvFilter(boolean filterValue)

Enables and disables the CiscoTermDeviceIdleEv filter. The
boolean getDeviceStateActiveEvFilter()
Gets the CiscoTermDeviceStateActiveEv filter status.

OL-7242-02 1-91
Chapter 1 Overview
Forced Authorization and Client Matter Codes
boolean getDeviceStateAlertingEvFilter()
Gets the CiscoTermDeviceStateAlertingEv filter status.

Implementation.”
Forced Authorization Code (FAC)

Force the user to enter a valid authorization code prior to extending calls to
specified classes of dialed numbers (DN), such as external, toll, or international
calls. Authorization information is written to the Cisco CallManager CDR
database.
Client Matter Code (CMC)

Allow the user to enter a code before extending a call. Customers can use Client
Matter Codes for assigning accounting or billing codes to calls placed, and Client
Matter Code information is written to the Cisco_CallManager CDR database.
Supported Interfaces
Cisco JTAPI supports FAC and CMC in the following interfaces:

1-92 OL-7242-02
Chapter 1 Overview
• Call.Connect()
• Call.Consult()
• Call.Transfer(String)
• Connection.redirect()
• RouteSession.selectRoute()
Call.Connect() and Call.Consult()

When an application initiates a call with one of these interfaces to a DN that
requires an FAC, CMC, or both codes, CiscoToneChangedEv is delivered on a
CallObserver that also contains which code or codes are required for the DN. The
getCiscoCause() interface returns CiscoCallEV.CAUSE_FAC_CMC for this even
if it is delivered because of FAC_CMC feature. The getTone() interface returns
CiscoTone.ZIPZIP to indicate that ZIPZIP tone has been played.
Upon receiving the CiscoToneChangedEv, applications need to enter the
appropriate code or codes using the connection.addToAddress interface with a #
terminating string. Digits can either be entered one at a time within the inter-digit
timer value (T302 timer) for each digit including the # terminating character, or
all the digits, including the # termination character, can be entered within the
T302 timer value configured in Cisco CallManager Administration.
When FAC and CMC Are Both Required

For a DN that requires both codes, the first event is always for FAC and the second
code if for CMC, but the application has the option to send both codes, separated
by an octothorpe (#), in the same request. The second event is optional, based on
what the application sends in the first request.
The application can send both codes at the same time, but both codes must end
with #. as shown in the following example:
connection.addToAddress(“1234#678#”)
where 1234 is the FAC and 678 is the CMC.
In this case the application does not receive a second CiscoToneChanged.
The first CiscoToneChangesEv will have
getWhichCodeRequired()=CiscoToneChanged.FAC_CMC_REQUIRED, and
getCause()=CiscoCallEv.CAUSE_FAC_CMC. In response, one of the following
cases can occur.

OL-7242-02 1-93
Chapter 1 Overview
• The application sends FAC and CMC in the same

connection.addToAddres(code1#code2#) request. In this case, there is no
second CiscoToneChangedEv sent to the application.
• The application sends only a FAC code in connection.addToAddress(code#1).
In this case, the application receives a second CiscoToneChangedEv with
getWhichCodeRequired()=CiscoToneChangedEv.CMC_REQUIRED.
• The application sends only part of the first code or the complete first code and
incomplete second code (if the code is not terminated with #, then it is
incomplete and the system waits for the T302 timer to expire and tries to
validate the code). If the code is incomplete, a second CiscoToneChangedEv
tone is generated with
getWhichCodeRequired()=CiscoToneChangedEv.CMC_REQUIRED and
getCause()=CiscoCallEv.CAUSE_FAC_CMC.
PostCondition Timer
The PostCondition timer is reset each time the connection.addToAddress
interface is invoked to send code. FAC and CMC must have the terminal # (for
example, Connection.assToAddress(“1234#”), where 1234 is the FAC). The
system waits for the T302 timer to expire and then extends the call if all codes
have been entered. If all codes have not been entered, the system plays reorder
tone.
For this case, the application could receive PlatformException with
postConditionTimeout even if the call is extended. To avoid this, the application
needs to increase the postcondition timeout using JTAPI Preferences.
If the application uses call.connect() or call.consult() to initiate a call but the FAC
or CMC (including #) is not entered from a Cisco IP phone within the
postcondition timeout limit, then the request could get a platformException with
postCondition timeout but the call may actually be extended. To avoid this, the
application needs to increase the postcondition timeout using JTAPI preferences.
Shared Lines
If the initiating party is a shared line, then applications need to use
setRequestController to set active terminalConnection before passing additional
digits using the connection.addToAddress interface.
Invalid or Missing Codes

If a code is invalid or no code is entered before the T302 timer expires, the call is
rejected with callCtlCause cause code as CiscoCallEv.CAUSE_FAC-CMC.

1-94 OL-7242-02
Chapter 1 Overview
Super Provider (Disable Device Validation)
Call.transfer(String) and Connection.redirect()

Two additional string parameters (facCode, cmcCode) are added to these
interfaces to support FAC and CMC. The default value for these codes are null
values.
These is no CiscoToneChangedEv delivered for these requests for DNs that
require codes. A call conditionally redirected to a DN an FAC, a CMC, or both, is
not rejected but remains connected if either of the codes is incorrect.
RouteSession.selectRoute()
Two additional arrays of string parameters (facCode, cmcCode) are added to this
interface to support FAC and CMC. For each routeselect element, applications can
specify the code for the DN. Applications need to specify null values for DNs that
do not require any codes. The default values for the codes are null values.
If one routeselected element does not contain the correct code, then the next
element in the arrays tried. If all of them fail, then reRouteEvent is sent to the
application.
Note Forwarding to a DN that requires an FAC or CMC code is not supported. The
application can set the forward number to these DNs using Address API, but calls
forwarded to these numbers are rejected.
Super Provider (Disable Device Validation)

When a JTAPI application user is configured, the system administrator normally
associates a certain set of terminals (Cisco IP phones and devices) with this
application user, who can control and monitor only this set of terminals. The
Super Provider feature gives applications the ability to control and monitor any
terminal in a Cisco CallManager cluster.
A new interface in CiscoProvider, createTerminal(), enables the application to
create a terminal by specifying terminalName. JTAPI does not provide the
capability to get terminalName through any interface. The
CiscoProvider.createTerminal(terminalName) returns Terminal. If Terminal
already exists in the provider domain, JTAPI returns the existing Terminal.

OL-7242-02 1-95
Chapter 1 Overview
Q.Signaling (QSIG) Path Replacement
A second new interface, CiscoProvider.deleteTerminal() enables the application

to delete the CiscoTerminal objects created using the
CiscoProvider.createTerminal() interface. If Terminal object doesn’t exist or
Terminal was not created Application using the CiscoProvider.createTerminal()
interface, then JTAPI throws exceptions.
JTAPI also provides a new interface on CiscoProviderCapabilities,
canObserveAnyTerminal(), which can be enabled for Application users through
Cisco CallManager Administration user configuration. Applications can use this
interface to determine if they have sufficient capability to invoke the
creatTerminal(terminalName) interface. If the application doesn’t have sufficient
capability and this interface is invoked, JTAPI throws the
PrivilegeViolationException exception. If the application provides a
terminalName that doesn’t exist in the Cisco CallManager cluster, the JTAPI
throws the InvalidArgumentException exception.
Q.Signaling (QSIG) Path Replacement

QSIG Path Replacement is a network feature that optimizes the real-time protocol
(RTP) path when calls are transferred or forwarded to other PBXs connected
through QSIG trunks. When path replacement is in progress there is a small
window of time when the feature requests from applications would be ignored and
JTAPI would throw an exception to the application.
The Global Call ID or the call is changed when the RTP path is optimized with a
direct path between the starting terminating PBXs. JTAPI provides new interfaces
to monitor the call.
Network Events
In prior releases of Cisco JTAPI, when a call is made to an address outside the
cluster, CallCtlConnNetworkReachedEv and CallCtlConnNetworkAlertingEv
events are delivered for the far-end address.
In later versions of Cisco CallManager (4.0 and above), these events are not
delivered. In these versions CallCtlConnection for the far-end address goes to the
ESTABLISHED state from OFFERED state. The application will receive
CallCtlConnOfferedEv, CallCtlConnEstablishedEv for the far-end address. The

1-96 OL-7242-02
Chapter 1 Overview
Network Events
CallCtlConnNetworkReachedEv and CallCtlConnNetworkAlertingEv events are

not delivered to application. To receive network events, the “Allow overlap
sending” flag on the route pattern configured for the gateway must be turned on.
A new jtapi.ini parameter called “AllowNetworkEventsAfterOffered” is
introduced to allow the application control the delivery of these events.
Applications that need the network events but cannot turn on this flag can use this
new ini parameter to receive network events for outgoing calls.
To turn on the parameter:
Step 1 Run jtprefs and select the required options. This creates jtapi.ini file in
c:\winnt\java\lib, if Cisco JTAPI is installed in the default directory. If the jtapi.ini
file already exists, then the file can be updated directly without running jtprefs.
Step 2 Add AllowNetworkEventsAfterOffered=1 to the end of the file and save it.
Step 3 Repeat the above step every time Cisco JTAPI is reinstalled.
When the AllowNetworkEventsAfterOffered flag is enabled, the application will
receive CallCtlConnOfferedEv, CallCtlConnNetworkReachedEv or
CallCtlConnNetworkAlertingEv, and CallCtlConnEstablishedEv for the far end
address.

OL-7242-02 1-97
Chapter 1 Overview
Network Events

1-98 OL-7242-02
C H A P T E R 2
Cisco JTAPI Implementation
Cisco JTAPI Implementation describes interfaces and classes available. To create

new applications, use these interfaces and classes with the standard JTAPI
interfaces and classes described in the Cisco JTAPI v 1.2.
This chapter contains the following sections:
• Cisco JTAPI Extensions Hierarchy
• Class com.cisco.jtapi.extensions
• Class com.cisco.services.alarm
• Class com.cisco.services.tracing
Cisco JTAPI Extensions Hierarchy
Class Hierarchy
class java.lang.Object
class com.cisco.services.alarm.AlarmManager
class com.cisco.services.tracing.BaseTraceWriter (implements
com.cisco.services.tracing.TraceWriter)
class com.cisco.services.tracing.ConsoleTraceWriter

OL-7242-02 2-1
Chapter 2 Cisco JTAPI Implementation
class com.cisco.services.tracing.LogFileTraceWriter
class com.cisco.services.tracing.OutputStreamTraceWriter
class com.cisco.services.tracing.SyslogTraceWriter
class com.cisco.jtapi.extensions.CiscoAddressCallInfo
class com.cisco.jtapi.extensions.CiscoJtapiVersion
class com.cisco.jtapi.extensions.CiscoMediaCapability
class com.cisco.jtapi.extensions.CiscoG711MediaCapability
class com.cisco.jtapi.extensions.CiscoGSMMediaCapability
class com.cisco.jtapi.extensions.CiscoRTPParams
class com.cisco.services.alarm.DefaultAlarm (implements
com.cisco.services.alarm.Alarm)
class com.cisco.services.alarm.DefaultAlarmWriter (implements
com.cisco.services.alarm.AlarmWriter)
class com.cisco.services.alarm.ParameterList
class java.lang.Throwable (implements java.io.Serializable)
class java.lang.Exception
class com.cisco.jtapi.extensions.CiscoRegistrationException
class com.cisco.jtapi.extensions.CiscoUnregistrationException
class com.cisco.services.tracing.TraceManagerFactory
Interface Hierarchy
interface javax.telephony.Address
interface com.cisco.jtapi.extensions.CiscoAddress (also extends
com.cisco.jtapi.extensions.CiscoObjectContainer)
interface javax.telephony.callcenter.RouteAddress
interface com.cisco.jtapi.extensions.CiscoRouteAddress
interface javax.telephony.AddressObserver

2-2 OL-7242-02
interface com.cisco.jtapi.extensions.CiscoAddressObserver
interface com.cisco.services.alarm.Alarm
interface com.cisco.services.alarm.AlarmWriter
interface javax.telephony.Call
interface javax.telephony.callcontrol.CallControlCall
interface com.cisco.jtapi.extensions.CiscoCall (also extends
interface com.cisco.jtapi.extensions.CiscoConsultCall
interface com.cisco.jtapi.extensions.CiscoJtapiException
interface com.cisco.jtapi.extensions.CiscoJtapiProperties
interface com.cisco.jtapi.extensions.CiscoObjectContainer
interface com.cisco.jtapi.extensions.CiscoAddress (also extends
javax.telephony.Address)
interface com.cisco.jtapi.extensions.CiscoCall (also extends
javax.telephony.callcontrol.CallControlCall)
interface com.cisco.jtapi.extensions.CiscoConsultCall
interface com.cisco.jtapi.extensions.CiscoCallID
interface com.cisco.jtapi.extensions.CiscoConnection (also extends
javax.telephony.callcontrol.CallControlConnection)
interface com.cisco.jtapi.extensions.CiscoConnectionID
interface com.cisco.jtapi.extensions.CiscoJtapiPeer (also extends
javax.telephony.JtapiPeer, com.cisco.services.tracing.TraceModule)
interface com.cisco.jtapi.extensions.CiscoProvider (also extends
javax.telephony.Provider)
interface com.cisco.jtapi.extensions.CiscoTerminal (also extends
javax.telephony.Terminal)
interface com.cisco.jtapi.extensions.CiscoMediaTerminal
interface com.cisco.jtapi.extensions.CiscoTerminalConnection (also extends
javax.telephony.callcontrol.CallControlTerminalConnection)
interface com.cisco.jtapi.extensions.CiscoProvFeatureID
interface com.cisco.jtapi.extensions.CiscoRTPBitRate

OL-7242-02 2-3
interface com.cisco.jtapi.extensions.CiscoRTPInputProperties
interface com.cisco.jtapi.extensions.CiscoRTPOutputProperties
interface com.cisco.jtapi.extensions.CiscoRTPPayload
interface com.cisco.jtapi.extensions.CiscoSynchronousObserver
interface javax.telephony.Connection
interface javax.telephony.callcontrol.CallControlConnection
interface com.cisco.jtapi.extensions.CiscoConnection (also extends
interface javax.telephony.events.Ev
interface javax.telephony.events.AddrEv
interface com.cisco.jtapi.extensions.CiscoAddrEv (also extends
com.cisco.jtapi.extensions.CiscoEv)
interface com.cisco.jtapi.extensions.CiscoAddrInServiceEv
interface com.cisco.jtapi.extensions.CiscoAddrOutOfServiceEv
(also extends com.cisco.jtapi.extensions.CiscoOutOfServiceEv)
interface javax.telephony.events.CallEv
interface javax.telephony.events.CallActiveEv
interface com.cisco.jtapi.extensions.CiscoConsultCallActiveEv (also
extends com.cisco.jtapi.extensions.)
interface com.cisco.jtapi.extensions.CiscoCallEv (also extends
interface com.cisco.jtapi.extensions.CiscoConferenceEndEv
interface com.cisco.jtapi.extensions.CiscoConferenceStartEv
extends javax.telephony.events.CallActiveEv)
interface com.cisco.jtapi.extensions.CiscoTransferEndEv
interface com.cisco.jtapi.extensions.CiscoTransferStartEv
interface com.cisco.jtapi.extensions.CiscoEv
interface com.cisco.jtapi.extensions.CiscoAddrEv (also extends
javax.telephony.events.AddrEv)
interface com.cisco.jtapi.extensions.CiscoAddrInServiceEv

2-4 OL-7242-02
interface com.cisco.jtapi.extensions.CiscoCallEv (also extends
javax.telephony.events.CallEv)
interface com.cisco.jtapi.extensions.CiscoConferenceEndEv
interface com.cisco.jtapi.extensions.CiscoConferenceStartEv
extends javax.telephony.events.CallActiveEv)
interface com.cisco.jtapi.extensions.CiscoTransferEndEv
interface com.cisco.jtapi.extensions.CiscoTransferStartEv
interface com.cisco.jtapi.extensions.CiscoOutOfServiceEv
(also extends com.cisco.jtapi.extensions.CiscoAddrEv)
interface com.cisco.jtapi.extensions.CiscoTermOutOfServiceEv
(also extends com.cisco.jtapi.extensions.CiscoTermEv)
interface com.cisco.jtapi.extensions.CiscoProvEv (also extends
javax.telephony.events.ProvEv)
interface com.cisco.jtapi.extensions.CiscoAddrCreatedEv
interface com.cisco.jtapi.extensions.CiscoAddrRemovedEv
interface com.cisco.jtapi.extensions.CiscoProvFeatureEv
interface com.cisco.jtapi.extensions.CiscoProvCallParkEv
interface
com.cisco.jtapi.extensions.CiscoProvFeatureUnRegisteredEv
interface com.cisco.jtapi.extensions.CiscoTermCreatedEv
interface com.cisco.jtapi.extensions.CiscoTermRemovedEv
interface com.cisco.jtapi.extensions.CiscoTermEv (also extends
javax.telephony.events.TermEv)
interface com.cisco.jtapi.extensions.CiscoRTPInputStartedEv
interface com.cisco.jtapi.extensions.CiscoRTPInputStoppedEv
interface com.cisco.jtapi.extensions.CiscoRTPOutputStartedEv
interface com.cisco.jtapi.extensions.CiscoRTPOutputStoppedEv

OL-7242-02 2-5
interface com.cisco.jtapi.extensions.CiscoTermDataEv
interface com.cisco.jtapi.extensions.CiscoTermInServiceEv
interface javax.telephony.events.ProvEv
interface com.cisco.jtapi.extensions.CiscoProvEv (also extends
interface com.cisco.jtapi.extensions.CiscoAddrCreatedEv
interface com.cisco.jtapi.extensions.CiscoAddrRemovedEv
interface com.cisco.jtapi.extensions.CiscoProvFeatureEv
interface com.cisco.jtapi.extensions.CiscoProvCallParkEv
interface
com.cisco.jtapi.extensions.CiscoProvFeatureUnRegisteredEv
interface com.cisco.jtapi.extensions.CiscoTermCreatedEv
interface com.cisco.jtapi.extensions.CiscoTermRemovedEv
interface javax.telephony.events.TermEv
interface com.cisco.jtapi.extensions.CiscoTermEv (also extends
interface com.cisco.jtapi.extensions.CiscoRTPInputStartedEv
interface com.cisco.jtapi.extensions.CiscoRTPInputStoppedEv
interface com.cisco.jtapi.extensions.CiscoRTPOutputStartedEv
interface com.cisco.jtapi.extensions.CiscoRTPOutputStoppedEv
interface com.cisco.jtapi.extensions.CiscoTermDataEv
interface com.cisco.jtapi.extensions.CiscoTermInServiceEv
interface javax.telephony.JtapiPeer
com.cisco.jtapi.extensions.CiscoObjectContainer,
com.cisco.services.tracing.TraceModule)
interface javax.telephony.Provider

2-6 OL-7242-02
interface com.cisco.jtapi.extensions.CiscoProvider (also extends

interface javax.telephony.capabilities.ProviderCapabilities
interface com.cisco.jtapi.extensions.CiscoProviderCapabilities
interface javax.telephony.ProviderObserver
interface com.cisco.jtapi.extensions.CiscoProviderObserver
interface javax.telephony.callcenter.RouteSession
interface com.cisco.jtapi.extensions.
interface javax.telephony.Terminal
interface com.cisco.jtapi.extensions.CiscoTerminal (also extends
interface com.cisco.jtapi.extensions.CiscoMediaTerminal
interface javax.telephony.TerminalConnection
interface javax.telephony.callcontrol.CallControlTerminalConnection
interface com.cisco.jtapi.extensions.CiscoTerminalConnection (also
extends com.cisco.jtapi.extensions.CiscoObjectContainer)
interface javax.telephony.TerminalObserver
interface com.cisco.jtapi.extensions.CiscoTerminalObserver
interface com.cisco.services.tracing.Trace
interface com.cisco.services.tracing.ConditionalTrace
interface com.cisco.services.tracing.UnconditionalTrace
interface com.cisco.services.tracing.TraceManager
interface com.cisco.services.tracing.TraceModule
com.cisco.jtapi.extensions.CiscoObjectContainer, javax.telephony.JtapiPeer)
interface com.cisco.services.tracing.TraceWriter
interface com.cisco.services.tracing.TraceWriterManager

OL-7242-02 2-7
Class com.cisco.jtapi.extensions
Class com.cisco.jtapi.extensions
The Cisco JTAPI extension consists of a set of classes and interfaces that expose
the functionality available in the Cisco IP Telephony. This API allows
programmers to create independent applications for Cisco CallManager. The
Cisco JTAPI implementation offers additional functionality not readily exposed
through the JTAPI 1.2 interfaces. Applications can use the interfaces and classes
in the com.cisco.jtapi.extensions package with the standard JTAPI interfaces and
classes described in the Cisco JTAPI v 1.2 Specification manual to create new
applications.
CiscoAddrAddedToTerminalEv
Declaration
public interface CiscoAddrAddedToTerminalEv extends CiscoProvEv
All Superinterfaces
CiscoEv, CiscoProvEv, javax.telephony.events.Ev,
javax.telephony.events.ProvEv
Description
The CiscoAddrAddedToTerminalEv event gets sent under the following
conditions:
• When User adds a Terminal/Device into the user controlList that contains
SharedDN, this event will be sent to application. If a user has an address in
control list, and we add new device with same address in control list, this
event will be sent.

2-8 OL-7242-02
CiscoAddrAddedToTerminalEv
• When EM(Extension mobility) user logs into a Terminal with a profile that
contains SharedDN, this event notifies that a new Terminal is added to an
already existing Address.
• A new SharedDN is added to a Device in a user control list. Interface
getTerminal() returns the terminal that gets added to Address. Interface
getAddress() will return the address on which the new terminal is added.
Member Summary
Fields
static int ID
Methods
javax.telephony.Address getAddress()
javax.telephony.Terminal getTerminal()
Inherited Member Summary

Fields inherited from interface Ev
CAUSE_CALL_CANCELLED, CAUSE_DEST_NOT_OBTAINABLE, CAUSE_INCOMPATIBLE_DESTINATION,
CAUSE_LOCKOUT, CAUSE_NETWORK_CONGESTION, CAUSE_NETWORK_NOT_OBTAINABLE, CAUSE_NEW_CALL,
CAUSE_NORMAL, CAUSE_RESOURCES_NOT_AVAILABLE, CAUSE_SNAPSHOT, CAUSE_UNKNOWN,
META_CALL_ADDITIONAL_PARTY, META_CALL_ENDING, META_CALL_MERGING, META_CALL_PROGRESS,
META_CALL_REMOVING_PARTY, META_CALL_STARTING, META_CALL_TRANSFERRING, META_SNAPSHOT,
META_UNKNOWN
Methods inherited from interface Ev
getCause(), getID(), getMetaCode(), getObserved(), isNewMetaEvent()
Methods inherited from interface ProvEv
getProvider()
Fields
ID
public static final int ID

OL-7242-02 2-9
Methods
getAddress()
public javax.telephony.Address getAddress()
getTerminal()
public javax.telephony.Address getTerminal()
Declaration
public interface CiscoAddrAutoAcceptStatusChangedEv extends
CiscoAddrEv
All Superinterfaces
javax.telephony.events.AddrEv, CiscoAddrEv, CiscoEv,
javax.telephony.events.Ev
Description
The CiscoAddrAutoAcceptStatusChangedEv event is send to
Applications whenever AutoAccept status for the Address on the Terminal is
changed. If an Address has multiple Terminals, then this event will be sent for
Address’s AutoAccept status on each individual Terminals.

2-10 OL-7242-02
Member Summary
Fields
static int ID
Methods
int getAutoAcceptStatus()
CiscoAddrAutoAcceptStatusChangedEv.getAutoAcceptStatus() returns
following value of AutoAccept status of Address on Terminal
CiscoAddress.AUTOACCEPT_OFF CiscoAddress.AUTOACCEPT_ON
CiscoTerminal getTerminal()
Returns the terminal at which this address is going
InService.

META_UNKNOWN
Methods inherited from interface AddrEv

getAddress()

Fields
ID

OL-7242-02 2-11
CiscoAddrCreatedEv
Methods
getAutoAcceptStatus()
public int getAutoAcceptStatus()
CiscoAddrAutoAcceptStatusChangedEv.getAutoAcceptStatus() returns
following value of AutoAccept status of Address on Terminal
CiscoAddress.AUTOACCEPT_OFF CiscoAddress.AUTOACCEPT_ON
See Also:
CiscoAddress.getAutoAcceptStatus()
getTerminal()
public com.cisco.jtapi.extensions.CiscoTerminal getTerminal()
Returns the terminal at which this address is going InService

In Shared Lines, applications may receive multiple CiscoAddressInService
events and the same Address appears on different Terminals. In order for
Application to find out which Shared Line is going in service, Applications
can use this interface. This interface returns the terminal on which Address is
going in Service.
Returns:
the terminal at which this address is going InService
CiscoAddrCreatedEv
Declaration
public interface CiscoAddrCreatedEv extends CiscoProvEv
All Superinterfaces
CiscoEv,CiscoProvEv, javax.telephony.events.Ev,

2-12 OL-7242-02
CiscoAddrCreatedEv
Description
The CiscoAddrCreatedEv event
Member Summary
Fields
static int ID
Methods

META_UNKNOWN
getProvider()
Fields
ID
Methods
getAddress()

OL-7242-02 2-13
CiscoAddress
CiscoAddress
Declaration
public interface CiscoAddress extends javax.telephony.Address,
All Superinterfaces
javax.telephony.Address, CiscoObjectContainer
Description
The CiscoAddress interface extends the Address interface with additional
CallManager-specific capabilities.
See Also
javax.telephony.Address
Member Summary
Fields
static int AUTOACCEPT_OFF
AutoAccept is off.
static int AUTOACCEPT_ON
AutoAccept is on.
static int EXTERNAL
This is an external address with a valid name.
static int EXTERNAL_UNKNOWN
This is an external address with an unknown name.
static int IN_SERVICE
The address is out-of-service
static int INTERNAL
This is an internal address.
static int OUT_OF_SERVICE
The address is in-service

2-14 OL-7242-02
CiscoAddress
Member Summary
static int RINGER_DEFAULT
Sets the ringer status to configured value
static int RINGER_DISABLE
Disables the ringer for the address
static int RINGER_ENABLE
Enables the ringer for the address
static int UNKNOWN
This is an external address with an unknown name.
Methods
void clearCallConnections()
Use this interface to clear off any phantom calls on the
address
CiscoAddressCallInfo getAddressCallInfo(Terminal)
Use this Interface to get info of calls present at the
terminal
int getAutoAcceptStatus(Terminal)
Returns the AutoAccept status of the Address on the
terminal
javax.telephony.Terminal getInServiceAddrTerminals()
Returns an array of terminals for which this address is
InService.
int getRegistrationState()
Returns the state of this address.
int getState()
int getType()
Returns the type of this address.
void setAutoAcceptStatus(int, Terminal)
Allows the application to enable AutoAccept for addresses
on CiscoMediaTerminal and/or CiscoRouteTerminal.
void setMessageWaiting(java.lang.String destination, boolean
enable)
Specifies whether the message-waiting indicator should be
activated or deactivated for the Address specified by the
destination.
void setRingerStatus(int)
changes the ringer status on this address

OL-7242-02 2-15
CiscoAddress

Methods inherited from interface Address
addCallObserver(CallObserver), addObserver(AddressObserver),
getAddressCapabilities(Terminal), getCallObservers(), getCapabilities(),
getConnections(), getName(), getObservers(), getProvider(), getTerminals(),
removeCallObserver(CallObserver), removeObserver(AddressObserver)
Methods inherited from interface CiscoObjectContainer

getObject(), setObject(Object)
Fields
AUTOACCEPT_OFF
public static final int AUTOACCEPT_OFF
AutoAccept is off.
AUTOACCEPT_ON
public static final int AUTOACCEPT_ON
AutoAccept is on.
EXTERNAL
public static final int EXTERNAL
This is an external address with a valid name. An address of this type is

created when ANI or callerID is available on the call.
EXTERNAL_UNKNOWN
public static final int EXTERNAL_UNKNOWN
This is an external address with an unknown name. An address of this type is

created to represent an endpoint for which there is insufficient information.

2-16 OL-7242-02
CiscoAddress
IN_SERVICE
public static final int IN_SERVICE
The address is out-of-service
INTERNAL
public static final int INTERNAL
This is an internal address.
OUT_OF_SERVICE
public static final int OUT_OF_SERVICE
The address is in-service
RINGER_DEFAULT
public static final int RINGER_DEFAULT
Sets the ringer status to configured value
RINGER_DISABLE
public static final int RINGER_DISABLE
Disables the ringer for the address
RINGER_ENABLE
public static final int RINGER_ENABLE
Enables the ringer for the address
UNKNOWN
public static final int UNKNOWN
This is an external address with an unknown name. An address of this type is

created to represent an endpoint for which there is insufficient information.

OL-7242-02 2-17
CiscoAddress
Methods
clearCallConnections()
public void clearCallConnections()
throws PrivilegeViolationException
Use this interface to clear off any phantom calls on the address
Throws:
getAddressCallInfo(Terminal)
public com.cisco.jtapi.extensions.CiscoAddressCallInfo
getAddressCallInfo(javax.telephony.Terminal iterminal)
Use this Interface to get info of calls present at the terminal
getAutoAcceptStatus(Terminal)
public void getAutoAcceptStatus(javax.telephony.Terminal terminal)
throws PlatformException, InvalidStateException, MethodNotSuppo
rtedException,
CiscoAddress.getAutoAccept(Terminal iterminal) returns AutoAccept status

of Address on Terminal. It may return one of the following constants:
CiscoAddress.AUTOACCEPT_OFF CiscoAddress.AUTOACCEPT_ON.
Pre-conditions:
1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. (getState() == IN_SERVICE
Post-conditions:
Parameters:
terminal - Terminal on which AutoAccept status of
Address will be returned.

2-18 OL-7242-02
CiscoAddress
Throws:
javax.telephony.InvalidStateException - The Provider is
not “in service”.
javax.telephony.PlatformException - Terminal is not on the
Address.
javax.telephony.MethodNotSupportedException - This
method is not supported ExtraProviderAddresses.
getInServiceAddrTerminals()
public javax.telephony.Terminal[] getInServiceAddrTerminals()
Use this interface to find out which Shared Lines are in service. In Shared
Lines, the same address appears on different Terminals.
Returns:
an array of terminals on which address is in service
getRegistrationState()
public int getRegistrationState()
Deprecated
This method has been replaced by the getState() method.
The state may be any of the following constants:
• CiscoAddress.OUT_OF_SERVICE
• CiscoAddress.IN_SERVICE
Returns:
the state of this address
getState()
public int getState()

OL-7242-02 2-19
CiscoAddress

• CiscoAddress.OUT_OF_SERVICE
• CiscoAddress.IN_SERVICE
Returns:
the state of this address
getType()
public int getType()
Returns the type of this address.

The type may be any of the following constants:
• CiscoAddress.INTERNAL
• CiscoAddress.EXTERNAL
• CiscoAddress.EXTERNAL_UNKNOWN
Returns:
the type of address
setAutoAcceptStatus(int, Terminal)
public void getAutoAcceptStatus(int autoAcceptStatus,
javax.telephony.Terminal terminal)
throws PlatformException, InvalidStateException, MethodNotSuppo
rtedException
This allows Application to enable AutoAccept for Addresses on

CiscoMediaTerminal and/or CiscoRouteTerminal. Addresses on
CiscoTerminal other than CiscoMediaTerminal or CiscoRouteTerminal will
always have AutoAccept on. If Terminal passed in the parameter is not
CiscoMediaTerminal or CiscoRouteTerminal, it will throw exception. For the
CiscoMediaTerminal that have Shared Address with CiscoTerminal, it is
recommended to enable AutoAccept on CiscoMediaTerminal.
Pre-conditions:

2-20 OL-7242-02
CiscoAddress
Post-conditions:
Parameters:
value - Can be either CiscoAddress.AUTOACCEPT_OFF or
CiscoAddress.AUTOACCEPT_ON. If autoAcceptStatus is
AUTOACCEPT_ON, it will enable AutoAccept for address on Terminal.
If autoAcceptStatus is AUTOACCEPT_OFF, it will disable AutoAccept
for address on Terminal.
terminal. - It the terminal on which AutoAccept will be enabled
Throws:
javax.telephony.PlatformException - Terminal is not on the
Address.
method is not supported ExtraProviderAddresses.
setMessageWaiting(java.lang.String destination, boolean enable)

public void setMessageWaiting(java.lang.String destination,
boolean enable)
throws MethodNotSupportedException, InvalidStateException, Priv
ilegeViolationException
Specifies whether the message-waiting indicator should be activated or

deactivated for the Address specified by the destination. If enable is
true, message-waiting is activated if not already activated. If enable is false,
message-waiting is deactivated if not already deactivated.
Pre-conditions:
Post-conditions:

OL-7242-02 2-21
CiscoAddress
Note The following postconditions as specified in CallControlAddress are

currently not enforced by this implementation.
1. this.getMessageWaiting() == enable
2. CallCtlAddrMessageWaitingEv is delivered for this Address
Parameters:
destination - DN whose message waiting indicator should be
activated
enable - True to activate message-waiting, false to deactivate.
Throws:
method is not supported by the given implementation.
javax.telephony.PrivilegeViolationException - The
Provider user has insufficient privileges to invoke the message waiting
indicator for this destination
setRingerStatus(int)
public void setRingerStatus(int status)
throws MethodNotSupportedException, InvalidStateException, Inva
lidArgumentException
Changes the ringer status on this address

Accepts on of the following constants: CiscoAddress.RINGER_DEFAULT
CiscoAddress.RINGER_DISABLE CiscoAddress.RINGER_ENABLE
Throws:
javax.telephony.InvalidArgumentException,
javax.telephony.MethodNotSupportedException

2-22 OL-7242-02
CiscoAddressCallInfo
CiscoAddressCallInfo
Declaration
public class CiscoAddressCallInfo
java.lang.Object
|
+--com.cisco.jtapi.extensions.CiscoAddressCallInfo
Member Summary
Constructors
CiscoAddressCallInfo(int, int, int, int), int
imaxActiveCalls, int inumCallsOnHold, int imaxCallsOnHold)
CiscoAddressCallInfo(int, int, int, int, CiscoCall[]), int
imaxActiveCalls, int inumCallsOnHold, int imaxCallsOnHold,
CiscoCall icalls)
Methods
CiscoCall[] getCalls()
int getMaxActiveCalls()
int getMaxCallsOnHold()
int getNumActiveCalls()
int getNumCallsOnHold()

Methods inherited from class Object
clone(), equals(Object), finalize(), getClass(), hashCode(), notify(), notifyAll(),
toString(), wait(), wait(), wait()
Constructors
CiscoAddressCallInfo(int, int, int, int)
public CiscoAddressCallInfo(int inumActiveCalls,
int imaxActiveCalls, int inumCallsOnHold, int imaxCallsOnHold)

OL-7242-02 2-23
CiscoAddressObserver
CiscoAddressCallInfo(int, int, int, int, CiscoCall[])

public CiscoAddressCallInfo(int inumActiveCalls,
int imaxActiveCalls, int inumCallsOnHold, int imaxCallsOnHold,
com.cisco.jtapi.extensions.CiscoCall[] icalls)
Methods
getCalls()
public com.cisco.jtapi.extensions.CiscoCall[] getCalls()
getMaxActiveCalls()
public int getMaxActiveCalls()
getMaxCallsOnHold()
public int getMaxCallsOnHold()
getNumActiveCalls()
public int getNumActiveCalls()
getNumCallsOnHold()
public int getNumCallsOnHold()
Declaration
public interface CiscoAddressObserver extends
javax.telephony.AddressObserver
All Superinterfaces
javax.telephony.AddressObserver

2-24 OL-7242-02
CiscoAddrEv
Description
Applications implement this interface in order to receive CiscoAddrEv events
such as CiscoAddrInServiceEv and CiscoAddrOutOfServiceEv
when observing Addresses via the Address.addObserver method.
See Also:
CiscoAddrInServiceEv, CiscoAddrOutOfServiceEv

Methods inherited from interface AddressObserver
addressChangedEvent(AddrEv[])
CiscoAddrEv
Declaration
public interface CiscoAddrEv extends CiscoEv,
javax.telephony.events.AddrEv
All Superinterfaces
javax.telephony.events.AddrEv, CiscoEv,
All Known Subinterfaces

CiscoAddrAutoAcceptStatusChangedEv, CiscoAddrInServiceEv,
CiscoAddrOutOfServiceEv

OL-7242-02 2-25
CiscoAddrInServiceEv
Description
The CiscoAddrEv interface, which extends JTAPI’s core
javax.telephony.events.AddrEv interface, serves as the base interface
for all Cisco-extended JTAPI Address events. Every Address-related event in this
package extends this interface, directly or indirectly.
See Also:
javax.telephony.events.AddrEv

META_UNKNOWN

getAddress()

Declaration
public interface CiscoAddrInServiceEv extends CiscoAddrEv

2-26 OL-7242-02
All Superinterfaces
javax.telephony.events.AddrEv, CiscoAddrEv, CiscoEv,
Description
The CiscoAddrInServiceEv event
Member Summary
Fields
static int ID
Methods
InService.

META_UNKNOWN

getAddress()


OL-7242-02 2-27
Fields
ID
Methods
getTerminal()
Returns the terminal at which this address is going InService

In Shared Lines, applications may receive multiple CiscoAddressInService
events and the same Address appears on different Terminals. In order for
Application to find out which Shared Line is going in service, Applications
can use this interface. This interface returns the terminal on which Address is
going in Service.
Returns:
the terminal at which this address is going InService
See Also:
CiscoAddress.getInServiceAddressTerminal()
Declaration
public interface CiscoAddrOutOfServiceEv extends CiscoAddrEv,
CiscoOutOfServiceEv

2-28 OL-7242-02
All Superinterfaces
javax.telephony.events.AddrEv,CiscoAddrEv, CiscoEv,
CiscoOutOfServiceEv, javax.telephony.events.Ev
Description
The CiscoAddrOutOfServiceEv event
Member Summary
Fields
static int ID
Methods
OutOfService.

Fields inherited from interface CiscoOutOfServiceEv
CAUSE_CALLMANAGER_FAILURE, CAUSE_CTIMANAGER_FAILURE, CAUSE_DEVICE_FAILURE,
CAUSE_DEVICE_UNREGISTERED, CAUSE_NOCALLMANAGER_AVAILABLE,
CAUSE_REHOME_TO_HIGHER_PRIORITY_CM, CAUSE_REHOMING_FAILURE

META_UNKNOWN

getAddress()

OL-7242-02 2-29
CiscoAddrRemovedEv

Fields
ID
Methods
getTerminal()
Returns the terminal at which this address is going OutOfService

In Shared Lines, applications may receive multiple
CiscoAddressOutOfService events and the same Address appears on different
Terminals. Applications use this interface to find out which Shared Line is
going out of service.
Returns:
the terminal at which this address is going OutOfService
See Also:
CiscoAddress.getInServiceAddressTerminal()
CiscoAddrRemovedEv
Declaration
public interface CiscoAddrRemovedEv extends CiscoProvEv

2-30 OL-7242-02
CiscoAddrRemovedEv
All Superinterfaces
Description
The CiscoAddrRemovedEv event
Member Summary
Fields
static int ID
Methods

META_UNKNOWN


getProvider()

OL-7242-02 2-31
CiscoAddrRemovedFromTerminalEv
Fields
ID
Methods
getAddress()
Declaration
public interface CiscoAddrRemovedEv extends CiscoProvEv
All Superinterfaces
Description
The CiscoAddrRemovedFromTerminalEv event gets sent under the following
conditions:
• When User removes a Terminal/Device into the user controlList that contains
SharedDN, this event will be sent to application. If a user has an address in
control list, and we remove a device with same address in control list, this
event will be sent.

2-32 OL-7242-02
• When EM(Extension mobility) user logs out from Terminal with a profile that
contains SharedDN, this event notifies that one of the Terminals is removed
from an existing Address.
• A new SharedDN is removed from a Device in a user control list. Interface
getTerminal() returns the terminal that is removed from the Address.
Interface getAddress() will return the address from where the terminal is
removed.
Member Summary
Fields
static int ID
Methods

META_UNKNOWN


getProvider()
Fields
ID

OL-7242-02 2-33
CiscoCall
Methods
getAddress()
getTerminal()
public javax.telephony.Terminal getTerminal()
CiscoCall
Declaration
public interface CiscoCall extends
javax.telephony.callcontrol.CallControlCall, CiscoObjectContainer
All Superinterfaces
javax.telephony.Call,
javax.telephony.callcontrol.CallControlCall,

CiscoConsultCall
Description
The CiscoCall interface extends the CallControlCall interface with additional
CallManager-specific capabilities.

2-34 OL-7242-02
CiscoCall
In Cisco CallManager terms, every Call object comprises a set of call legs that
share a common identifier: the global call handle. Connection objects represent
call legs in JTAPI, and the Call object that relates a set of Connections contains
the global call handle that the underlying call legs share.
The global call handle within a CiscoCall is accessible via its CallManagerID
and CallID properties. Taken together, the CallManagerID and CallID form the
global call handle maintained by the CallManager. This pair of properties is
guaranteed to be unique among all ACTIVE Call objects, but when an ACTIVE
call becomes INACTIVE, its CallManagerID and CallID may be reused to
identify a newly-created Call object. Therefore, it is possible for an INACTIVE
Call to have identical CallManagerID and CallID properties to those of a currently
ACTIVE Call object.
See Also:
javax.telephony.Call
Member Summary
Methods
void conference(Call[])
Merges N calls together, resulting in the union of the
participants of all the calls being placed on a single
call.
connect(Terminal, Address, String, CiscoRTPParams)
javax.telephony.Connection From the CallEvent perspective, this method behaves
[] similar to Call.connect(Terminal terminal, Address
origaddr, String dialedDigits).
boolean getCalledAddressPI()
Returns Presentation Indicator(PI) associated with
getCalledAddressPI. If it returns true, Application can
display this Address name to end users. If it returns
false, Applications should not display this Address name
to end user.
CiscoCallID getCallID()
CallID is a unique identifier among all ACTIVE calls
with the same CallManagerID.

OL-7242-02 2-35
CiscoCall
Member Summary
boolean getCallingAddressPI()
getCallingAddressPI. If it returns true, Application can
display this Address name to end users. If it returns
to the end user.
javax.telephony.Address getCurrentCalledAddress()
Returns the current calling address for the call.
boolean getCurrentCalledAddressPI()
CurrentCalledAddress. If it returns true, Application
can display this Address to end users. If it returns
to end user.
getCurredCalledDisplayNamePI. If it returns true,
Application can display this DisplayName to end users.
If it returns false, Applications should not display
this DisplayName to end user.
java.lang.String getCurrentCalledPartyDisplayName()
This interface returns the display of the called party
in the call.
javax.telephony.Address getCurrentCallingAddress()
This interface returns current called address for the
call this will return updated calling address every
every time call is redirected or transferred.
For example, in the CiscoJtapi implementation,
CallControlCall.getCallingAddress() returns the first
calling party of the call.
boolean getCurrentCallingAddressPI()
returns Presentation Indicator(PI) associated with
getCurrentCallingAddressPI If it returns true,
Application can display this Address name to end users
if it returns false, Applications should not display
this Address name to end user
getCurrentCalledDisplayNamePI If it returns true,
Application can display this DisplayName to end users if
it returns false, Applications should not display this
DisplayName to end user
java.lang.String getCurrentCallingPartyDisplayName()
This interface returns the display name of the calling
party.

2-36 OL-7242-02
CiscoCall
Member Summary
boolean getLastRedirectingAddressPI()
getLastRedirectingAddressPI If it returns true, Application
can display this Address name to end users if it returns
false, Applications should not display this Address name to
end user
javax.telephony.Address getModifiedCalledAddress()
This interface returns modified called address for the call
if an application modifies its calling party using from
selectRoute API.
javax.telephony.Address getModifiedCallingAddress()
This interface returns modified calling address for the call
if an application modifies its calling party using from
selectRoute API.
javax.telephony.Connection transfer(String, String, String)
This method overloads the CallControlCall.transfer(String)
method.

Fields inherited from interface Call
ACTIVE, IDLE, INVALID
Methods inherited from interface Call

addObserver(CallObserver), connect(Terminal, Address, String),
getCallCapabilities(Terminal, Address), getCapabilities(Terminal, Address),
getConnections(), getObservers(), getProvider(), getState(),
removeObserver(CallObserver)
Methods inherited from interface CallControlCall

addParty(String), conference(Call), consult(TerminalConnection),
consult(TerminalConnection), drop(), getCalledAddress(), getCallingAddress(),
getCallingTerminal(), getConferenceController(), getConferenceEnable(),
getLastRedirectedAddress(), getTransferController(), getTransferEnable(),
offHook(Address, Terminal), setConferenceController(TerminalConnection),
setConferenceEnable(boolean), setTransferController(TerminalConnection),
setTransferEnable(boolean), transfer(String), transfer(String)


OL-7242-02 2-37
CiscoCall
Methods
conference(Call[])
public void
converence(javax.telephony.Call[] otherCalls)
Throws:
InvalidStateException, InvalidArgumentException,
MethodNotSupportedE xception, PrivilegeViolationException,
ResourceUnavailableException
Merges N Calls together, resulting in the union of the participants of all the
Calls being placed on a single Call. This method takes list of Calls as
argument, referred to hereafter as the “secondary” Calls. All of the
participants from the secondary call are moved to the Call on which this
method is invoked.
The Conference Controller

In order for the conferencing feature to happen, there must be a common
participant to all the Calls, as represented by a single Terminal and multiple
TerminalConnections, one on all of the Calls. These TerminalConnections are
known as the conference controllers. In the real-world, only one of the Calls
would be active with respect to the controlling Terminal, and hence, the
TerminalConnection on the secondary Call should be in the
CallControlTerminalConnection.HELD state. The N conference controlling
TerminalConnections are merged into one as a result of this method.
Applications may control which TerminalConnection acts as the conference
controller via the CallControlCall.setConferenceController() method. The
CallControlCall.getConferenceController() method returns the current
conference controller, null if there is none. If no conference controller is set,
the implementation chooses a suitable TerminalConnection when the
conferencing feature is invoked.
The Telephone Call Argument

All of the participants from the secondary Calls, passed as the argument to
this method, are “moved” to the Call on which this method was invoked. That
is, new Connections and TerminalConnections are created on this Call which
are found on the secondary Calls. Those Connections and
TerminalConnections on the secondary Calls are removed from the Call and
the Call moves into the Call.INVALID state.

2-38 OL-7242-02
CiscoCall
The conference controller TerminalConnections are merged into one on this

Call. That is, the existing TerminalConnection controller on this Call remains
unchanged, while the TerminalConnection on the secondary Calls gets
removed from that Call.
Other Shared Participants

There may exist Address and Terminals which are part of some telephone
calls in addition to the designated conference controller. In these instances,
those participants which are shared between both Calls are merged into one.
That is, the Connections and TerminalConnections on this Calls are left
unchanged. The corresponding Connections and TerminalConnections on the
secondary Calls are removed from that Call.
Pre-conditions:
1. Let tc1 be the conference controller on this Call
2. Let connection1 = tc1.getConnection()
3. Let tc2 to tcN be the conference controllers on otherCalls
5. (this.getState() == Call.ACTIVE
6. tc1.getTerminal() == tc2.getTerminal()...=tcN.getTerminal
7. tc1.getCallControlState() ==
CallControlTerminalConnection.TALKING/HELD
8. tc2-tcN.getCallControlState() ==
CallControlTerminalConnection.HELD/TALKING
9. this != otherCalls
Post-conditions:
2. this.getState() == Call.ACTIVE
3. otherCall.getState() == INVALID
4. Let c[] be the Connections to be merged from otherCall
5. Let tc[] be the TerminalConnections to be merged from otherCall
6. Let new(c) be the set of new Connections created on this Call
7. Let new(tc) be the set of new TerminalConnections created on this Call

OL-7242-02 2-39
CiscoCall
8. new(c) element of this.getConnections()

9. new(c).getCallState() == c.getCallState()
10. new(tc) element of (this.getConnections()).getTerminalConnections()
11. new(tc).getCallState() == tc.getCallState()
12. c[i].getCallControlState() ==
CallControlConnection.DISCONNECTED for all i
13. tc[i].getCallControlState() ==
CallControlTerminalConnection.DROPPED for all i
14. CallInvalidEv is delivered for otherCall
15. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for all
c[i]
16. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all
tc[i]
17. ConnCreatedEv is delivered for all new(c)
18. TermConnCreatedEv is delivered for all new(tc)
19. Appropriate events are delivered for all new(c) and new(tc)
Parameters:
otherCall - The second Call which to merge with this Call object.
Throws:
javax.telephony.InvalidArgumentException - The Call object provided is
not valid for the conference
javax.telephony.InvalidStateException - Either the Provider is not “in
service”, the Call is not “active”, or the conference controllers are not in
the proper state.
javax.telephony.MethodNotSupportedException - This method is not
supported by the implementation.
javax.telephony.PrivilegeViolationException - The application does not
have the proper authority to invoke this method.
javax.telephony.ResourceUnavailableException - An internal resource
necessary for the successful invocation of this method is not available.

2-40 OL-7242-02
CiscoCall
See Also:
javax.telephony.events.ConnCreatedEv,
javax.telephony.events.TermConnCreatedEv,
javax.telephony.events.ConnDisconnectedEv,
javax.telephony.events.TermConnDroppedEv,
javax.telephony.events.CallInvalidEv,
javax.telephony.callcontrol.events.CallCtlConnDisconnectedEv,
javax.telephony.callcontrol.events.CallCtlTermConnDroppedEv
connect(Terminal, Address, String, CiscoRTPParams)

public javax.telephony.Connection[]
connect(javax.telephony.Terminal origterm,
javax.telephony.Address origaddr, java.lang.String
dialedDigits, com.cisco.jtapi.extensions.CiscoRTPParams
rtpParams)throws ResourceUnavailableException,
PrivilegeViolationException, InvalidPartyException,
InvalidArgumentException, InvalidStateException, MethodNotSup
portedException
From CallEvent perspective, this method behaves similar to

Call.connect(Terminal terminal, Address origaddr, String dialedDigits). This
method may only be invoked when making a call from CiscoMediaTerminal
want to specify media parameters for this call. Establishes the media at the
specified CiscoRTPParams parameters if the request is successful.
Throws:
javax.telephony.MethodNotSupportedException,
javax.telephony.InvalidPartyException,
javax.telephony.PrivilegeViolationException,
javax.telephony.ResourceUnavailableException
getCalledAddressPI()
public boolean getCallAddressPI()
Returns Presentation Indicator (PI) associated with getCalledAddressPI. If it

returns true, Application can display this address name to the end users. If it
returns false, Application should not display this Address name to the end
user.

OL-7242-02 2-41
CiscoCall
getCallID()
public com.cisco.jtapi.extensions.CiscoCallID getCallID()
CallID is a unique identifier among all ACTIVE calls with the same
CallManagerID.
Returns:
the CallID property of this Call
getCallingAddressPI()
public boolean getCallingAddressPI()
Returns Presentation Indicator (PI) associated with getCallingAddressPI. If it

user.
getCurrentCalledAddress()
public javax.telephony.Address getCurrentCalledAddress()
This interface returns current calling address for the call this will return
updated called address every time call gets redirected or transferred.
For example, in the CiscoJtapi implementation,
CallControlCall.getCalledAddress() returns the first called party of the call.
getCurrentCalledAddressPI()
public javax.telephony.Address getCurrentCalledAddressPI()
Returns Presentation Indicator (PI) associated with getCalledAddressPI. If it

user.
getCurrentCalledDisplayNamePI()
public boolean getCurrentCalledDisplayNamePI()
Returns Presentation Indicator (PI) associated with CurrentCalledAddress. If

it returns true, Application can display this address name to the end users. If
it returns false, Application should not display this Address name to the end
user.

2-42 OL-7242-02
CiscoCall
getCurrentCalledPartyDisplayName()
public java.lang.String getCurrentCalledPartyDisplayName()
This interface returns the display of the called party in the call. It returns null
if display name is unknown.
getCurrentCallingAddress()
public javax.telephony.Address getCurrentCallingAddress()
This interface returns current called address for the call this will return
updated calling address every time call is redirected or transferred
Note In the CiscoJtapi implementation

CallControlCall.getCallingAddress()returns the first
calling party of the call i.e. the original calling party
Usage:
if ( call instanceof CiscoCall ) {
Address currentCalled = ((CiscoCall)call).getCurrentCalling ();
}
See Also:
javax.telephony.callcontrol.CallControlCall
getCurrentCallingAddressPI()
public boolean getCurrentCallingAddressPI()

getCurrentCallingAddress. If it returns true, Application can display this
Address to end users. If it returns false, Applications should not display this
Address name to end user
getCurrentCallingDisplayNamePI()
public boolean getCurrentCallingDisplayNamePI()

getCurrentCalledDisplayNamePI. If it returns true, Application can display
this DisplayName to end users. If it returns false, Applications should not
display this DisplayName to end user

OL-7242-02 2-43
CiscoCall
getCurrentCallingPartyDisplayName()
public java.lang.String getCurrentCallingPartyDisplayName()
This interface returns the display name of the calling party. It returns null if
display name is unknown.
getLastRedirectingAddressPI()
public boolean getLastRedirectingAddressPI()

getLastRedirectingAddressPI. If it returns true, Application can display this
Address name to end users. If it returns false, Applications should not display
this Address name to end user
getModifiedCalledAddress()
public javax.telephony.Address getModifiedCalledAddress()
This interface returns modified called address for the call if an application
modifies its calling party using from selectRoute API. However, this
information may not be accurate if an application is only controlling the
Route Point that is modifying the calling number. If no modified calling
number is performed, this is similar to getCurrentCalledAddress interface.
Typically, this is varied from getCurrentCalledAddress when a feature is
invoked after modified calling number modifications.
Usage:
Address currentCalled = ((CiscoCall)call).getModifiedCalledAddress
();
}
See Also:

2-44 OL-7242-02
CiscoCallChangedEv
getModifiedCallingAddress()
public javax.telephony.Address getModifiedCallingAddress()
This interface returns modified calling address for the call if an application
modifies its calling party using from selectRoute API. However, this
information may not be accurate if an application is only controlling the RP
that is modifying the calling number. If no modified calling number is
performed, this is similar to getCurrentCallingAddress interface.
Usage:
Address currentCalled =
((CiscoCall)call).getModifiedCallingAddress ();
}
See Also:
transfer(String, String, String)

javax.telephony.Connection transfer
(java.lang.String destinationAddress, java.lang.String facCode,
java.lang.String cmcCode)
This method overloads the CallControlCall.transfer(String) method. It takes

two new parameters: facCode and cmcCode. The facCode is the forced
authorization code (FAC), and cmcCode is the client matter code (CMC).
See Also:
CiscoCallChangedEv
Declaration
public interface CiscoCallChangedEv extends CiscoCallEv,
javax.telephony.events.CallEv

OL-7242-02 2-45
CiscoCallChangedEv
All Superinterfaces
javax.telephony.events.CallEv, CiscoCallEv,
Description
The CiscoCallChangedEv event is delivered to the call observer whenever the
Global Call ID (GCID) of the call is changed due to path replacement. In the case
of shared lines, multiple CiscoCallChangedEv events would be delivered.
Member Summary
Methods
CiscoCall getSurvivingCall()
Returns a reference to the new call, which would be the surviving
call.
CiscoCall getOriginalCall()
Returns a reference to the old call, which will go to INVALID
state.
getCiscoCause()
Returns CiscoCaqllEv.CAUSE_QSIG_PR when GCID is changed
QSIG Path replacement.
CiscoConnection getConnection()
Returns the connection of the call on which the change has
occurred.
TerminalConnection getTerminalConnection()
Returns the terminal connection of the on which the GCID has
changed. A Null is returned if there is no terminal connection.

Fields inherited from interface CiscoCallEv

2-46 OL-7242-02
CiscoCallChangedEv

CAUSE_ACCESSINFORMATIONDISCARDED, CAUSE_BARGE, CAUSE_BCBPRESENTLYAVAIL,
CAUSE_BCNAUTHORIZED, CAUSE_BEARERCAPNIMPL, CAUSE_CALLBEINGDELIVERED, CAUSE_CALLIDINUSE,
CAUSE_CALLMANAGER_FAILURE, CAUSE_CALLREJECTED, CAUSE_CALLSPLIT, CAUSE_CHANTYPENIMPL,
CAUSE_CHANUNACCEPTABLE, CAUSE_CTIMANAGER_FAILURE, CAUSE_DESTINATIONOUTOFORDER,
CAUSE_DESTNUMMISSANDDCNOTSUB, CAUSE_FACILITYREJECTED, CAUSE_IDENTIFIEDCHANDOESNOTEXIST,
CAUSE_IENIMPL, CAUSE_INBOUNDBLINDTRANSFER, CAUSE_INBOUNDCONFERENCE,
CAUSE_INBOUNDTRANSFER, CAUSE_INCOMINGCALLBARRED, CAUSE_INCOMPATABLEDDESTINATION,
CAUSE_INTERWORKINGUNSPECIFIED, CAUSE_INVALIDCALLREFVALUE, CAUSE_INVALIDIECONTENTS,
CAUSE_INVALIDMESSAGEUNSPECIFIED, CAUSE_INVALIDNUMBERFORMAT, CAUSE_INVALIDTRANSITNETSEL,
CAUSE_MANDATORYIEMISSING, CAUSE_MSGNCOMPATABLEWCS, CAUSE_MSGTYPENCOMPATWCS,
CAUSE_MSGTYPENIMPL, CAUSE_NETOUTOFORDER, CAUSE_NOANSWERFROMUSER, CAUSE_NOCALLSUSPENDED,
CAUSE_NOCIRCAVAIL, CAUSE_NOERROR, CAUSE_NONSELECTEDUSERCLEARING,
CAUSE_NORMALCALLCLEARING, CAUSE_NORMALUNSPECIFIED, CAUSE_NOROUTETODDESTINATION,
CAUSE_NOROUTETOTRANSITNET, CAUSE_NOUSERRESPONDING, CAUSE_NUMBERCHANGED,
CAUSE_ONLYRDIVEARERCAPAVAIL, CAUSE_OUTBOUNDCONFERENCE, CAUSE_OUTBOUNDTRANSFER,
CAUSE_PROTOCOLERRORUNSPECIFIED, CAUSE_QUALOFSERVNAVAIL, CAUSE_RECOVERYONTIMEREXPIRY,
CAUSE_REDIRECTED, CAUSE_REQCALLIDHASBEENCLEARED, CAUSE_REQCIRCNAVIL,
CAUSE_REQFACILITYNIMPL, CAUSE_REQFACILITYNOTSUBSCRIBED, CAUSE_RESOURCESNAVAIL,
CAUSE_RESPONSETOSTATUSENQUIRY, CAUSE_SERVNOTAVAILUNSPECIFIED,
CAUSE_SERVOPERATIONVIOLATED, CAUSE_SERVOROPTNAVAILORIMPL, CAUSE_SUSPCALLBUTNOTTHISONE,
CAUSE_SWITCHINGEQUIPMENTCONGESTION, CAUSE_TEMPORARYFAILURE, CAUSE_UNALLOCATEDNUMBER,
CAUSE_USERBUSY

META_UNKNOWN
Methods inherited from interface CallEv

getCall()
Methods inherited from interface CiscoCallEv

getCiscoCause()


OL-7242-02 2-47
CiscoCallEv
Methods
getSurvivingCall()
public com.cisco.jtapi.extensions.CiscoCall getSurvivingCall()
Returns a reference to the new call, which would be the surviving call.
getOriginalCall()
public com.cisco.jtapi.extensions.CiscoCall getOriginalCall()
Returns a reference to the old call, which will go to INVALID state.
getCiscoCause()
public int getCiscoCause()
Returns CiscoCallEv.CAUSE_QSIG_PR when the GCID is changed by

QSIG path replacement.
getConnection()
public com.cisco.jtapi.extensions.CiscoConnection getConnection()
Returns the connection of the call on which the change has occurred.
getTerminalConnection()
public javax.telephony.TerminalConnection getTerminalConnection()
Returns the terminal connection of the call on which the GCID has changed.
A Null is returned if there is no terminal connection.
CiscoCallEv
Declaration
public interface CiscoCallEv extends CiscoEv,

2-48 OL-7242-02
CiscoCallEv
All Superinterfaces
javax.telephony.events.CallEv, CiscoEv,

CiscoConferenceEndEv, CiscoConferenceStartEv,
CiscoConsultCallActiveEv, CiscoTransferEndEv,
CiscoTransferStartEv, CiscoCallChangedEv
Description
The CiscoCallEv interface, which extends the JTAPI core
javax.telephony.events.CallEv interface, serves as the base interface
for all Cisco-extended JTAPI Call events. Every Call-related event in this package
extends this interface, directly or indirectly.
See Also:
Member Summary
Fields
static int CAUSE_ACCESSINFORMATIONDISCARDED
static int CAUSE_BARGE
static int CAUSE_BCBPRESENTLYAVAIL
static int CAUSE_BCNAUTHORIZED
static int CAUSE_BEARERCAPNIMPL
static int CAUSE_CALLBEINGDELIVERED
static int CAUSE_CALLIDINUSE
static int CAUSE_CALLMANAGER_FAILURE
static int CAUSE_CALLREJECTED
static int CAUSE_CALLSPLIT
static int CAUSE_CHANTYPENIMPL
static int CAUSE_CHANUNACCEPTABLE

OL-7242-02 2-49
CiscoCallEv
Member Summary
static int CAUSE_CTIMANAGER_FAILURE
static int CAUSE_DESTINATIONOUTOFORDER
static int CAUSE_DESTNUMMISSANDDCNOTSUB
static int CAUSE_FACILITYREJECTED
static int CAUSE_IDENTIFIEDCHANDOESNOTEXIST
static int CAUSE_IENIMPL
static int CAUSE_INBOUNDBLINDTRANSFER
static int CAUSE_INBOUNDCONFERENCE
static int CAUSE_INBOUNDTRANSFER
static int CAUSE_INCOMINGCALLBARRED
static int CAUSE_INCOMPATABLEDDESTINATION
static int CAUSE_INTERWORKINGUNSPECIFIED
static int CAUSE_INVALIDCALLREFVALUE
static int CAUSE_INVALIDIECONTENTS
static int CAUSE_INVALIDMESSAGEUNSPECIFIED
static int CAUSE_INVALIDNUMBERFORMAT
static int CAUSE_INVALIDTRANSITNETSEL
static int CAUSE_MANDATORYIEMISSING
static int CAUSE_MSGNCOMPATABLEWCS
static int CAUSE_MSGTYPENCOMPATWCS
static int CAUSE_MSGTYPENIMPL
static int CAUSE_NETOUTOFORDER
static int CAUSE_NOANSWERFROMUSER
static int CAUSE_NOCALLSUSPENDED
static int CAUSE_NOCIRCAVAIL
static int CAUSE_NOERROR
static int CAUSE_NONSELECTEDUSERCLEARING
static int CAUSE_NORMALCALLCLEARING
static int CAUSE_NORMALUNSPECIFIED
static int CAUSE_NOROUTETODDESTINATION
static int CAUSE_NOROUTETOTRANSITNET
static int CAUSE_NOUSERRESPONDING
static int CAUSE_NUMBERCHANGED
static int CAUSE_ONLYRDIVEARERCAPAVAIL
static int CAUSE_OUTBOUNDCONFERENCE
static int CAUSE_OUTBOUNDTRANSFER
static int CAUSE_PROTOCOLERRORUNSPECIFIED
static int CAUSE_QUALOFSERVNAVAIL
static int CAUSE_RECOVERYONTIMEREXPIRY
static int CAUSE_REDIRECTED
static int CAUSE_REQCALLIDHASBEENCLEARED
static int CAUSE_REQCIRCNAVIL
static int CAUSE_REQFACILITYNIMPL

2-50 OL-7242-02
CiscoCallEv
Member Summary
static int CAUSE_DESTINATIONOUTOFORDER
static int CAUSE_DESTNUMMISSANDDCNOTSUB
static int CAUSE_FACILITYREJECTED
static int CAUSE_IDENTIFIEDCHANDOESNOTEXIST
static int CAUSE_IENIMPL
static int CAUSE_INBOUNDBLINDTRANSFER
static int CAUSE_INBOUNDCONFERENCE
static int CAUSE_INBOUNDTRANSFER
static int CAUSE_INCOMINGCALLBARRED
static int CAUSE_INCOMPATABLEDDESTINATION
static int CAUSE_INTERWORKINGUNSPECIFIED
static int CAUSE_INVALIDCALLREFVALUE
static int CAUSE_INVALIDIECONTENTS
static int CAUSE_INVALIDMESSAGEUNSPECIFIED
static int CAUSE_INVALIDNUMBERFORMAT
static int CAUSE_INVALIDTRANSITNETSEL
static int CAUSE_MANDATORYIEMISSING
static int CAUSE_MSGNCOMPATABLEWCS
static int CAUSE_MSGTYPENCOMPATWCS
static int CAUSE_MSGTYPENIMPL
static int CAUSE_NETOUTOFORDER
static int CAUSE_NOANSWERFROMUSER
static int CAUSE_NOCALLSUSPENDED
static int CAUSE_NOCIRCAVAIL
static int CAUSE_NOERROR
static int CAUSE_NONSELECTEDUSERCLEARING
static int CAUSE_NORMALCALLCLEARING
static int CAUSE_NORMALUNSPECIFIED
static int CAUSE_NOROUTETODDESTINATION
static int CAUSE_NOROUTETOTRANSITNET
static int CAUSE_NOUSERRESPONDING
static int CAUSE_NUMBERCHANGED
static int CAUSE_ONLYRDIVEARERCAPAVAIL
static int CAUSE_OUTBOUNDCONFERENCE
static int CAUSE_OUTBOUNDTRANSFER
static int CAUSE_PROTOCOLERRORUNSPECIFIED
static int CAUSE_QUALOFSERVNAVAIL
static int CAUSE_RECOVERYONTIMEREXPIRY
static int CAUSE_REDIRECTED
static int CAUSE_REQCALLIDHASBEENCLEARED
static int CAUSE_REQCIRCNAVIL
static int CAUSE_REQFACILITYNIMPL

OL-7242-02 2-51
CiscoCallEv
Member Summary
static int CAUSE_REQFACILITYNOTSUBSCRIBED
static int CAUSE_RESOURCESNAVAIL
static int CAUSE_RESPONSETOSTATUSENQUIRY
static int CAUSE_SERVNOTAVAILUNSPECIFIED
static int CAUSE_SERVOPERATIONVIOLATED
static int CAUSE_SERVOROPTNAVAILORIMPL
static int CAUSE_SUSPCALLBUTNOTTHISONE
static int CAUSE_SWITCHINGEQUIPMENTCONGESTION
static int CAUSE_TEMPORARYFAILURE
static int CAUSE_UNALLOCATEDNUMBER
static int CAUSE_USERBUSY
Methods
int getCiscoCause()
Returns the CallManager cause for this event.

META_UNKNOWN

getCall()

Fields
CAUSE_ACCESSINFORMATIONDISCARDED
public static final int CAUSE_ACCESSINFORMATIONDISCARDED

2-52 OL-7242-02
CiscoCallEv
CAUSE_BARGE
public static final int CAUSE_BARGE
CAUSE_BCBPRESENTLYAVAIL
public static final int CAUSE_BCBPRESENTLYAVAIL
CAUSE_BCNAUTHORIZED
public static final int CAUSE_BCNAUTHORIZED
CAUSE_BEARERCAPNIMPL
public static final int CAUSE_BEARERCAPNIMPL
CAUSE_CALLBEINGDELIVERED
public static final int CAUSE_CALLBEINGDELIVERED
CAUSE_CALLIDINUSE
public static final int CAUSE_CALLIDINUSE
CAUSE_CALLMANAGER_FAILURE
public static final int CAUSE_CALLMANAGER_FAILURE
CAUSE_CALLREJECTED
public static final int CAUSE_CALLREJECTED
CAUSE_CALLSPLIT
public static final int CAUSE_CALLSPLIT
CAUSE_CHANTYPENIMPL
public static final int CAUSE_CHANTYPENIMPL
CAUSE_CHANUNACCEPTABLE
public static final int CAUSE_CHANUNACCEPTABLE
CAUSE_CTIMANAGER_FAILURE
public static final int CAUSE_CTIMANAGER_FAILURE
CAUSE_DESTINATIONOUTOFORDER
public static final int CAUSE_DESTINATIONOUTOFORDER

OL-7242-02 2-53
CiscoCallEv
CAUSE_DESTNUMMISSANDDCNOTSUB
public static final int CAUSE_DESTNUMMISSANDDCNOTSUB
CAUSE_FACILITYREJECTED
public static final int CAUSE_FACILITYREJECTED
CAUSE_IDENTIFIEDCHANDOESNOTEXIST
public static final int CAUSE_IDENTIFIEDCHANDOESNOTEXIST
CAUSE_IENIMPL
public static final int CAUSE_IENIMPL
CAUSE_INBOUNDBLINDTRANSFER
public static final int CAUSE_INBOUNDBLINDTRANSFER
CAUSE_INBOUNDCONFERENCE
public static final int CAUSE_INBOUNDCONFERENCE
CAUSE_INBOUNDTRANSFER
public static final int CAUSE_INBOUNDTRANSFER
CAUSE_INCOMINGCALLBARRED
public static final int CAUSE_INCOMINGCALLBARRED
CAUSE_INCOMPATABLEDDESTINATION
public static final int CAUSE_INCOMPATABLEDDESTINATION
CAUSE_INTERWORKINGUNSPECIFIED
public static final int CAUSE_INTERWORKINGUNSPECIFIED
CAUSE_INVALIDCALLREFVALUE
public static final int CAUSE_INVALIDCALLREFVALUE
CAUSE_INVALIDIECONTENTS
public static final int CAUSE_INVALIDIECONTENTS
CAUSE_INVALIDMESSAGEUNSPECIFIED
public static final int CAUSE_INVALIDMESSAGEUNSPECIFIED

2-54 OL-7242-02
CiscoCallEv
CAUSE_INVALIDNUMBERFORMAT
public static final int CAUSE_INVALIDNUMBERFORMAT
CAUSE_INVALIDTRANSITNETSEL
public static final int CAUSE_INVALIDTRANSITNETSEL
CAUSE_MANDATORYIEMISSING
public static final int CAUSE_MANDATORYIEMISSING
CAUSE_MSGNCOMPATABLEWCS
public static final int CAUSE_MSGNCOMPATABLEWCS
CAUSE_MSGTYPENCOMPATWCS
public static final int CAUSE_MSGTYPENCOMPATWCS
CAUSE_MSGTYPENIMPL
public static final int CAUSE_MSGTYPENIMPL
CAUSE_NETOUTOFORDER
public static final int CAUSE_NETOUTOFORDER
CAUSE_NOANSWERFROMUSER
public static final int CAUSE_NOANSWERFROMUSER
CAUSE_NOCALLSUSPENDED
public static final int CAUSE_NOCALLSUSPENDED
CAUSE_NOCIRCAVAIL
public static final int CAUSE_NOCIRCAVAIL
CAUSE_NOERROR
public static final int CAUSE_NOERROR
CAUSE_NONSELECTEDUSERCLEARING
public static final int CAUSE_NONSELECTEDUSERCLEARING
CAUSE_NORMALCALLCLEARING
public static final int CAUSE_NORMALCALLCLEARING

OL-7242-02 2-55
CiscoCallEv
CAUSE_NORMALUNSPECIFIED
public static final int CAUSE_NORMALUNSPECIFIED
CAUSE_NOROUTETODDESTINATION
public static final int CAUSE_NOROUTETODDESTINATION
CAUSE_NOROUTETOTRANSITNET
public static final int CAUSE_NOROUTETOTRANSITNET
CAUSE_NOUSERRESPONDING
public static final int CAUSE_NOUSERRESPONDING
CAUSE_NUMBERCHANGED
public static final int CAUSE_NUMBERCHANGED
CAUSE_ONLYRDIVEARERCAPAVAIL
public static final int CAUSE_ONLYRDIVEARERCAPAVAIL
CAUSE_OUTBOUNDCONFERENCE
public static final int CAUSE_OUTBOUNDCONFERENCE
CAUSE_OUTBOUNDTRANSFER
public static final int CAUSE_OUTBOUNDTRANSFER
CAUSE_PROTOCOLERRORUNSPECIFIED
public static final int CAUSE_PROTOCOLERRORUNSPECIFIED
CAUSE_QUALOFSERVNAVAIL
public static final int CAUSE_QUALOFSERVNAVAIL
CAUSE_RECOVERYONTIMEREXPIRY
public static final int CAUSE_RECOVERYONTIMEREXPIRY
CAUSE_REDIRECTED
public static final int CAUSE_REDIRECTED
CAUSE_REQCALLIDHASBEENCLEARED
public static final int CAUSE_REQCALLIDHASBEENCLEARED

2-56 OL-7242-02
CiscoCallEv
CAUSE_REQCIRCNAVIL
public static final int CAUSE_REQCIRCNAVIL
CAUSE_REQFACILITYNIMPL
public static final int CAUSE_REQFACILITYNIMPL
CAUSE_REQFACILITYNOTSUBSCRIBED
public static final int CAUSE_REQFACILITYNOTSUBSCRIBED
CAUSE_RESOURCESNAVAIL
public static final int CAUSE_RESOURCESNAVAIL
CAUSE_RESPONSETOSTATUSENQUIRY
public static final int CAUSE_RESPONSETOSTATUSENQUIRY
CAUSE_SERVNOTAVAILUNSPECIFIED
public static final int CAUSE_SERVNOTAVAILUNSPECIFIED
CAUSE_SERVOPERATIONVIOLATED
public static final int CAUSE_SERVOPERATIONVIOLATED
CAUSE_SERVOROPTNAVAILORIMPL
public static final int CAUSE_SERVOROPTNAVAILORIMPL
CAUSE_SUSPCALLBUTNOTTHISONE
public static final int CAUSE_SUSPCALLBUTNOTTHISONE
CAUSE_SWITCHINGEQUIPMENTCONGESTION
public static final int CAUSE_SWITCHINGEQUIPMENTCONGESTION
CAUSE_TEMPORARYFAILURE
public static final int CAUSE_TEMPORARYFAILURE
CAUSE_UNALLOCATEDNUMBER
public static final int CAUSE_UNALLOCATEDNUMBER
CAUSE_USERBUSY
public static final int CAUSE_USERBUSY

OL-7242-02 2-57
CiscoCallID
Methods
getCiscoCause()
public int getCiscoCause()
Returns the CallManager cause for this event.

In order to function properly, some applications need to know the reason why
an event happened at an endpoint that the application is observing. For
example, a Connection may be disconnected because the call was not
answered (CAUSE_NOANSWERFROMUSER), or whether the caller it was
disconnected because it was rejected (CAUSE_CALLREJECTED).
Returns:
the CallManager cause for this event
CiscoCallID
Declaration
public interface CiscoCallID extends CiscoObjectContainer
All Superinterfaces
Description
The CiscoCallID object represents a unique object associated with each call.
Applications may use the object itself or the integer representation of the object
returned by the intValue() method.

2-58 OL-7242-02
CiscoCallID
Member Summary
Methods
CiscoCall getCall()
int getCallManagerID()
returns the call manager nodeID of the call
int getGlobalCallID()
returns the GlobalCallID of the call
int intValue()
Returns an integer representation of this object,
currently a bitwise OR of the CallManagerID and
GlobalCallID properties (shifted and truncated
appropriately)

Methods
getCall()
public com.cisco.jtapi.extensions.CiscoCall getCall()
getCallManagerID()
public int getCallManagerID()
returns the call manager nodeID of the call
getGlobalCallID()
public int getGlobalCallID()
returns the GlobalCallID of the call
intValue()
public int intValue()
Returns an integer representation of this object, currently a bitwise OR of the

CallManagerID and GlobalCallID properties (shifted and truncated
appropriately)

OL-7242-02 2-59
Returns:
an integer representation of this object
Declaration
public interface CiscoConferenceEndEv extends CiscoCallEv
All Superinterfaces
javax.telephony.events.CallEv, CiscoCallEv, CiscoEv,
Description
The CiscoConferenceEndEv event indicates that a transfer operation has
completed. This event is reported via the CallControlCallObserver
interface.
Member Summary
Fields
static int ID
Methods
javax.telephony.Address getConferenceControllerAddress()
Returns the Address, which currently acts as the
conference controller for this call —- the initiating
call.
javax.telephony.Call getConferencedCall()
Returns the call that have merged.
javax.telephony.Call[] getFailedCalls()
Returns a list of the calls that could not be
conferenced.

2-60 OL-7242-02
Member Summary
javax.telephony.Call getFinalCall()
Returns the call that remains active after the
conference completes.
getHeldConferenceController()
javax.telephony.TerminalCo Returns the TerminalConnection, which currently acts as
nnection the conference controller for this call —- the
initiating call.
getHeldConferenceControllers()
nnection[] the conference controller for this call —- the
initiating call.
getTalkingConferenceController()
initiating call.
boolean isSuccess()
Returns True or False depending on whether Conference is
successful or failed.


OL-7242-02 2-61

CAUSE_USERBUSY

META_UNKNOWN

getCall()

getCiscoCause()


2-62 OL-7242-02
Fields
ID
Methods
getConferenceControllerAddress()
public javax.telephony.Address getConferenceControllerAddress()
Returns the Address which currently acts as the conference controller for this
call —- the initiating call.
getConferencedCall()
public javax.telephony.Call getConferencedCall()
Returns the call that has been merged. This call is in the Call.INVALID
state.
getFailedCalls()
public favax.telephony.Call[] getFailedCalls{}
Returns the list of the calls that could not be conferenced.

Returns:
Null, if conference is successful.
See Also:
isSuccess()
getFinalCall()
public javax.telephony.Call getFinalCall()
Returns the call that remains active after the conference is completed.

OL-7242-02 2-63
public javax.telephony.TerminalConnection
Returns the TerminalConnection which currently acts as the conference

controller for this call —- the final call. This is the TerminalConnection that
was in HELD state when conference was initiated. This method returns null
if the conference controller is not being observed.
public javax.telephony.TerminalConnection[]

controller for this call: the initiating call. This is the TerminalConnection that
was in the HELD state. This method returns null if the conference controller
is not being observed. This method returns the first held Controller for
multiple call join scenario.

controller for this call —- the initiating call. This is the TerminalConnection
that was in TALKING state. This method returns null if the conference
controller is not being observed.
isSuccess()
public boolean isSuccess()
Returns True or False depending on whether the Conference successful or

failed. Application can use interface to find whether Conference is
successful. The following are defined as Conference Fail:
• If application issues request Call.conferece(otherCalls[]) this Conference
would be considered failed, if one or more than one Calls could Join into
Conference. Application can use interface getFailedCalls() to find Failed
Call.

2-64 OL-7242-02
• If no Conference Bridge available and conference could not be completed at

all. Again Application can use interface getFailedCalls() to get list of Calls
that could not Join into Conference.
• Party being Conferenced Dropped out before conference could be completed.
Declaration
public interface CiscoConferenceStartEv extends CiscoCallEv
All Superinterfaces
Description
The CiscoConferenceStartEv event indicates that a conference operation
has started. This event is reported via the CallControlCallObserver
interface.
Member Summary
Fields
static int ID
Methods
javax.telephony.Address getConferenceControllerAddress()
Returns the Address which currently acts as the
conference controller for this call —- the initiating
call.
javax.telephony.Call getConferencedCall()
Returns the call that will be conferenced.
javax.telephony.Call[] getConferencedCalls()
Returns the list of the calls that will be conferenced.

OL-7242-02 2-65
Member Summary
Returns the call that will remain active after the
conference is completed.
javax.telephony.TerminalCo Returns the TerminalConnection which currently acts as
initiating call.
javax.telephony.TerminalCo getHeldConferenceControllers()
nnection[] Returns the TerminalConnection that currently acts as
the conference controller for this call — the initiating
call.
javax.telephony.TerminalCo Returns the TerminalConnection which currently acts as
initiating call.

CAUSE_USERBUSY

2-66 OL-7242-02

META_UNKNOWN

getCall()

getCiscoCause()

Fields
ID
Methods
getConferenceControllerAddress()
public javax.telephony.Address getConferenceControllerAddress()
Returns the Address which currently acts as the conference controller for this
call —- the initiating call.
getConferencedCall()
public javax.telephony.Call getConferencedCall()
Returns the call that will be conferenced. This is the call that will be merged
into the initiating call.

OL-7242-02 2-67
getConferencedCalls()
public javax.telephony.Call getConferencedCalls()
Returns the list of calls that will be conferenced. This is the call that will be
merged into the final call.
getFinalCall()
Returns the call that will remain active after the conference is completed. This
is the call all calls are finally merged into.
Returns the TerminalConnection that currently acts as the conference

that was in HELD state. This method returns null if the conference controller
is not being observed.
Returns the TerminalConnection that currently acts as the conference

that was in HELD state. This method returns null if the conference controller
is not being observed. This method returns all held controllers joining into the
finalCall.

that was in TALKING state. This method returns null if the conference
controller is not being observed.

2-68 OL-7242-02
CiscoConnection
CiscoConnection
Declaration
public interface CiscoConnection extends
javax.telephony.callcontrol.CallControlConnection,
All Superinterfaces
javax.telephony.callcontrol.CallControlConnection,
CiscoObjectContainer, javax.telephony.Connection
Description
The CiscoConnection interface extends the CallControlConnection interface
with additional CallManager-specific capabilities.
Applications can use the getReason method to obtain the reason for the
creation of this Connection.
Member Summary
Fields
static int ADDRESS_SEARCH_SPACE
This indicates that the redirect should be done using
the search space of the redirect controller’s address.
static int CALLED_ADDRESS_DEFAULT
This option indicates that the default behavior for
Cisco JTAPI should apply.
static int CALLED_ADDRESS_SET_TO_REDIRECT_DESTINATION
This option indicates that the calledAddress should be
reset to the redirect destination.
static int CALLED_ADDRESS_UNCHANGED
This option indicates that the calledAddress should
remain unchanged after the redirect operation.

OL-7242-02 2-69
CiscoConnection
Member Summary
static int CALLINGADDRESS_SEARCH_SPACE
the search space of the calling address.
static int DEFAULT_SEARCH_SPACE
the search space that is the default for the
implementation.
static int REASON_DIRECTCALL
This Connection was the result of a direct call.
static int REASON_FORWARDALL
This Connection was the result of unconditional
forwarding.
static int REASON_FORWARDBUSY
This Connection was the result of a forwarding on busy.
static int REASON_FORWARDNOANSWER
This Connection was the result of a forwarding on no
answer.
static int REASON_OUTBOUND
This Connection is an originating Connection, not a
destination Connection.
static int REASON_REDIRECT
This Connection was the result of a redirection.
static int REASON_TRANSFERREDCALL
This Connection was the result of a transfer.
static int REDIRECT_DROP_ON_FAILURE
This redirect mode instructs the implementation to
perform redirect without checking the validity or
availability of the destination.
static int REDIRECT_NORMAL
This redirect mode instructs the implementation to
perform redirect if the destination is valid and
available.
Methods
CiscoConnectionID getConnectionID()
CiscoConnectionID is a unique object that identifier
among all ACTIVE calls with the same CallManagerID.
int getReason()
Returns the reason for the creation of this Connection.
getRedirectController()
javax.telephony.TerminalC This method returns the current redirectController for
onnection the connection.
java.lang.String park()
This method parks the call at a system park port and
returns the address of the port.

2-70 OL-7242-02
CiscoConnection
Member Summary
redirect(String, int)
javax.telephony.Connectio This method overloads the
n CallControlConnection.redirect() method.
redirect(String, int, int)
redirect(String, int, int, int)

Fields inherited from interface CallControlConnection
ALERTING, DIALING, DISCONNECTED, ESTABLISHED, FAILED, IDLE, INITIATED,
NETWORK_ALERTING, NETWORK_REACHED, OFFERED, OFFERING, QUEUED, UNKNOWN
Fields inherited from interface Connection

CONNECTED, INPROGRESS
Methods inherited from interface CallControlConnection

accept(), addToAddress(String), getCallControlState(), park(String), redirect(String),
reject()

Methods inherited from interface Connection

disconnect(), getAddress(), getCall(), getCapabilities(),
getConnectionCapabilities(Terminal, Address), getState(), getTerminalConnections()

OL-7242-02 2-71
CiscoConnection
Fields
ADDRESS_SEARCH_SPACE
public static final int ADDRESS_SEARCH_SPACE
This indicates that the redirect should be done using the search space of the
redirect controller’s address.
CALLED_ADDRESS_DEFAULT
public static final int CALLED_ADDRESS_DEFAULT
This option indicates that the default behavior for Cisco JTAPI should apply.
Cisco JTAPI’s default behavior is the same as
CALLED_ADDRESS_UNCHANGED.
CALLED_ADDRESS_SET_TO_REDIRECT_DESTINATION
public static final int CALLED_ADDRESS_SET_TO_REDIRECT_DESTINATION
This option indicates that the calledAddress should be reset to the redirect
destination.
CALLED_ADDRESS_UNCHANGED
public static final int CALLED_ADDRESS_UNCHANGED
This option indicates that the calledAddress should remain unchanged after
the redirect operation.
CALLINGADDRESS_SEARCH_SPACE
public static final int CALLINGADDRESS_SEARCH_SPACE
calling address.
DEFAULT_SEARCH_SPACE
public static final int DEFAULT_SEARCH_SPACE
This indicates that the redirect should be done using the search space that is
the default for the implementation. The default is to use the calling address’s
search space.

2-72 OL-7242-02
CiscoConnection
REASON_DIRECTCALL
public static final int REASON_DIRECTCALL
This Connection was the result of a direct call.
REASON_FORWARDALL
public static final int REASON_FORWARDALL
This Connection was the result of unconditional forwarding.
REASON_FORWARDBUSY
public static final int REASON_FORWARDBUSY
This Connection was the result of a forwarding on busy.
REASON_FORWARDNOANSWER
public static final int REASON_FORWARDNOANSWER
This Connection was the result of a forwarding on no answer.
REASON_OUTBOUND
public static final int REASON_OUTBOUND
This Connection is an originating Connection, not a destination Connection.
REASON_REDIRECT
public static final int REASON_REDIRECT
This Connection was the result of a redirection.
REASON_TRANSFERREDCALL
public static final int REASON_TRANSFERREDCALL
This Connection was the result of a transfer.
REDIRECT_DROP_ON_FAILURE
public static final int REDIRECT_DROP_ON_FAILURE
This redirect mode instructs the implementation to perform redirect without

checking the validity or availability of the destination. The original call will
be dropped if the destination is not valid or if it’s busy.

OL-7242-02 2-73
CiscoConnection
REDIRECT_NORMAL
public static final int REDIRECT_NORMAL
This redirect mode instructs the implementation to perform redirect if the

destination is valid and available. Otherwise, the request will return error. The
original call will not be dropped on failure.
Methods
getAddressPI()
public boolean getAddressPI()
Returns Presentation Indicator(PI) associated with Address on which the

connection is created. If it returns true, Application can display this Address
Name to end users. If it returns false, Applications should not display this
Address Name to end user
getConnectionID()
public com.cisco.jtapi.extensions.CiscoConnectionID
getConnectionID()
CiscoConnectionID is a unique object that identifier among all ACTIVE calls

with the same CallManagerID.
Returns:
getReason()
public int getReason()
Returns the reason for the creation of this Connection.

In order to function properly, some applications need to know the reason why
a Connection is created at an endpoint that the application is observing. For
example, a voice mail application may want to know whether a caller is
someone that wants to leave a message in a voice mailbox
(REASON_FORWARDNOANSWER), or whether the caller is trying to access a
voice mail box (REASON_DIRECTCALL).

2-74 OL-7242-02
CiscoConnection
The reason for a Connection creation may be any of the following constants:
• CiscoConnection.REASON_DIRECTCALL
• CiscoConnection.REASON_TRANSFERREDCALL
• CiscoConnection.REASON_FORWARDNOANSWER
• CiscoConnection.REASON_FORWARDBUSY
• CiscoConnection.REASON_FORWARDALL
• CiscoConnection.REASON_REDIRECT
• CiscoConnection.REASON_NORMAL
All of the reasons except for REASON_TRANSFERORIGINATION and
REASON_NORMAL are associated with inbound, or destination Connections.
The REASON_NORMAL reason is associated without outbound, or originating
Connections.
Returns:
the reason for the creation of this Connection
getRedirectController()
public javax.telephony.TerminalConnection getRedirectController()
Returns the current redirectController for the connection.
park()
public java.lang.String park()
throws InvalidArgumentException, PrivilegeViolationException,
ResourceUnavailableException, InvalidStateException
This method parks the call at a system park port and returns the address of the
port. The call can be unparked using this address.
Throws:
javax.telephony.ResourceUnavailableException,
javax.telephony.InvalidArgumentException

OL-7242-02 2-75
CiscoConnection
redirect(String, int)
public javax.telephony.Connection redirect(java.lang.String
destinationAddress, int mode)
throws InvalidStateException, InvalidPartyException, MethodNotS
upportedException, PrivilegeViolationException, ResourceUnavail
ableException
This method overloads the CallControlConnection.redirect() method. It takes

a new parameter —- redirectMode. When this parameter is:
1. CiscoConnection.REDIRECT_DROP_ON_FAILURE This mode
instructs the implementation to perform redirect without checking the
validity or availability of the destination. The original call will be
dropped if the destination is not valid or if it’s busy.
2. CiscoConnection.REDIRECT_NORMAL This mode instructs the
implementation to perform redirect only after checking the validity or
availability of the destination. This is the same as the
CallControlConnection.redirect() method. The original
call will not be dropped on failure.
Throws:
javax.telephony.InvalidStateException
redirect(String, int, int)

destinationAddress, int mode, int callingSearchSpace)
ableException

two new parameters —- redirectMode and callingSearchSpace. The
redirectMode is used to select which type of redirect to perform, and the
callingSearchSpace is used to instruct the implementation to use either the
calling party’s search space or the redirect controller’s search space.

2-76 OL-7242-02
CiscoConnection
The redirectMode parameter may be:

1. CiscoConnection.REDIRECT_DROP_ON_FAILURE
2. CiscoConnection.REDIRECT_NORMAL
Read above for a description of what each of these means.
The callingSearchSpace parameter may be:
1. CiscoConnection.DEFAULT_SEARCH_SPACE
2. CiscoConnection.CALLINGADDRESS_SEARCH_SPACE
3. CiscoConnection.ADDRESS_SEARCH_SPACE
Note The callingSearchSpace parameter may be specified when the redirect

controller is a RouteAddress. It will be ignored for all other address types.
Throws:
redirect(String, int, int, int)

destinationAddress, int mode, int callingSearchSpace,
int calledAddressOption)
ableException

three new parameters —- redirectMode, callingSearchSpace, and
calledAddressOption. The redirectMode is used to select which type of
redirect to perform, and the callingSearchSpace is used to instruct the
implementation to use either the calling party’s search space or the redirect
controller’s search space. The calledAddressOption parameter is used to
decide whether to reset the original called fields or not.

OL-7242-02 2-77
CiscoConnection


The calledAddressOption parameter may be:

1. CiscoConnection.CALLED_ADDRESS_DEFAULT
2. CiscoConnection.CALLED_ADDRESS_UNCHANGED
3. CiscoConnection.CALLED_ADDRESS_SET_TO_REDIRECT_DESTIN
ATION
Throws:
redirect(String, int, int, String)

destinationAddress, int mode, int callingSearchSpace,
java.lang.String preferredOriginalCalledParty)
throws InvalidStateException, InvalidPartyException,
MethodNotSupportedException, PrivilegeViolationException,
ResourceUnavailableException

three new parameters -- redirectMode, callingSearchSpace,
preferredOriginalCalledParty.

2-78 OL-7242-02
CiscoConnection
The redirectMode is used to select which type of redirect to perform, and the
callingSearchSpace is used to instruct the implementation to use either the
calling party's search space or the redirect controller's search space.

PreferredOriginalCalledParty parameter may be: a DN which will be the

originalCalledParty field when call is offered to destinationAddress.
Throws:
redirect(String, int, int, int, String, String, String)

public javax.telephony.Connection redirect
(java.lang.String destinationAddress, int mode,
int callingSearchSpace, int calledAddressOption,
java.lang.String preferredOriginalCalledParty,
java.lang.String facCode, java.lang.String cmcCode)

five new parameters —- redirectMode, callingSearchSpace,
calledAddressOption, facCode, and cmcCode. The redirectMode is used to

OL-7242-02 2-79
CiscoConnection
select which type of redirect to perform, and the callingSearchSpace is used

to instruct the implementation to use either the calling party’s search space or
the redirect controller’s search space. The calledAddressOption parameter is
used to decide whether to reset the original called fields or not.

The calledAddressOption parameter may be:

1. CiscoConnection.CALLED_ADDRESS_DEFAULT
2. CiscoConnection.CALLED_ADDRESS_UNCHANGED
3. CiscoConnection.CALLED_ADDRESS_SET_TO_REDIRECT_DESTIN
ATION
Throws:
PreferredOriginalCalledParty parameter may be a DN that will be the
originalCalledParty field when the call is offered to destinationAddress.
The facCode is the forced account code (FAC), and cmcCode is the client
matter code (CMC).
setRequestController(TerminalConnection)
public void

2-80 OL-7242-02
CiscoConnectionID
setRequestController(javax.telephony.TerminalConnection tc)
throws InvalidArgumentException, InvalidStateException
This interface is provided to Requesting TerminalConnection. Applications

are required to call this method prior to redirecting /Parking/disconnecting
the Call for a Connection for a SharedLine Call. On a SharedLine address,
there will be more that one TerminalConnection for a connection.
When there is only one active terminalConnection, applications may not
specify RequestController, however if there is more that one active
TerminalConnection in same connection e.g for BargedCall/ConferenceCall
then Applications must specify RequestController. RequestController is the
TerminalConnection which will be used for completing request.
RequestController will be set to null/0 after request is completed/executed.
The following examples show how this interface can be used.
Example 2-1 Redirect: Address A has two active terminalConnection TC1 and
TC2 Application want to redirect Call T2 to C.
CiscoConnection.setRequqestController(TC2);
CiscoConnection.redirect(C);
Example 2-2 Park: Address A have two active TerminalConnection TC1 and
TC2 Application want to Park the Call at T2
CiscoConnection.setRequestController(TC2);
CiscoConnection.park();
Throws:
javax.telephony.InvalidArgumentException
CiscoConnectionID
Declaration
public interface CiscoConnectionID extends CiscoObjectContainer

OL-7242-02 2-81
CiscoConnectionID
All Superinterfaces
Description
The CiscoConnectionID object represents a unique object associated with
each connection. Applications may use the object itself or the integer
representation of the object returned by the intValue() method.
Member Summary
Methods
CiscoConnection getConnection()
int intValue()
Returns an integer representation of this object,
currently the CallManager CallLeg ID.

Methods
getConnection()
public com.cisco.jtapi.extensions.CiscoConnection getConnection()
intValue()
public int intValue()
Returns an integer representation of this object, currently the CallManager

CallLeg ID.

2-82 OL-7242-02
CiscoConsultCall
Returns:
CiscoConsultCall
Declaration
public interface CiscoConsultCall extends CiscoCall
All Superinterfaces
javax.telephony.Call,
javax.telephony.callcontrol.CallControlCall,
CiscoCall, CiscoObjectContainer
Description
The CiscoConsultCall interface extends the CiscoCall interface to expose
certain properties of Calls that have been created as part of a consultative transfer
or consultative conference.
See Also:
Member Summary
Methods
consultWithoutMedia(TerminalConnection, String)
javax.telephony.Connectio From CallEvent perspective, this method behaves similar
n[] to CallControlCall.consult(TerminalConnection tc, String
dialedDigits).

OL-7242-02 2-83
CiscoConsultCall
Member Summary
getConsultingTerminalConnection()
javax.telephony.TerminalC Returns the consulting TerminalConnection that was used
onnection to create this CiscoConsultCall.

Fields inherited from interface Call
ACTIVE, IDLE, INVALID
Methods inherited from interface Call

addObserver(CallObserver), connect(Terminal, Address, String),
getCallCapabilities(Terminal, Address), getCapabilities(Terminal, Address),
getConnections(), getObservers(), getProvider(), getState(),
removeObserver(CallObserver)
Methods inherited from interface CallControlCall

addParty(String), conference(Call), consult(TerminalConnection),
consult(TerminalConnection), drop(), getCalledAddress(), getCallingAddress(),
getCallingTerminal(), getConferenceController(), getConferenceEnable(),
getLastRedirectedAddress(), getTransferController(), getTransferEnable(),
offHook(Address, Terminal), setConferenceController(TerminalConnection),
setConferenceEnable(boolean), setTransferController(TerminalConnection),
setTransferEnable(boolean), transfer(String), transfer(String)
Methods inherited from interface CiscoCall

conference(Call[]), connect(Terminal, Address, String, CiscoRTPParams), getCallID(),
getCalledAddressPI(), getCallingAddressPI(), getCurrentCalledAddress(),
getCurrentCalledAddressPI(), getCurrentCalledDisplayNamePI(),
getCurrentCalledPartyDisplayName(), getCurrentCallingAddress(),
getCurrentCallingAddressPI(), getCurrentCallingDisplayNamePI(),
getCurrentCallingPartyDisplayName(), getLastRedirectingAddressPI(),
getModifiedCalledAddress(), getModifiedCallingAddress()


2-84 OL-7242-02
CiscoConsultCall
Methods
consultWithoutMedia(TerminalConnection, String)
public javax.telephony.Connection[]
consultWithoutMedia(javax.telephony.TerminalConnection tc,
java.lang.String dialedDigits)
throws InvalidStateException, InvalidArgumentException, MethodN
otSupportedException, ResourceUnavailableException, PrivilegeVi
olationException, InvalidPartyException
From CallEvent perspective, this method behaves similar to

CallControlCall.consult(TerminalConnection tc,
String dialedDigits). Creates a consultation between this Call and
an active Call without establishing the media. This consult call may only be
transferred, not conferenced.
The Consultation Purpose
This method does not support if invoked with
CallControlCall.setConferneceEnable(). It only supports if
invoked with CallControlCall.setTransferEnable().
Throws:
Returns the consulting TerminalConnection that was used to create this

CiscoConsultCall.
If this Call was created as part of a consultative transfer or consultative
conference, the TerminalConnection which was used to perform the
consultation on the original Call is returned by the
getConsultingTerminalConnection method. This may be useful to

OL-7242-02 2-85
CiscoConsultCall
applications that wish to correlate a ConsultCall with its original Call. Note
that the original Call does not have any methods which may be used to
determine the ConsultCall, if any, to which it is related.
Returns:
null if this Call is not the result of a consultation, or the consulting
TerminalConnection of the original Call if this Call is the result of a
consultation.

2-86 OL-7242-02
CiscoConsultCallActiveEv
Declaration
public interface CiscoConsultCallActiveEv extends CiscoCallEv,
javax.telephony.events.CallActiveEv
All Superinterfaces
javax.telephony.events.CallActiveEv,
Description
The CiscoConsultCallActiveEv event interface extends the JTAPI
CallActiveEv. It indicates that the state of the Call object has changed to
Call.ACTIVE and that the call was initiated as a result of a consultative transfer
or consultative conference operation (manual or programmatic). Applications can
obtain the consulting TerminalConnection on the original (consulting) call by
using the CiscoConsultCall.getConsultingTerminalConnection
method.
This event is reported to applications via the CallObserver interface.
See Also:
javax.telephony.Call, javax.telephony.CallObserver,
javax.telephony.events.CallActiveEv
Member Summary
Fields
static int ID

OL-7242-02 2-87
Member Summary
Methods
getHeldTerminalConnection()
javax.telephony.TerminalC Returns the consulting TerminalConnection that was used
onnection to create this CiscoConsultCall.

CAUSE_USERBUSY

META_UNKNOWN

getCall()

2-88 OL-7242-02

getCiscoCause()

Fields
ID
Methods
Deprecated.
replaced by CiscoConsultCall.getConsultingTerminalConnection ()
Returns the consulting TerminalConnection that was used to create this
CiscoConsultCall.
This may be useful to applications that wish to correlate a consultation Call
with its original Call. Note that the original Call does not have any methods
which may be used to determine the consultation Call, if any, to which it is
related.
Returns:
the consulting TerminalConnection of the Call that created the Call
referenced by this event

OL-7242-02 2-89
CiscoEv
CiscoEv
Declaration
public interface CiscoEv extends javax.telephony.events.Ev
All Superinterfaces

CiscoAddrAddedToTerminalEv, CiscoAddrAutoAcceptStatusChangedEv,
CiscoAddrCreatedEv, CiscoAddrEv, CiscoAddrInServiceEv,
CiscoAddrOutOfServiceEv, CiscoAddrRemovedEv, CiscoCallEv,
CiscoConferenceEndEv, CiscoConferenceStartEv,
CiscoConsultCallActiveEv, CiscoOutOfServiceEv,
CiscoProvCallParkEv, CiscoProvEv, CiscoProvFeatureEv,
CiscoProvFeatureUnRegisteredEv, CiscoRTPInputStartedEv,
CiscoRTPInputStoppedEv, CiscoRTPOutputStoppedEv,
CiscoRTPOutputStartedEv, CiscoTermButtonPressedEv,
CiscoTermButtonPressedEv, CiscoTermCreatedEv, CiscoTermDataEv,
CiscoTermEv, CiscoTerminal, CiscoTerminal, CiscoTermInServiceEv,
CiscoTermOutOfServiceEv, CiscoTermRemovedEv,
CiscoTransferEndEv, CiscoTransferStartEv
Description
The CiscoEv interface, which extends JTAPI’s core
javax.telephony.events.Ev interface, serves as the base interface for all
Cisco-extended JTAPI events. Every event in this package extends this interface,
directly or indirectly.

2-90 OL-7242-02
CiscoG711MediaCapability
See Also:

META_UNKNOWN

Declaration
public class CiscoG711MediaCapability extends CiscoMediaCapability
java.lang.Object
|
+--com.cisco.jtapi.extensions.CiscoMediaCapability
|
+--com.cisco.jtapi.extensions.CiscoG711MediaCapability
Description
The CiscoG711MediaCapability object specifies the properties for a
G.711 encoded RTP stream. Applications that support G.711 media termination
use this object to specify their preferred packet size when registering a
CiscoMediaTerminal.
The default packet size is thirty milliseconds.

OL-7242-02 2-91
Member Summary
Fields
static int FRAMESIZE_SIXTY_MILLISECOND_PACKET
The frames-per-packet value for 60 millisecond packets
static int FRAMESIZE_THIRTY_MILLISECOND_PACKET
static int FRAMESIZE_TWENTY_MILLISECOND_PACKET
Constructors
CiscoG711MediaCapability()
Constructs a CiscoG711MediaCapability</CODE object with a
default thirty millisecond packet size.
CiscoG711MediaCapability(int)
Constructs a CiscoG711MediaCapability</CODE object with
the specified packet size.

Fields inherited from class CiscoMediaCapability
G711_64K_30_MILLISECONDS, G723_6K_30_MILLISECONDS, G729_30_MILLISECONDS,
GSM_80_MILLISECONDS, WIDEBAND_256K_10_MILLISECONDS
Methods inherited from class CiscoMediaCapability

getMaxFramesPerPacket(), getPayloadType(), toString(), isSupported()

wait(), wait(), wait()
Fields
FRAMESIZE_SIXTY_MILLISECOND_PACKET
public static final int FRAMESIZE_SIXTY_MILLISECOND_PACKET

2-92 OL-7242-02
FRAMESIZE_THIRTY_MILLISECOND_PACKET
public static final int FRAMESIZE_THIRTY_MILLISECOND_PACKET
FRAMESIZE_TWENTY_MILLISECOND_PACKET
public static final int FRAMESIZE_TWENTY_MILLISECOND_PACKET
Constructors
public CiscoG711MediaCapability()

a default thirty millisecond packet size.
CiscoG711MediaCapability(int)
public CiscoG711MediaCapability(int maxFramesPerPacket)

Declaration
java.lang.Object
|
|

OL-7242-02 2-93
Description
use this object to specify their preferred packet size and bit rate when registering
a CiscoMediaTerminal.
The default packet size is thirty milliseconds and the default bit rate is 6.4k.
Member Summary
Fields
Constructors
default thirty millisecond packet size and 6.4k bit rate.
CiscoG723MediaCapability(int, int)
the specified packet size and bit rate.
Methods
int getBitRate()
Returns the bit rate specified by this capability object.
java.lang.String toString()


getMaxFramesPerPacket(), getPayloadType(), isSupported()

2-94 OL-7242-02

witty wait()
Fields
Constructors

a default thirty millisecond packet size and 6.4k bit
rate.
public CiscoG723MediaCapability(int maxFramesPerPacket,
int bitRate)

the specified packet size and bit rate.

OL-7242-02 2-95
Methods
getBitRate()
public int getBitRate()
Returns the bit rate specified by this capability object.

Returns:
a bit rate from the RTPBitRate interface
toString()
public java.lang.String toString()
Overrides:
toString in class CiscoMediaCapability
Declaration
java.lang.Object
|
|
Description
use this object to specify their preferred packet size when registering a
CiscoMediaTerminal.

2-96 OL-7242-02
Member Summary
Fields
Constructors
default G729 payload and thirty millisecond packet size.
the specified packet size and payload.


getMaxFramesPerPacket(), getPayloadType(), isSupported(), toString()

witty wait()
Fields

OL-7242-02 2-97
Constructors

a default G729 payload and thirty millisecond packet
size.
public CiscoG729MediaCapability(int payload,
int maxFramesPerPacket)

the specified packet size and payload. The choice of
payload is specified in CiscoRTPPayload with the
options CiscoRTPPayload.G729 and
CiscoRTPPayload.G729ANNEXA

2-98 OL-7242-02
CiscoGSMMediaCapability
Declaration
public class CiscoGSMMediaCapability extends CiscoMediaCapability
java.lang.Object
|
|
+--com.cisco.jtapi.extensions.CiscoGSMMediaCapability
Description
The CiscoGSMMediaCapability object specifies the properties for a GSM
encoded RTP stream. Applications that support GSM media termination use this
object to specify their preferred packet size when registering a
CiscoMediaTerminal.
Member Summary
Fields
static int FRAMESIZE_EIGHTY_MILLISECOND_PACKET
Constructors
CiscoGSMMediaCapability()
Constructs a CiscoGSMMediaCapability</CODE object with a
default eighty millisecond packet size.
CiscoGSMMediaCapability(int)
Constructs a CiscoGSMMediaCapability</CODE object with

OL-7242-02 2-99



Fields
FRAMESIZE_EIGHTY_MILLISECOND_PACKET
public static final int FRAMESIZE_EIGHTY_MILLISECOND_PACKET
Constructors
CiscoGSMMediaCapability()
public CiscoGSMMediaCapability()
Constructs a CiscoGSMMediaCapability</CODE object with a

default eighty millisecond packet size.
CiscoGSMMediaCapability(int)
public CiscoGSMMediaCapability(int maxFramesPerPacket)
Constructs a CiscoGSMMediaCapability</CODE object with


2-100 OL-7242-02
CiscoJtapiException
CiscoJtapiException
Declaration
public interface CiscoJtapiException
Description
The CiscoJtapiException interface defines CTI error codes. These are the error
codes that may be returned by CTI requests. All the JTAPI exceptions have been
extended to implement this interface. The Error codes can be got by casting the
exception to CiscoJtapiException and calling the method getErrorCode(). If 'e' is
any exception caught in an application, see if its an instance of
CiscoJtapiException.
try {
// some code here }
catch ( Exception e ) {
if( e instanceof CiscoJtapiException){
CiscoJtapiException ce =
com.cisco.cti.client.CTIFAILURE.(CiscoJtapiException) e
int errorCode = com.cisco.cti.client.CTIFAILURE.ce.getErrorCode()
//returns the ErrorCode.
}
}
Member Summary
Fields
static int ASSOCIATED_LINE_NOT_OPEN
static int CALL_ALREADY_EXISTS
public static final int CALL_DROPPED
static int CALLHANDLE_NOTINCOMINGCALL
static int CALLHANDLE_UNKNOWN_TO_LINECONTROL
static int CANNOT_OPEN_DEVICE
static int CANNOT_TERMINATE_MEDIA_ON_PHONE
static int CFWDALL_ALREADY_OFF
static int CFWDALL_ALREADY_SET

OL-7242-02 2-101
CiscoJtapiException
Member Summary
static int CFWDALL_DESTN_INVALID
static int CLUSTER_LINK_FAILURE
static int COMMAND_NOT_IMPLEMENTED_ON_DEVICE
static int CONFERENCE_ALREADY_PRESENT
static int CONFERENCE_FAILED
static int CONFERENCE_FULL
static int CONFERENCE_INACTIVE
static int CONFERENCE_INVALID_PARTICIPANT
static int CTIERR_ACCESS_TO_DEVICE_DENIED
static int CTIERR_APP_SOFTKEYS_ALREADY_CONTROLLED
static int CTIERR_APPLICATION_DATA_SIZE_EXCEEDED
static int CTIERR_CALL_MANAGER_NOT_AVAILABLE
static int CTIERR_CALL_NOT_EXISTED
static int CTIERR_CALL_PARK_NO_DN
static int CTIERR_CALL_REQUEST_ALREADY_OUTSTANDING
static int CTIERR_CALL_UNPARK_FAILED
static int CTIERR_CAPABILITIES_DO_NOT_MATCH
static int CTIERR_CLOSE_DELAY_NOT_SUPPORTED_WITH_REG_TYPE
static int CTIERR_CONFERENCE_ALREADY_EXISTED
static int CTIERR_CONFERENCE_NOT_EXISTED
static int CTIERR_CONSULT_CALL_FAILURE
static int CTIERR_CONSULTCALL_ALREADY_OUTSTANDING
static int CTIERR_CTIHANDLER_PROCESS_CREATION_FAILED
static int CTIERR_DEVICE_ALREADY_OPENED
static int CTIERR_DEVICE_NOT_OPENED_YET
static int CTIERR_DEVICE_OWNER_ALIVE_TIMER_STARTED
static int CTIERR_DEVICE_SHUTTING_DOWN
static int CTIERR_DUPLICATE_CALL_REFERENCE
static int CTIERR_FAC_CMC_REASON_FAC_NEEDED
static int CTIERR_FAC_CMC_REASON_CMC_NEEDED
static int CTIERR_FAC_CMC_REASON_FAC_CMC_NEEDED
static int CTIERR_FAC_CMC_REASON_FAC_INVALID
static int CTIERR_FAC_CMC_REASON_CMC_INVALID
static int CTIERR_FEATURE_ALREADY_REGISTERED
static int CTIERR_FEATURE_DATA_REJECT
static int CTIERR_ILLEGAL_DEVICE_TYPE
static int CTIERR_INCOMPATIBLE_AUTOINSTALL_PROTOCOL_VERSION
static int CTIERR_INCORRECT_MEDIA_CAPABILITY
static int CTIERR_INFORMATION_NOT_AVAILABLE
static int CTIERR_INTERNAL_FAILURE
static int CTIERR_INVALID_DEVICE_NAME
static int CTIERR_INVALID_DTMFDIGITS
static int CTIERR_INVALID_MEDIA_DEVICE

2-102 OL-7242-02
CiscoJtapiException
Member Summary
static int CTIERR_INVALID_MEDIA_PARAMETER
static int CTIERR_INVALID_MEDIA_PROCESS
static int CTIERR_INVALID_MEDIA_RESOURCE_ID
static int CTIERR_INVALID_MESSAGE_HEADER_INFO
static int CTIERR_INVALID_MESSAGE_LENGTH
static int CTIERR_INVALID_MONITOR_DN_TYPE
static int CTIERR_INVALID_PARAMETER
static int CTIERR_INVALID_PARK_DN
static int CTIERR_INVALID_PARK_REGISTRATION_HANDLE
static int CTIERR_INVALID_RESOURCE_TYPE
static int CTIERR_MAXCALL_LIMIT_REACHED
static int CTIERR_MEDIA_ALREADY_TERMINATED_DYNAMIC
static int CTIERR_MEDIA_ALREADY_TERMINATED_NONE
static int CTIERR_MEDIA_ALREADY_TERMINATED_STATIC
static int CTIERR_MEDIA_CAPABILITY_MISMATCH
static int CTIERR_MEDIA_RESOURCE_NAME_SIZE_EXCEEDED
static int CTIERR_MEDIAREGISTRATIONTYPE_DO_NOT_MATCH
static int CTIERR_MESSAGE_TOO_BIG
static int CTIERR_MORE_ACTIVE_CALLS_THAN_RESERVED
static int CTIERR_NO_EXISTING_CALLS
static int CTIERR_NO_EXISTING_CONFERENCE
static int CTIERR_NO_RESPONSE_FROM_MP
static int CTIERR_NOT_PRESERVED_CALL
static int CTIERR_OPERATION_FAILED_QUIETCLEAR
static int CTIERR_OPERATION_NOT_ALLOWED
static int CTIERR_OWNER_NOT_ALIVE
static int CTIERR_PENDING_ACCEPT_OR_ANSWER_REQUEST
static int CTIERR_REDIRECT_UNAUTHORIZED_COMMAND_USAGE
static int CTIERR_REGISTER_FEATURE_ACTIVATION_FAILED
static int CTIERR_RESOURCE_NOT_AVAILABLE
static int CTIERR_STATION_SHUT_DOWN
static int CTIERR_SYSTEM_ERROR
static int CTIERR_UNKNOWN_EXCEPTION
static int CTIERR_UNSUPPORTED_CALL_PARK_TYPE
static int DARES_INVALID_REQ_TYPE
static int DATA_SIZE_LIMIT_EXCEEDED
static int DB_ERROR
static int DB_ILLEGAL_DEVICE_TYPE
static int DB_NO_MORE_DEVICES
static int DESTINATION_BUSY
static int DESTINATION_UNKNOWN
static int DEVICE_ALREADY_REGISTERED
static int DEVICE_NOT_OPEN

OL-7242-02 2-103
CiscoJtapiException
Member Summary
static int DEVICE_OUT_OF_SERVICE
static int DIGIT_GENERATION_ALREADY_IN_PROGRESS
static int DIGIT_GENERATION_CALLSTATE_CHANGED
static int DIGIT_GENERATION_WRONG_CALL_HANDLE
static int DIGIT_GENERATION_WRONG_CALL_STATE
static int DIRECTORY_LOGIN_FAILED
static int DIRECTORY_LOGIN_NOT_ALLOWED
static int DIRECTORY_TEMPORARY_UNAVAILABLE
static int EXISTING_FIRSTPARTY
static int HOLDFAILED
static int ILLEGAL_CALLINGPARTY
static int ILLEGAL_CALLSTATE
static int ILLEGAL_HANDLE
static int ILLEGAL_MESSAGE_FORMAT
static int INCOMPATIBLE_PROTOCOL_VERSION
static int INVALID_LINE_HANDLE
static int INVALID_RING_OPTION
static int LINE_INFO_DOES_NOT_EXIST
static int LINE_NOT_PRIMARY
static int LINECONTROL_FAILURE
static int MAX_NUMBER_OF_CTI_CONNECTIONS_REACHED
static int MSGWAITING_DESTN_INVALID
static int NO_ACTIVE_DEVICE_FOR_THIRDPARTY
static int NO_CONFERENCE_BRIDGE
static int NOT_INITIALIZED
static int PROTOCOL_TIMEOUT
static int PROVIDER_ALREADY_OPEN
static int PROVIDER_CLOSED
static int PROVIDER_NOT_OPEN
static int REDIRECT_CALL_CALL_TABLE_FULL
static int REDIRECT_CALL_DESTINATION_BUSY
static int REDIRECT_CALL_DESTINATION_OUT_OF_ORDER
static int REDIRECT_CALL_DIGIT_ANALYSIS_TIMEOUT
static int REDIRECT_CALL_DOES_NOT_EXIST
static int REDIRECT_CALL_INCOMPATIBLE_STATE
static int REDIRECT_CALL_MEDIA_CONNECTION_FAILED
static int REDIRECT_CALL_NORMAL_CLEARING
static int REDIRECT_CALL_ORIGINATOR_ABANDONED
static int REDIRECT_CALL_PARTY_TABLE_FULL
static int REDIRECT_CALL_PENDING_REDIRECT_TRANSACTION
static int REDIRECT_CALL_PROTOCOL_ERROR
static int REDIRECT_CALL_UNKNOWN_DESTINATION
static int REDIRECT_CALL_UNKNOWN_ERROR

2-104 OL-7242-02
CiscoJtapiException
Member Summary
static int REDIRECT_CALL_UNKNOWN_PARTY
static int REDIRECT_CALL_UNRECOGNIZED_MANAGER
static int REDIRECT_CALLINFO_ERR
static int REDIRECT_ERR
static int RETRIEVEFAILED
static int RETRIEVEFAILED_ACTIVE_CALL_ON_LINE
static int SSAPI_NOT_REGISTERED
static int TIMEOUT
static int TRANSFER_INACTIVE
static int TRANSFERFAILED
static int TRANSFERFAILED_CALLCONTROL_TIMEOUT
static int TRANSFERFAILED_DESTINATION_BUSY
static int TRANSFERFAILED_DESTINATION_UNALLOCATED
static int TRANSFERFAILED_OUTSTANDING_TRANSFER
static int UNDEFINED_LINE
static int UNKNOWN_GLOBAL_CALL_HANDLE
static int UNRECOGNIZABLE_PDU
static int UNSPECIFIED
The CTI error codes.
Methods
int getErrorCode()
Returns the errorCode for this exception
java.lang.String getErrorDescription()
This method returns the detail description of the
errorCode
java.lang.String getErrorDescription(int)
This method returns the detail description of the
errorCode
java.lang.String getErrorName()
This method returns an exception in the string format.
java.lang.String getErrorName(int)
This method will return an exception in the string
format.
Fields
ASSOCIATED_LINE_NOT_OPEN
public static final int ASSOCIATED_LINE_NOT_OPEN
CALL_ALREADY_EXISTS
public static final int CALL_ALREADY_EXISTS

OL-7242-02 2-105
CiscoJtapiException
CALL_DROPPED
public static final int CALL_DROPPED
The call is dropped after the feature request (hold, unhold, transfer,
conference) but before completing the request.
CALLHANDLE_NOTINCOMINGCALL
public static final int CALLHANDLE_NOTINCOMINGCALL
CALLHANDLE_UNKNOWN_TO_LINECONTROL
public static final int CALLHANDLE_UNKNOWN_TO_LINECONTROL
CANNOT_OPEN_DEVICE
public static final int CANNOT_OPEN_DEVICE
CANNOT_TERMINATE_MEDIA_ON_PHONE
public static final int CANNOT_TERMINATE_MEDIA_ON_PHONE
CFWDALL_ALREADY_OFF
public static final int CFWDALL_ALREADY_OFF
CFWDALL_ALREADY_SET
public static final int CFWDALL_ALREADY_SET
CFWDALL_DESTN_INVALID
public static final int CFWDALL_DESTN_INVALID
CLUSTER_LINK_FAILURE
public static final int CLUSTER_LINK_FAILURE
COMMAND_NOT_IMPLEMENTED_ON_DEVICE
public static final int COMMAND_NOT_IMPLEMENTED_ON_DEVICE
CONFERENCE_ALREADY_PRESENT
public static final int CONFERENCE_ALREADY_PRESENT
CONFERENCE_FAILED
public static final int CONFERENCE_FAILED

2-106 OL-7242-02
CiscoJtapiException
CONFERENCE_FULL
public static final int CONFERENCE_FULL
CONFERENCE_INACTIVE
public static final int CONFERENCE_INACTIVE
CONFERENCE_INVALID_PARTICIPANT
public static final int CONFERENCE_INVALID_PARTICIPANT
CTIERR_ACCESS_TO_DEVICE_DENIED
public static final int CTIERR_ACCESS_TO_DEVICE_DENIED
CTIERR_APP_SOFTKEYS_ALREADY_CONTROLLED
public static final int CTIERR_APP_SOFTKEYS_ALREADY_CONTROLLED
CTIERR_APPLICATION_DATA_SIZE_EXCEEDED
public static final int CTIERR_APPLICATION_DATA_SIZE_EXCEEDED
CTIERR_CALL_MANAGER_NOT_AVAILABLE
public static final int CTIERR_CALL_MANAGER_NOT_AVAILABLE
CTIERR_CALL_NOT_EXISTED
public static final int CTIERR_CALL_NOT_EXISTED
CTIERR_CALL_PARK_NO_DN
public static final int CTIERR_CALL_PARK_NO_DN
CTIERR_CALL_REQUEST_ALREADY_OUTSTANDING
public static final int CTIERR_CALL_REQUEST_ALREADY_OUTSTANDING
CTIERR_CALL_UNPARK_FAILED
public static final int CTIERR_CALL_UNPARK_FAILED
CTIERR_CAPABILITIES_DO_NOT_MATCH
public static final int CTIERR_CAPABILITIES_DO_NOT_MATCH

OL-7242-02 2-107
CiscoJtapiException
CTIERR_CLOSE_DELAY_NOT_SUPPORTED_WITH_REG_TYPE
public static final int
CTIERR_CLOSE_DELAY_NOT_SUPPORTED_WITH_REG_TYPE
CTIERR_CONFERENCE_ALREADY_EXISTED
public static final int CTIERR_CONFERENCE_ALREADY_EXISTED
CTIERR_CONFERENCE_NOT_EXISTED
public static final int CTIERR_CONFERENCE_NOT_EXISTED
CTIERR_CONSULT_CALL_FAILURE
public static final int CTIERR_CONSULT_CALL_FAILURE
CTIERR_CONSULTCALL_ALREADY_OUTSTANDING
public static final int CTIERR_CONSULTCALL_ALREADY_OUTSTANDING
CTIERR_CTIHANDLER_PROCESS_CREATION_FAILED
public static final int CTIERR_CTIHANDLER_PROCESS_CREATION_FAILED
CTIERR_DEVICE_ALREADY_OPENED
public static final int CTIERR_DEVICE_ALREADY_OPENED
CTIERR_DEVICE_NOT_OPENED_YET
public static final int CTIERR_DEVICE_NOT_OPENED_YET
CTIERR_DEVICE_OWNER_ALIVE_TIMER_STARTED
public static final int CTIERR_DEVICE_OWNER_ALIVE_TIMER_STARTED
CTIERR_DEVICE_SHUTTING_DOWN
public static final int CTIERR_DEVICE_SHUTTING_DOWN
CTIERR_DUPLICATE_CALL_REFERENCE
public static final int CTIERR_DUPLICATE_CALL_REFERENCE
CTIERR_FAC_CMC_REASON_CMC_INVALID
public static final int CTIERR_FAC_CMC_REASON_CMC_INVALID
CTIERR_FAC_CMC_REASON_CMC_NEEDED
public static final int CTIERR_FAC_CMC_REASON_CMC_NEEDED

2-108 OL-7242-02
CiscoJtapiException
CTIERR_FAC_CMC_REASON_FAC_INVALID
public static final int CTIERR_FAC_CMC_REASON_FAC_INVALID
CTIERR_FAC_CMC_REASON_FAC_CMC_NEEDED
public static final int.CTIERR_FAC_CMC_REASON_FAC_CMC_NEEDED
CTIERR_FAC_CMC_REASON_FAC_NEEDED
public static final int CTIERR_FAC_CMC_REASON_FAC_NEEDED
CTIERR_FEATURE_ALREADY_REGISTERED
public static final int CTIERR_FEATURE_ALREADY_REGISTERED
CTIERR_FEATURE_DATA_REJECT
public static final int CTIERR_FEATURE_DATA_REJECT
CTIERR_ILLEGAL_DEVICE_TYPE
public static final int CTIERR_ILLEGAL_DEVICE_TYPE
CTIERR_INCOMPATIBLE_AUTOINSTALL_PROTOCOL_VERSION
public static final int
CTIERR_INCOMPATIBLE_AUTOINSTALL_PROTOCOL_VERSION
CTIERR_INCORRECT_MEDIA_CAPABILITY
public static final int CTIERR_INCORRECT_MEDIA_CAPABILITY
CTIERR_INFORMATION_NOT_AVAILABLE
public static final int CTIERR_INFORMATION_NOT_AVAILABLE
CTIERR_INTERNAL_FAILURE
public static final int CTIERR_INTERNAL_FAILURE
CTIERR_INVALID_DEVICE_NAME
public static final int CTIERR_INVALID_DEVICE_NAME
CTIERR_INVALID_DTMFDIGITS
public static final int CTIERR_INVALID_DTMFDIGITS
CTIERR_INVALID_MEDIA_DEVICE
public static final int CTIERR_INVALID_MEDIA_DEVICE

OL-7242-02 2-109
CiscoJtapiException
CTIERR_INVALID_MEDIA_PARAMETER
public static final int CTIERR_INVALID_MEDIA_PARAMETER
CTIERR_INVALID_MEDIA_PROCESS
public static final int CTIERR_INVALID_MEDIA_PROCESS
CTIERR_INVALID_MEDIA_RESOURCE_ID
public static final int CTIERR_INVALID_MEDIA_RESOURCE_ID
CTIERR_INVALID_MESSAGE_HEADER_INFO
public static final int CTIERR_INVALID_MESSAGE_HEADER_INFO
CTIERR_INVALID_MESSAGE_LENGTH
public static final int CTIERR_INVALID_MESSAGE_LENGTH
CTIERR_INVALID_MONITOR_DN_TYPE
public static final int CTIERR_INVALID_MONITOR_DN_TYPE
CTIERR_INVALID_PARAMETER
public static final int CTIERR_INVALID_PARAMETER
CTIERR_INVALID_PARK_DN
public static final int CTIERR_INVALID_PARK_DN
CTIERR_INVALID_PARK_REGISTRATION_HANDLE
public static final int CTIERR_INVALID_PARK_REGISTRATION_HANDLE
CTIERR_INVALID_RESOURCE_TYPE
public static final int CTIERR_INVALID_RESOURCE_TYPE
CTIERR_MAXCALL_LIMIT_REACHED
public static final int CTIERR_MAXCALL_LIMIT_REACHED
CTIERR_INCORRECT_MEDIA_CAPABILITY
public static final int CTIERR_INCORRECT_MEDIA_CAPABILITY
CTIERR_INVALID_DTMFDIGITS
public static final int CTIERR_INVALID_DTMFDIGITS

2-110 OL-7242-02
CiscoJtapiException
CTIERR_MEDIA_ALREADY_TERMINATED_DYNAMIC
public static final int CTIERR_MEDIA_ALREADY_TERMINATED_DYNAMIC
CTIERR_MEDIA_ALREADY_TERMINATED_NONE
public static final int CTIERR_MEDIA_ALREADY_TERMINATED_NONE
CTIERR_MEDIA_ALREADY_TERMINATED_STATIC
public static final int CTIERR_MEDIA_ALREADY_TERMINATED_STATIC
CTIERR_MEDIA_CAPABILITY_MISMATCH
public static final int CTIERR_MEDIA_CAPABILITY_MISMATCH
CTIERR_MEDIA_RESOURCE_NAME_SIZE_EXCEEDED
public static final int CTIERR_MEDIA_RESOURCE_NAME_SIZE_EXCEEDED
CTIERR_MEDIAREGISTRATIONTYPE_DO_NOT_MATCH
public static final int CTIERR_MEDIAREGISTRATIONTYPE_DO_NOT_MATCH
CTIERR_MESSAGE_TOO_BIG
public static final int CTIERR_MESSAGE_TOO_BIG
CTIERR_MORE_ACTIVE_CALLS_THAN_RESERVED
public static final int CTIERR_MORE_ACTIVE_CALLS_THAN_RESERVED
CTIERR_NO_EXISTING_CALLS
public static final int CTIERR_NO_EXISTING_CALLS
CTIERR_NO_EXISTING_CONFERENCE
public static final int CTIERR_NO_EXISTING_CONFERENCE
CTIERR_NO_RESPONSE_FROM_MP
public static final int CTIERR_NO_RESPONSE_FROM_MP
CTIERR_NOT_PRESERVED_CALL
public static final int CTIERR_NOT_PRESERVED_CALL
CTIERR_OPERATION_FAILED_QUIETCLEAR
public static final int CTIERR_OPERATION_FAILED_QUIETCLEAR

OL-7242-02 2-111
CiscoJtapiException
CTIERR_OPERATION_NOT_ALLOWED
public static final int CTIERR_OPERATION_NOT_ALLOWED
CTIERR_OWNER_NOT_ALIVE
public static final int CTIERR_OWNER_NOT_ALIVE
CTIERR_PENDING_ACCEPT_OR_ANSWER_REQUEST
public static final int CTIERR_PENDING_ACCEPT_OR_ANSWER_REQUEST
CTIERR_REDIRECT_UNAUTHORIZED_COMMAND_USAGE
public static final int CTIERR_REDIRECT_UNAUTHORIZED_COMMAND_USAGE
CTIERR_REGISTER_FEATURE_ACTIVATION_FAILED
public static final int CTIERR_REGISTER_FEATURE_ACTIVATION_FAILED
CTIERR_RESOURCE_NOT_AVAILABLE
public static final int CTIERR_RESOURCE_NOT_AVAILABLE
CTIERR_STATION_SHUT_DOWN
public static final int CTIERR_STATION_SHUT_DOWN
CTIERR_SYSTEM_ERROR
public static final int CTIERR_SYSTEM_ERROR
CTIERR_UNKNOWN_EXCEPTION
public static final int CTIERR_UNKNOWN_EXCEPTION
CTIERR_UNSUPPORTED_CALL_PARK_TYPE
public static final int CTIERR_UNSUPPORTED_CALL_PARK_TYPE
DARES_INVALID_REQ_TYPE
public static final int DARES_INVALID_REQ_TYPE
DATA_SIZE_LIMIT_EXCEEDED
public static final int DATA_SIZE_LIMIT_EXCEEDED
DB_ERROR
public static final int DB_ERROR

2-112 OL-7242-02
CiscoJtapiException
DB_ILLEGAL_DEVICE_TYPE
public static final int DB_ILLEGAL_DEVICE_TYPE
DB_NO_MORE_DEVICES
public static final int DB_NO_MORE_DEVICES
DESTINATION_BUSY
public static final int DESTINATION_BUSY
DESTINATION_UNKNOWN
public static final int DESTINATION_UNKNOWN
DEVICE_ALREADY_REGISTERED
public static final int DEVICE_ALREADY_REGISTERED
DEVICE_NOT_OPEN
public static final int DEVICE_NOT_OPEN
DEVICE_OUT_OF_SERVICE
public static final int DEVICE_OUT_OF_SERVICE
DIGIT_GENERATION_ALREADY_IN_PROGRESS
public static final int DIGIT_GENERATION_ALREADY_IN_PROGRESS
DIGIT_GENERATION_CALLSTATE_CHANGED
public static final int DIGIT_GENERATION_CALLSTATE_CHANGED
DIGIT_GENERATION_WRONG_CALL_HANDLE
public static final int DIGIT_GENERATION_WRONG_CALL_HANDLE
DIGIT_GENERATION_WRONG_CALL_STATE
public static final int DIGIT_GENERATION_WRONG_CALL_STATE
DIRECTORY_LOGIN_FAILED
public static final int DIRECTORY_LOGIN_FAILED
DIRECTORY_LOGIN_NOT_ALLOWED
public static final int DIRECTORY_LOGIN_NOT_ALLOWED

OL-7242-02 2-113
CiscoJtapiException
DIRECTORY_TEMPORARY_UNAVAILABLE
public static final int DIRECTORY_TEMPORARY_UNAVAILABLE
EXISTING_FIRSTPARTY
public static final int EXISTING_FIRSTPARTY
HOLDFAILED
public static final int HOLDFAILED
ILLEGAL_CALLINGPARTY
public static final int ILLEGAL_CALLINGPARTY
ILLEGAL_CALLSTATE
public static final int ILLEGAL_CALLSTATE
ILLEGAL_HANDLE
public static final int ILLEGAL_HANDLE
ILLEGAL_MESSAGE_FORMAT
public static final int ILLEGAL_MESSAGE_FORMAT
INCOMPATIBLE_PROTOCOL_VERSION
public static final int INCOMPATIBLE_PROTOCOL_VERSION
INVALID_LINE_HANDLE
public static final int INVALID_LINE_HANDLE
INVALID_RING_OPTION
public static final int INVALID_RING_OPTION
LINE_INFO_DOES_NOT_EXIST
public static final int LINE_INFO_DOES_NOT_EXIST
LINE_NOT_PRIMARY
public static final int LINE_NOT_PRIMARY
LINECONTROL_FAILURE
public static final int LINECONTROL_FAILURE

2-114 OL-7242-02
CiscoJtapiException
MAX_NUMBER_OF_CTI_CONNECTIONS_REACHED
public static final int MAX_NUMBER_OF_CTI_CONNECTIONS_REACHED
MSGWAITING_DESTN_INVALID
public static final int MSGWAITING_DESTN_INVALID
NO_ACTIVE_DEVICE_FOR_THIRDPARTY
public static final int NO_ACTIVE_DEVICE_FOR_THIRDPARTY
NO_CONFERENCE_BRIDGE
public static final int NO_CONFERENCE_BRIDGE
NOT_INITIALIZED
public static final int NOT_INITIALIZED
PROTOCOL_TIMEOUT
public static final int PROTOCOL_TIMEOUT
PROVIDER_ALREADY_OPEN
public static final int PROVIDER_ALREADY_OPEN
PROVIDER_CLOSED
public static final int PROVIDER_CLOSED
PROVIDER_NOT_OPEN
public static final int PROVIDER_NOT_OPEN
REDIRECT_CALL_CALL_TABLE_FULL
public static final int REDIRECT_CALL_CALL_TABLE_FULL
REDIRECT_CALL_DESTINATION_BUSY
public static final int REDIRECT_CALL_DESTINATION_BUSY
REDIRECT_CALL_DESTINATION_OUT_OF_ORDER
public static final int REDIRECT_CALL_DESTINATION_OUT_OF_ORDER
REDIRECT_CALL_DIGIT_ANALYSIS_TIMEOUT
public static final int REDIRECT_CALL_DIGIT_ANALYSIS_TIMEOUT

OL-7242-02 2-115
CiscoJtapiException
REDIRECT_CALL_DOES_NOT_EXIST
public static final int REDIRECT_CALL_DOES_NOT_EXIST
REDIRECT_CALL_INCOMPATIBLE_STATE
public static final int REDIRECT_CALL_INCOMPATIBLE_STATE
REDIRECT_CALL_MEDIA_CONNECTION_FAILED
public static final int REDIRECT_CALL_MEDIA_CONNECTION_FAILED
REDIRECT_CALL_NORMAL_CLEARING
public static final int REDIRECT_CALL_NORMAL_CLEARING
REDIRECT_CALL_ORIGINATOR_ABANDONED
public static final int REDIRECT_CALL_ORIGINATOR_ABANDONED
REDIRECT_CALL_PARTY_TABLE_FULL
public static final int REDIRECT_CALL_PARTY_TABLE_FULL
REDIRECT_CALL_PENDING_REDIRECT_TRANSACTION
public static final int REDIRECT_CALL_PENDING_REDIRECT_TRANSACTION
REDIRECT_CALL_PROTOCOL_ERROR
public static final int REDIRECT_CALL_PROTOCOL_ERROR
REDIRECT_CALL_UNKNOWN_DESTINATION
public static final int REDIRECT_CALL_UNKNOWN_DESTINATION
REDIRECT_CALL_UNKNOWN_ERROR
public static final int REDIRECT_CALL_UNKNOWN_ERROR
REDIRECT_CALL_UNKNOWN_PARTY
public static final int REDIRECT_CALL_UNKNOWN_PARTY
REDIRECT_CALL_UNRECOGNIZED_MANAGER
public static final int REDIRECT_CALL_UNRECOGNIZED_MANAGER
REDIRECT_CALLINFO_ERR
public static final int REDIRECT_CALLINFO_ERR

2-116 OL-7242-02
CiscoJtapiException
REDIRECT_ERR
public static final int REDIRECT_ERR
RETRIEVEFAILED
public static final int RETRIEVEFAILED
RETRIEVEFAILED_ACTIVE_CALL_ON_LINE
public static final int RETRIEVEFAILED_ACTIVE_CALL_ON_LINE
SSAPI_NOT_REGISTERED
public static final int SSAPI_NOT_REGISTERED
TIMEOUT
public static final int TIMEOUT
TRANSFER_INACTIVE
public static final int TRANSFER_INACTIVE
TRANSFERFAILED
public static final int TRANSFERFAILED
TRANSFERFAILED_CALLCONTROL_TIMEOUT
public static final int TRANSFERFAILED_CALLCONTROL_TIMEOUT
TRANSFERFAILED_DESTINATION_BUSY
public static final int TRANSFERFAILED_DESTINATION_BUSY
TRANSFERFAILED_DESTINATION_UNALLOCATED
public static final int TRANSFERFAILED_DESTINATION_UNALLOCATED
TRANSFERFAILED_OUTSTANDING_TRANSFER
public static final int TRANSFERFAILED_OUTSTANDING_TRANSFER
UNDEFINED_LINE
public static final int UNDEFINED_LINE
UNKNOWN_GLOBAL_CALL_HANDLE
public static final int UNKNOWN_GLOBAL_CALL_HANDLE

OL-7242-02 2-117
CiscoJtapiException
UNRECOGNIZABLE_PDU
public static final int UNRECOGNIZABLE_PDU
UNSPECIFIED
public static final int UNSPECIFIED
The CTI error codes. These are the error codes that may be returned by CTI
requests.
Methods
getErrorCode()
public int getErrorCode()

Returns:
errorCode in an integer representation
getErrorDescription()
public java.lang.String getErrorDescription()
This method returns the detail description of the errorCode

Returns:
String detail description of the errorCode
getErrorDescription(int)
public java.lang.String getErrorDescription(int errorCode)
Deprecated.
instead use String getErrorDescription ();
This method returns the detail description of the errorCode
Returns:
String detail description of the errorCode

2-118 OL-7242-02
CiscoJtapiPeer
getErrorName()
public java.lang.String getErrorName()
This method returns an exception in the string format.

Returns:
String representation of the error code
getErrorName(int)
public java.lang.String getErrorName(int errorCode)
Deprecated.
instead use String getErrorName ();
This method will return an exception in the string format.
Returns:
String representation of the error code
CiscoJtapiPeer
Declaration
public interface CiscoJtapiPeer extends
com.cisco.services.tracing.TraceModule, javax.telephony.JtapiPeer,
All Superinterfaces
CiscoObjectContainer, javax.telephony.JtapiPeer,
com.cisco.services.tracing.TraceModule

OL-7242-02 2-119
CiscoJtapiPeer
Description
By extending the com.cisco.services.tracing.TraceModule
interface, the CiscoJtapiPeer exposes trace information to applications. All
instances of JtapiPeer objects created by the Cisco JTAPI implementation
implement this interface. Applications that wish to manipulate the trace settings
of the Cisco JTAPI implementation may use the
CiscoJtapiPeer.getTraceManager method to obtain its
TraceManager object. The TraceManager object may then be manipulated
as described in the com.cisco.services.tracing package.
See Also:
com.cisco.services.tracing.TraceModule
Member Summary
Methods
CiscoJtapiProperties getJtapiProperties()
CiscoJtapiProperties defines the various methods that
applications can use to modify the parameters that the
JTAPI layer will use.

Methods inherited from interface JtapiPeer

getName(), getProvider(String), getServices()
Methods inherited from interface TraceModule

getTraceManager(), getTraceModuleName()

2-120 OL-7242-02
CiscoJtapiProperties
Methods
getJtapiProperties()
public com.cisco.jtapi.extensions.CiscoJtapiProperties
getJtapiProperties()
CiscoJtapiProperties defines the various methods that applications can use to

modify the parameters that the JTAPI layer will use.
See Also:
Declaration
public interface CiscoJtapiProperties
Description
Cisco JTAPI’s behavior and functionality is tailored by many parameters which
are read in from the jtapi.ini file when an instance of CiscoJtapiPeer is
instantiated. These parameters are now exposed to applications for control via this
CiscoJtapiproperties interface.
Applications can query the CiscoJtapiproperties properties object and
change these parameters to better suit the application functionality. Exposing
these properties via the CiscoJtapiproperties interface also allows
applications to have a single point of administration (at the application end) for
these parameters.
The most visible parameters are those describing the tracing levels and tracing
destinations.

OL-7242-02 2-121
Usage:
JtapiPeer peer = JtapiPeerFactory.getJtapiPeer ( null );
if(peer instanceof CiscoJtapiPeer){
CiscoJtapiProperties jProps =
((CiscoJtapiPeer)peer).getJtapiProperties();
jProps.setTracePath(“\\D:\\Traces\\WorkFlow”);
jProps.setUseJavaConsoleTrace(false);
MyProviderObserver providerObserver = new MyProviderObserver ();
provider = peer.getProvider ( providerName );
}
where
an application sets the java console tracing to off and the trace path to
D:\Traces\WorkFlowApp1.
When the peer gets obtained, an object implementing CiscoJtapiProperties gets
created by reading parameters set in the jtapi.ini file. If no jtapi.ini file
exists in the classpath, the default settings get used to create this object.
The parameters used by Cisco Jtapi are read in and frozen when the first
getProvider () call is made.

2-122 OL-7242-02
Member Summary
Methods
java.lang.String getAlarmServiceHostname()
get the alarm service host name
int getAlarmServicePort()
get the port number for the alarm service
int getCtiRequestTimeout()
get the timout for cti requests, other than the provider
open (seconds)
java.lang.String[] getDebuggingNames()
get names of supported debugging level jtapi traces
boolean getDebuggingValue(String)
get the enabled or disabled state of a debugging level
trace
int getDesiredServerHeartbeatInterval()
get the desired interval at which the CTI Manager must
send heartbeats to JTAPI (seconds).
java.lang.String getFileNameBase()
the filename for individual log files.
java.lang.String getFileNameExtension()
get the filename extension for log files
int getNumTraceFiles()
number of trace files before rollover
boolean getPeriodicWakeupEnabled()
get the enabled state of periodic wake up
int getPeriodicWakeupInterval()
get the interval for periodic wakeup (milliseconds)
int getProviderOpenRequestTimeout()
get the timout for a provider open request (seconds)
int getProviderRetryInterval()
get the interval at which the connection to the CTI
Manager will ge retried (seconds)
int getQueueSizeThreshold()
get the threshold for the event queue size to trigger
alarms
boolean getQueueStatsEnabled()
get the enabled state of event queue stats
int getRouteSelectTimeout()
get the route select timeout (milliseconds)
java.lang.String[] getServices()
Returns the services that this implementation supports.
java.lang.String getSyslogCollector()
get the syslog collector hostname

OL-7242-02 2-123
Member Summary
int getSyslogCollectorUDPPort()
get the syslog collector UDP port
java.lang.String getTraceDirectory()
the directory in the path where trace files will be
written
int getTraceFileSize()
the size of the tracefiles before rollover
java.lang.String[] getTraceNames()
get the names of supported jtapi traces
java.lang.String getTracePath()
get the path where the trace files will be located
boolean getTraceValue(String)
get the enabled or disabled state of a trace
boolean getUseAlarmService()
get the enabled/disabled state of the alarm service
boolean getUseFileTrace()
get the enabled or disabled state of jtapi log file
tracing
boolean getUseJavaConsoleTrace()
get the enabled or disabled state of jtapi console
tracing
boolean getUseSameDir()
if UseSameDir is true this will cause the traces to go to
a single directory.
boolean getUseSyslog()
get the enabled or disabled state of syslog tracing
void setAlarmServiceHostname(String)
set the alarm service host name
void setAlarmServicePort(int)
set the port number the alarm service is listening on
void setCtiRequestTimeout(int)
set the timeout for cti requests other than provider open
(seconds)
void setDebuggingValue(String, boolean)
enable or disable a particular debugging level trace
void setDesiredServerHeartbeatInterval(int)
set the desired interval at which the CTI Manager must
send heartbeats to JTAPI (seconds).
void setFileNameBase(String)
set the filename for log files
void setFileNameExtension(String)
set the filename extension for log files
void setNumTraceFiles(int)
set the number of trace files before rollover

2-124 OL-7242-02
Member Summary
void setPeriodicWakeupEnabled(boolean)
set the enable/disable state for periodic wake up
void setPeriodicWakeupInterval(int)
set the periodic wake up interval (milliseconds)
void setProviderOpenRequestTimeout(int)
set the timeout for a provider open request (seconds)
void setProviderRetryInterval(int)
set the interval at which the connection to the CTI
Manager will ge retried (seconds)
void setQueueSizeThreshold(int)
set the threshold for the event queue size to trigger
alarms
void setQueueStatsEnabled(boolean)
enable / disable event queue statistics
void setRouteSelectTimeout(int)
set the route select timeout milliseconds
void setServices(String[])
set a list of available services
void setSyslogCollector(String)
set the syslog collector hostname
void setSyslogCollectorUDPPort(int)
set the syslog collector UDP port
void setTraceDirectory(String)
set the directory where jtapi trace files should be
written
void setTraceFileSize(int)
set the size of the trace file
void setTracePath(String)
set the directory root where jtapi traces will be written
void setTraceValue(String, boolean)
enable or disable a particular trace
void setUseAlarmService(boolean)
enable the alarm service
void setUseFileTrace(boolean)
enable or disable jtapi log file tracing
void setUseJavaConsoleTrace(boolean)
enable or disable jtapi console tracing
void setUseSameDir(boolean)
if UseSameDir is true this will cause the traces to go to
a single directory.
void setUseSyslog(boolean)
enable or disable syslog tracing

OL-7242-02 2-125
Methods
getAlarmServiceHostname()
public java.lang.String getAlarmServiceHostname()
get the alarm service host name
getAlarmServicePort()
public int getAlarmServicePort()
get the port number for the alarm service
getCtiRequestTimeout()
public int getCtiRequestTimeout()
get the timout for cti requests, other than the provider open (seconds)
getDebuggingNames()
public java.lang.String[] getDebuggingNames()
get names of supported debugging level jtapi traces
getDebuggingValue(String)
public boolean getDebuggingValue(java.lang.String debuggingName)
get the enabled or disabled state of a debugging level trace
getDesiredServerHeartbeatInterval()
public int getDesiredServerHeartbeatInterval()
get the desired interval at which the CTI Manager must send heartbeats to
JTAPI (seconds). The actual interval is decided by the server at connect time.
getFileNameBase()
public java.lang.String getFileNameBase()
the filename for individual log files.

2-126 OL-7242-02
getFileNameExtension()
public java.lang.String getFileNameExtension()
get the filename extension for log files
getNumTraceFiles()
public int getNumTraceFiles()
number of trace files before rollover
getPeriodicWakeupEnabled()
public boolean getPeriodicWakeupEnabled()
get the enabled state of periodic wake up
getPeriodicWakeupInterval()
public int getPeriodicWakeupInterval()
get the interval for periodic wakeup (milliseconds)
getProviderOpenRequestTimeout()
public int getProviderOpenRequestTimeout()
get the timout for a provider open request (seconds)
getProviderRetryInterval()
public int getProviderRetryInterval()
get the interval at which the connection to the CTI Manager will ge retried
(seconds)
getQueueSizeThreshold()
public int getQueueSizeThreshold()
get the threshold for the event queue size to trigger alarms
getQueueStatsEnabled()
public boolean getQueueStatsEnabled()
get the enabled state of event queue stats

OL-7242-02 2-127
getRouteSelectTimeout()
public int getRouteSelectTimeout()
get the route select timeout (milliseconds)
getServices()
public java.lang.String[] getServices()
Returns the services that this implementation supports. Note: This is a static
list administered in the jtapi.ini file. There is no automatic discovery
mechanism to locate available cti services
getSyslogCollector()
public java.lang.String getSyslogCollector()
get the syslog collector hostname
getSyslogCollectorUDPPort()
public int getSyslogCollectorUDPPort()
get the syslog collector UDP port
getTraceDirectory()
public java.lang.String getTraceDirectory()
The directory in the path where trace files will be written
getTraceFileSize()
public int getTraceFileSize()
The size of the tracefiles before rollover
getTraceNames()
public java.lang.String[] getTraceNames()
get the names of supported jtapi traces
getTracePath()
public java.lang.String getTracePath()
get the path where the trace files will be located

2-128 OL-7242-02
getTraceValue(String)
public boolean getTraceValue(java.lang.String traceName)
get the enabled or disabled state of a trace
getUseAlarmService()
public boolean getUseAlarmService()
get the enabled/disabled state of the alarm service
getUseFileTrace()
public boolean getUseFileTrace()
get the enabled or disabled state of jtapi log file tracing
getUseJavaConsoleTrace()
public boolean getUseJavaConsoleTrace()
get the enabled or disabled state of jtapi console tracing
getUseSameDir()
public boolean getUseSameDir()
if UseSameDir is true this will cause the traces to go to a single directory.

Otherwise each instance of a jtapi application will cause the traces to go to a
separate directory, indexed in sequence from the last directory written or
available.
getUseSyslog()
public boolean getUseSyslog()
get the enabled or disabled state of syslog tracing
setAlarmServiceHostname(String)
public void setAlarmServiceHostname(java.lang.String hostname)
set the alarm service host name

OL-7242-02 2-129
setAlarmServicePort(int)
public void setAlarmServicePort(int portNumber)
set the port number the alarm service is listening on
setCtiRequestTimeout(int)
public void setCtiRequestTimeout(int seconds)
set the timeout for cti requests other than provider open (seconds)
setDebuggingValue(String, boolean)
public void setDebuggingValue(java.lang.String debuggingName,
boolean value)
enable or disable a particular debugging level trace
setDesiredServerHeartbeatInterval(int)
public void setDesiredServerHeartbeatInterval(int seconds)
set the desired interval at which the CTI Manager must send heartbeats to
JTAPI (seconds). The actual interval is decided by the server at connect time.
setFileNameBase(String)
public void setFileNameBase(java.lang.String base)
set the filename for log files
setFileNameExtension(String)
public void setFileNameExtension(java.lang.String extn)
set the filename extension for log files
setNumTraceFiles(int)
public void setNumTraceFiles(int val)
set the number of trace files before rollover
setPeriodicWakeupEnabled(boolean)
public void setPeriodicWakeupEnabled(boolean enabled)
set the enable/disable state for periodic wake up

2-130 OL-7242-02
setPeriodicWakeupInterval(int)
public void setPeriodicWakeupInterval(int milliseconds)
set the periodic wake up interval (milliseconds)
setProviderOpenRequestTimeout(int)
public void setProviderOpenRequestTimeout(int seconds)
set the timeout for a provider open request (seconds)
setProviderRetryInterval(int)
public void setProviderRetryInterval(int seconds)
set the interval at which the connection to the CTI Manager will ge retried
(seconds)
setQueueSizeThreshold(int)
public void setQueueSizeThreshold(int size)
set the threshold for the event queue size to trigger alarms
setQueueStatsEnabled(boolean)
public void setQueueStatsEnabled(boolean enabled)
enable / disable event queue statistics
setRouteSelectTimeout(int)
public void setRouteSelectTimeout(int milliseconds)
set the route select timeout milliseconds
setServices(String[])
public void setServices(java.lang.String[] services)
set a list of available services
setSyslogCollector(String)
public void setSyslogCollector(java.lang.String value)
set the syslog collector hostname

OL-7242-02 2-131
setSyslogCollectorUDPPort(int)
public void setSyslogCollectorUDPPort(int port)
set the syslog collector UDP port
setTraceDirectory(String)
public void setTraceDirectory(java.lang.String dir)
set the directory where jtapi trace files should be written
setTraceFileSize(int)
public void setTraceFileSize(int val)
set the size of the trace file
setTracePath(String)
public void setTracePath(java.lang.String path)
set the directory root where jtapi traces will be written
setTraceValue(String, boolean)
public void setTraceValue(java.lang.String traceName,
boolean value)
enable or disable a particular trace
setUseAlarmService(boolean)
public void setUseAlarmService(boolean value)
enable the alarm service
setUseFileTrace(boolean)
public void setUseFileTrace(boolean value)
enable or disable jtapi log file tracing
setUseJavaConsoleTrace(boolean)
public void setUseJavaConsoleTrace(boolean value)
enable or disable jtapi console tracing

2-132 OL-7242-02
CiscoJtapi Version
setUseSameDir(boolean)
public void setUseSameDir(boolean value)
if UseSameDir is true this will cause the traces to go to a single directory.

Otherwise each instance of a jtapi application will cause the traces to go to a
separate directory, indexed in sequence from the last directory written or
available.
setUseSyslog(boolean)
public void setUseSyslog(boolean value)
enable or disable syslog tracing
CiscoJtapi Version
Declaration
public class CiscoJtapiVersion
java.lang.Object
|
+--com.cisco.jtapi.extensions.CiscoJtapiVersion
Description
This class gives the version information of the installed Cisco JTAPI. Programs
can get the version number using the accessor methods. Cisco JTAPI Version is in
a.b(x.y) format where a indicates the major version b indicates the minor version
x indicates the revision number y indicates the build number
Member Summary
Constructors
CiscoJtapiVersion()

OL-7242-02 2-133
CiscoJtapi Version
Member Summary
Methods
java.lang.String getBuildDescription()
Returns ’release’ if it is a release version or debug if
it is not a release version
int getBuildNumber()
This returns the build number of the version
int getMajorVersion()
This method returns the major version number
int getMinorVersion()
This method returns the minor version number
int getRevisionNumber()
This method returns the revision number of the version
java.lang.String getVersion()
returns the version information in a.b(x.y) format
without name

Constructors
CiscoJtapiVersion()
public CiscoJtapiVersion()
Methods
getBuildDescription()
public java.lang.String getBuildDescription()
Returns ’release’ if it is a release version or debug if it is not a release version

2-134 OL-7242-02
CiscoJtapi Version
getBuildNumber()
public int getBuildNumber()
This returns the build number of the version
getMajorVersion()
public int getMajorVersion()
This method returns the major version number
getMinorVersion()
public int getMinorVersion()
This method returns the minor version number
getRevisionNumber()
public int getRevisionNumber()
This method returns the revision number of the version
getVersion()
public java.lang.String getVersion()
returns the version information in a.b(x.y) format without name
toString()

Overrides:
toString in class Object

OL-7242-02 2-135
CiscoMediaCapability
Declaration
public class CiscoMediaCapability
java.lang.Object
|
Direct Known Subclasses

CiscoG711MediaCapability, CiscoG723MediaCapability,
CiscoG729MediaCapability, CiscoGSMMediaCapability,
CiscoWideBandMediaCapability
Description
The CiscoMediaCapability object specifies the properties of a particular
media format that an application can support for CiscoMediaTerminals that
it registers. Because CiscoMediaCapability is an abstract class,
applications may only construct its subclasses directly.
See Also:
CiscoG711MediaCapability, CiscoG723MediaCapability,
CiscoG729MediaCapability, CiscoGSMMediaCapability,
CiscoRTPBitRate, CiscoRTPPayload
Member Summary
Fields
static G711_64K_30_MILLISECONDS
CiscoMediaCapability G.711 capability with default parameters
static G723_6K_30_MILLISECONDS

2-136 OL-7242-02
Member Summary
static G729_30_MILLISECONDS
static GSM_80_MILLISECONDS
CiscoMediaCapability GSM capability with default parameters
static WIDEBAND_256K_10_MILLISECONDS
CiscoMediaCapability Wide band capability with default parameters
Constructors
CiscoMediaCapability(int, int), int maxFramesPerPacket)
Constructs a CiscoMediaCapability object for the
specified payload type and packet size.
Methods
int getMaxFramesPerPacket()
Returns the packet size specified by this object.
int getPayloadType()
Returns the payload type specified by this object.
boolean isSupported()
Returns whether the payload of this object gets supported
or not.

Fields
G711_64K_30_MILLISECONDS
public static final
com.cisco.jtapi.extensions.CiscoMediaCapability
G.711 capability with default parameters

OL-7242-02 2-137
See Also:
public static final
See Also:
G729_30_MILLISECONDS
public static final
G729_30_MILLISECONDS
See Also:
GSM_80_MILLISECONDS
public static final
GSM_80_MILLISECONDS
GSM capability with default parameters
See Also:
WIDEBAND_256K_10_MILLISECONDS
public static final
WIDEBAND_256K_10_MILLISECONDS

2-138 OL-7242-02
Wideband capability with default parameters
See Also:
Constructors
CiscoMediaCapability(int, int)
public CiscoMediaCapability(int payloadType,
int maxFramesPerPacket)
Constructs a CiscoMediaCapability object for the specified payload

type and packet size.
Methods
getMaxFramesPerPacket()
public int getMaxFramesPerPacket()
Returns the packet size specified by this object.

Returns:
the packet size, specified as a the number of frames within a single packet
getPayloadType()
public int getPayloadType()
Returns the payload type specified by this object.

Returns:
a payload type from the RTPPayload interface
isSupported()
public boolean isSupported()
Returns whether the payload of this object is supported or not.

Returns:

OL-7242-02 2-139
CiscoMediaOpenLogicalChannelEv
true if the payloadType gets supported; otherwise, false.
toString()
Overrides:
Declaration
public interface CiscoMediaOpenLogicalChannelEv extends CiscoTermEv

CiscoEv, CiscoTermEv, javax.telephony.events.Ev,
javax.telephony.events.TermEvDescription
Description
The CiscoMediaOpenLogicalChannelEv event is sent each time when media is
established for dynamically registered CiscoMediaTerminals or
CiscoRouteTerminals. Upon receiving this event applications must invoke
setRTPParams on CiscoMediaTerminal or CiscoRouteTerminal and pass in
ipAddress and port number where to terminate media along with rtpHandle that
is delivered in this event. Applications can get call reference using
CiscoProvider.getCall(CiscoRTPHandle). Applications need to be aware that the
far end and local end may not be able to invoke features unless setRTPParams
method is invoked. If applications fail to respond to this event within specified
time, the call may be disconnected.

2-140 OL-7242-02
Member Summary
Fields
static int ID
Methods
CiscoRTPHandle getCiscoRTPHandle()
Returns CiscoRTPHandle object.
int getPacketSize()
following constants.
Fields
ID
Methods
getCiscoRTPHandle()
public com.cisco.jtapi.extensions.CiscoRTPHandle
getCiscoRTPHandle()
Returns CiscoRTPHandle object. Applications should pass this handle along

with RTP Parameters to CiscoMediaTerminal or CiscoRouteTerminal.
Applications can get call reference using CiscoProvider.getCall. If there is no
callobserver or there was no callobserver when this event gets delivered, then
CiscoProvider.getCall may return null.
Returns:
CiscoRTPHandle
See Also:
CiscoRTPParams
getPacketSize()
public int getPacketSize()

OL-7242-02 2-141

Returns:
packet size, in milliseconds
getPayLoadType()
public int getPayLoadType()
Returns the payload format of the far end, one of the following constants:
• CiscoRTPPayload.NONSTANDARD
• CiscoRTPPayload.G711ALAW64K
• CiscoRTPPayload.G711ULAW64K
• CiscoRTPPayload.G722_64K
• CiscoRTPPayload.G7231
• CiscoRTPPayload.G729ANNEXA
• CiscoRTPPayload.IS11172AUDIOCAP
• CiscoRTPPayload.ACY_G729AASSN
• CiscoRTPPayload.DATA64
• CiscoRTPPayload.GSM
• CiscoRTPPayload.ACTIVEVOICE
Returns:
payload type

2-142 OL-7242-02
CiscoMediaTerminal
CiscoMediaTerminal
Declaration
public interface CiscoMediaTerminal extends CiscoTerminal
All Superinterfaces
CiscoObjectContainer, CiscoTerminal, javax.telephony.Terminal
Description
A CiscoMediaTerminal is a special kind of CiscoTerminal that allows
applications to terminate RTP media streams. Unlike a CiscoTerminal, a
CiscoMediaTerminal does not represent a physical telephony endpoint, which is
observable and controllable in a third-party manner. Instead, a
CiscoMediaTerminal is a logical telephony endpoint, which may be associated
with any application that desires to terminate media. Such applications include
voice mail systems, interactive voice response (IVR), and “soft” phones.
Note Only CTIPorts appear as CiscoMediaTerminals through JTAPI.
Terminating media is a two-step process. To terminate media for a particular

terminal, an application adds an observer that implements the
CiscoTerminalObserver interface using the Terminal.addObserver
method. Finally, the application registers its IP address and port number to which
the Terminal’s incoming RTP streams are to be directed using the
CiscoMediaTerminal.register method.
See Also:
CiscoTerminal

OL-7242-02 2-143
CiscoMediaTerminal
Member Summary
Methods
void changeRTPDefaults(InetAddress, int)
Changes the default registration parameters to specified
address and port.
This method returns true if the CiscoMediaTerminal is
registered and false otherwise.
void register(InetAddress, int, CiscoMediaCapability[])
The CiscoMediaTerminal must be in the
CiscoTerminal.UNREGISTERED state and its Provider must be
void register(InetAddress, int)
Registers a Terminal with the specified address and port,
defaulting to G.711 64KHz u-law encoding with a thirty
millisecond packet size.
void register(CiscoMediaCapability[], int)
void register(InetAddress, int, CiscoMediaCapability[], int)
void setRTPParams(CiscoRTPHandle, CiscoRTPParams)
Application can set ipAddress and RTPPort number to
void unregister()
The CiscoMediaTerminal must be registered and its
Provider must be in the Provider.IN_SERVICE state.

Fields inherited from interface CiscoTerminal
IN_SERVICE, OUT_OF_SERVICE

Methods inherited from interface CiscoTerminal

2-144 OL-7242-02
CiscoMediaTerminal

getFilter(), getRTPInputProperties(), getRTPOutputProperties(), getRegistrationState(),
getState(), sendData(byte[]), sendData(String), setFilter(CiscoTermEvFilter),
sendData(String), unPark(Address, String)
Methods inherited from interface Terminal

addCallObserver(CallObserver), addObserver(TerminalObserver), getAddresses(),
getCallObservers(), getCapabilities(), getName(), getObservers(), getProvider(),
getTerminalCapabilities(Terminal, Address), getTerminalConnections(),
removeCallObserver(CallObserver), removeObserver(TerminalObserver)
Methods
changeRTPDefaults(InetAddress, int)
public void changeRTPDefaults(java.net.InetAddress address,
int port)
throws CiscoRegistrationException
Changes the default registration parameters to specified address and port.

Only Registered application may invoke this method.
Parameters:
address - the internet address for inbound RTP streams on this
terminal
port - the UDP port for inbound RTP streams on this terminal
Throws:
CiscoRegistrationException
isRegistered()
public boolean isRegistered()
This method returns true if the CiscoMediaTerminal is registered and false

otherwise.

OL-7242-02 2-145
CiscoMediaTerminal
isRegisteredByThisApp()
public boolean isRegisteredByThisApp()
This method returns true if this application issued a successful registration
request. This if valid even if device is out of service because of CTIManager
failure. This will be set to true until this application unregisters the device.
register(CiscoMediaCapability[], int)
public void
register(com.cisco.jtapi.extensions.CiscoMediaCapability[]
capabilities, int failureCloseDelay) throws
The CiscoMediaTerminal must be in the CiscoTerminal.UNREGISTERED

state and its Provider must be in the Provider.IN_SERVICE state. The
successful effect of this method is to register the MediaTerminal. Registers a
Terminal with specified CiscoMediaCapabilities. Indicates that application is
interested in supplying ipAddress and port dynamically for each call.
Applications registering with this method will receive
CiscoMediaOpenLogicalChannelEv for each call and will have to supply
ipAddress and port number using setRTPParams method on
CiscoTerminalConnection.
Method Arguments
Arguments indicate the type of RTP encodings that the application is willing
to support for this Terminal and the application or CTIManager failure
persistence delay
Method Post-conditions
This method returns successfully when the CiscoMediaTerminal is
registered.
Parameters:
capabilities - the list of RTP encodings supported by this terminal
failureCloseDelay - persistence delay seconds on application or
CTIManager failure
Throws:
See Also:

2-146 OL-7242-02
CiscoMediaTerminal
register(InetAddress, int)
public void register(java.net.InetAddress address, int port
Deprecated.
Registers a Terminal with the specified address and port, defaulting to
G.711 64KHz u-law encoding with a thirty millisecond packet size.
Parameters:
terminal
Throws:
register(InetAddress, int, CiscoMediaCapability[])

public void register(java.net.InetAddress address, int port,
com.cisco.jtapi.extensions.CiscoMediaCapability[] capabilities)

CiscoTerminal.UNREGISTERED state and its Provider must be in the
Provider.IN_SERVICE state. The successful effect of this method is to
register the MediaTerminal.
Method Arguments
This method has three arguments. The first argument specifies the internet
address at which the RTP media stream for this Terminal will be terminated,
the second indicates the UDP port at which RTP packets will be directed, and
the final argument indicates the type of RTP encodings that the application is
willing to support for this Terminal.
This method returns successfully when the MediaTerminal is registered.

OL-7242-02 2-147
CiscoMediaTerminal
Parameters:
terminal
Throws:
register(InetAddress, int, CiscoMediaCapability[], int)

public void register(java.net.InetAddress address, int port,
com.cisco.jtapi.extensions.CiscoMediaCapability[] capabilities,
int failureCloseDelay) throws CiscoRegistrationException
The CiscoMediaTerminal must be in the CiscoTerminal.UNREGISTERED

successful effect of this method is to register the MediaTerminal.
Method Arguments
This method has four arguments. The first argument specifies the internet
address at which the RTP media stream for this Terminal will be terminated,
the second indicates the UDP port at which RTP packets will be directed, the
third argument indicates the type of RTP encodings that the application is
willing to support for this Terminal, and the final argument is the application
or CTIManager failure persistence delay
This method returns successfully when the MediaTerminal is registered.
Parameters:
address - the internet address for inbound RTP streams on this terminal
CTIManager failure
Throws:

2-148 OL-7242-02
CiscoMediaTerminal
setRTPParams(CiscoRTPHandle, CiscoRTPParams)
public void
setRTPParams(com.cisco.jtapi.extensions.CiscoRTPHandle0 rtpHandle,
com.cisco.jtapi.extensions.CiscoRTPParams rtpParams)
throws InvalidStateException, InvalidArgumentException,
PrivilegeViolationException
Applications can set ipAddress and RTP Port number to dynamically stream
media for a call. In order to do this, applications will have to register
MediaTerminal or CiscoRouteTeminal by providing only capabilities.
Applications will have to invoke this method upon receiving
CiscoCallOpenLogicalChannel on terminalObserver. Applications need to
pass in rtpHandle that is received in CiscoCallOpenLogicalChannelEv.
Applications can get CiscoCall reference using
CiscoProvider.getRTPHandle(rtpHandle) method. This may return null if
either no callobserver is added on the terminal or no callobserver at the time
when this event was sent or there is no call associated with this handle.
Throws:
See Also:
CiscoRTPParams
unregister()
public void unregister()
throws CiscoUnregistrationException
The CiscoMediaTerminal must not be registered and its Provider must be in
the Provider.IN_SERVICE state. The successful effect of this method is
to unregister the MediaTerminal.
This method returns successfully when the MediaTerminal is unregistered.
Throws:

OL-7242-02 2-149
Declaration
public interface CiscoObjectContainer

CiscoAddress, CiscoCall, CiscoCallID, CiscoConnection,
CiscoConnectionID, CiscoConsultCall, CiscoJtapiPeer,
CiscoMediaTerminal, CiscoProvider, CiscoTerminal,
CiscoTerminalConnection
Description
The ApplicationObject interface allows applications to associate an
application defined object to objects that implement this interface.
Member Summary
Methods
java.lang.Object getObject()
Gets the application-defined object.
java.lang.Object setObject(Object)
Sets an application-defined object.
Methods
getObject()
public java.lang.Object getObject()
Gets the application-defined object.

2-150 OL-7242-02
CiscoOutOfServiceEv
Returns:
setObject(Object)
public java.lang.Object setObject(java.lang.Object reference)
Sets an application-defined object.

Returns:
the CallManagerID property of this Call
CiscoOutOfServiceEv
Declaration
public interface CiscoOutOfServiceEv extends CiscoEv
All Superinterfaces
CiscoEv, javax.telephony.events.Ev

CiscoAddrOutOfServiceEv, CiscoTermOutOfServiceEv
Description
The CiscoAddrOutOfServiceEv event
Member Summary
Fields

OL-7242-02 2-151
CiscoOutOfServiceEv
Member Summary
static int CAUSE_CALLMANAGER_FAILURE
static int CAUSE_DEVICE_FAILURE
static int CAUSE_DEVICE_UNREGISTERED
static int CAUSE_NOCALLMANAGER_AVAILABLE
static int CAUSE_REHOME_TO_HIGHER_PRIORITY_CM
static int CAUSE_REHOMING_FAILURE
static int ID

META_UNKNOWN

Fields
CAUSE_CALLMANAGER_FAILURE
public static final int CAUSE_CALLMANAGER_FAILURE
CAUSE_CTIMANAGER_FAILURE
public static final int CAUSE_CTIMANAGER_FAILURE
CAUSE_DEVICE_FAILURE
public static final int CAUSE_DEVICE_FAILURE
CAUSE_DEVICE_UNREGISTERED
public static final int CAUSE_DEVICE_UNREGISTERED

2-152 OL-7242-02
CiscoProvCallParkEv
CAUSE_NOCALLMANAGER_AVAILABLE
public static final int CAUSE_NOCALLMANAGER_AVAILABLE
CAUSE_REHOME_TO_HIGHER_PRIORITY_CM
public static final int CAUSE_REHOME_TO_HIGHER_PRIORITY_CM
CAUSE_REHOMING_FAILURE
public static final int CAUSE_REHOMING_FAILURE
ID
CiscoProvCallParkEv
Declaration
public interface CiscoProvCallParkEv extends CiscoProvFeatureEv
All Superinterfaces
CiscoEv, CiscoProvEv, CiscoProvFeatureEv,
javax.telephony.events.Ev,
Description
The CiscoProvCallParkEv event is delivered to the provider observer when a call
is parked by any device in the cluster. To receive this event the application should
register using CiscoProvider.registerFeature() and
CiscoProvFeatureID.MONITOR_CALLPARK_DN. The user profile used by the
application should have the “Call Park Retrieval Allowed” flag enabled to receive
this event.

OL-7242-02 2-153
CiscoProvCallParkEv
Member Summary
Fields
static int ID
static int PARK_STATE_ACTIVE
Indicates that a call is parked
static int PARK_STATE_IDLE
Indicates that a call is unparked
static int REASON_CALLPARK
This event is due to call park
static int REASON_CALLPARKREMAINDER
This event is due to call park remainder
static int REASON_CALLUNPARK
This event is due to call being unparked
Methods
int getintCallIDValue()
Returns an integer representation of this object
java.lang.String getParkDN()
This returns where the call is parked
java.lang.String getParkedParty()
This returns the DN of the parked party
java.lang.String getParkingParty()
This returns the DN of the parking party
int getReason()
This returns the reason of the event.
int getState()
This returns the state of the call Possible states are
CiscoProvCallParkEv.PARK_STATE_IDLE
CiscoProvCallParkEv.PARK_STATE_ACTIVE

META_UNKNOWN
Methods inherited from interface CiscoProvFeatureEv

getFeatureID()


2-154 OL-7242-02
CiscoProvCallParkEv

getProvider()
Fields
ID
PARK_STATE_ACTIVE
public static final int PARK_STATE_ACTIVE
Indicates that a call is parked
PARK_STATE_IDLE
public static final int PARK_STATE_IDLE
Indicates that a call is unparked
REASON_CALLPARK
public static final int REASON_CALLPARK
This event is due to call park
REASON_CALLPARKREMAINDER
public static final int REASON_CALLPARKREMAINDER
This event is due to call park remainder
REASON_CALLUNPARK
public static final int REASON_CALLUNPARK
This event is due to call being unparked

OL-7242-02 2-155
CiscoProvCallParkEv
Methods
getintCallIDValue()
public int getintCallIDValue()
Returns an integer representation of this object
getParkDN()
public java.lang.String getParkDN()
This returns where the call is parked
getParkedParty()
public java.lang.String getParkedParty()
This returns the DN of the parked party
getParkingParty()
public java.lang.String getParkingParty()
This returns the DN of the parking party
getReason()
public int getReason()
This returns the reason of the event. Possible states include the following:
CiscoProvCallParkEv.REASON_CALLPARK
CiscoProvCallParkEv.REASON_CALLUNPARK
CiscoProvCallParkEv.REASON_CALLPARKREMAINDER
getState()
This returns the state of the call Possible states include the following:
CiscoProvCallParkEv.PARK_STATE_IDLE
CiscoProvCallParkEv.PARK_STATE_ACTIVE

2-156 OL-7242-02
CiscoProvEv
CiscoProvEv
Declaration
public interface CiscoProvEv extends CiscoEv,
All Superinterfaces
CiscoEv, javax.telephony.events.Ev,

CiscoAddrAddedToTerminalEv, CiscoAddrCreatedEv,
CiscoAddrRemovedEv, CiscoProvCallParkEv, CiscoProvFeatureEv,
CiscoProvFeatureUnRegisteredEv, CiscoTermCreatedEv,
CiscoTermRemovedEv
Description
The CiscoProvEv interface, which extends JTAPI’s core
javax.telephony.events.ProvEv interface, serves as the base interface
for all Cisco-extended JTAPI Provider events. Every Provider-related event in this
package extends this interface, directly or indirectly.
See Also:


OL-7242-02 2-157
CiscoProvFeatureEv

META_UNKNOWN


getProvider()
CiscoProvFeatureEv
Declaration
public interface CiscoProvFeatureEv extends CiscoProvEv
All Superinterfaces

2-158 OL-7242-02
CiscoProvFeatureEv

CiscoProvCallParkEv
Member Summary
Methods
int getFeatureID()
Feature ID for which application is interested in
receiving events

META_UNKNOWN


getProvider()
Methods
getFeatureID()
public int getFeatureID()
Feature ID for which application is interested in receiving events

OL-7242-02 2-159
CiscoProvFeatureID
CiscoProvFeatureID
Declaration
public interface CiscoProvFeatureID
Description
This interface lists the features supported by the registerFeature interface.
Member Summary
Fields
static int MONITOR_CALLPARK_DN
Fields
MONITOR_CALLPARK_DN
public static final int MONITOR_CALLPARK_DN
This feature ID is used with registerFeature interface in CiscoProvider to

receive CiscoProvCallParkEv when a call is parked or unparked from any
device in the cluster.
CiscoProvFeatureUnRegisteredEv
Declaration
public interface CiscoProvFeatureUnRegisteredEv extends CiscoProvEv

2-160 OL-7242-02
All Superinterfaces
Description
The CiscoProvFeatureUnRegisteredEv event This event indicates the
unregistration of a particular feature by Cisco CallManager
Member Summary
Fields
static int ID
Methods
int getFeatureID()
FeatureID for which application will no longer receive
events

META_UNKNOWN


getProvider()

OL-7242-02 2-161
Fields
ID

2-162 OL-7242-02
CiscoProvider
Methods
getFeatureID()
public int getFeatureID()
FeatureID for which application will no longer receive events
CiscoProvider
Declaration
public interface CiscoProvider extends javax.telephony.Provider,
All Superinterfaces
CiscoObjectContainer, javax.telephony.Provider
Description
Member Summary
Methods
CiscoTerminal createTerminal(java.lang.String name)
Returns an instance of the CiscoTerminal class which
corresponds to the given name.
void deleteCall(Call)
Deletes an unused call created by createCall().
void deleteTerminal(com.cisco.jtapi.extensions.CiscoTerminal
terminal)
Removes the CiscoTerminal Ojbect from providers control.
CiscoCall getCall(CiscoRTPHandle)
Returns call object with the rtpHandle associated with a
specific terminal.

OL-7242-02 2-163
CiscoProvider
Member Summary
boolean getCallbackGuardEnabled()
Returns the current state of the callback guard feature
CiscoMediaTerminal getMediaTerminal(String)
Returns an instance of the CiscoMediaTerminal class which
corresponds to the given name.
CiscoMediaTerminal[] getMediaTerminals()
Returns an array of CiscoMediaTerminals associated with
the Provider and within the Provider’s domain.
java.lang.String getVersion()
Returns the current version of provider running if
provider is in service otherwise it will return empty
string
void registerFeature(int)
used to register for a particular feature for which
application will get Provider events.
void setCallbackGuardEnabled(boolean)
Enables or disables try/catch logic for observer
callbacks
void unregisterFeature(int)
used to unregister a particular feature.

Fields inherited from interface Provider
IN_SERVICE, OUT_OF_SERVICE, SHUTDOWN

Methods inherited from interface Provider

2-164 OL-7242-02
CiscoProvider

addObserver(ProviderObserver), createCall(), getAddress(String),
getAddressCapabilities(Terminal), getAddressCapabilities(Terminal), getAddresses(),
getCallCapabilities(Terminal, Address), getCallCapabilities(Terminal, Address),
getCalls(), getCapabilities(), getConnectionCapabilities(Terminal, Address),
getConnectionCapabilities(Terminal, Address), getName(), getObservers(),
getProviderCapabilities(Terminal), getProviderCapabilities(Terminal), getState(),
getTerminal(String), getTerminalCapabilities(Terminal),
getTerminalCapabilities(Terminal), getTerminalConnectionCapabilities(Terminal),
getTerminalConnectionCapabilities(Terminal), getTerminals(),
removeObserver(ProviderObserver), shutdown()
Methods
createTerminal(java.lang.String name)
CiscoTerminal createTerminal(java.lang.String name)
Returns an instance of the CiscoTerminal class which corresponds to the

given name.
deleteCall(Call)
public void deleteCall(javax.telephony.Call call
throws InvalidStateException
Deletes an unused call created by createCall(). An exception is generated if

the call is not in IDLE state or if provider is not in Provider.IN_SERVICE
state. Applications may use this interface to move un used calls to INVALID
state and reclaim resources allocated to the call.
Pre-conditions:
1. this.getState() == Provider.IN_SERVICE
2. call.getState() == Call.IDLE
Post-conditions:
1. call.getState() == Call.INVALID
Throws:

OL-7242-02 2-165
CiscoProvider
deleteTerminal(com.cisco.jtapi.extensions.CiscoTerminal terminal)
void deleteTerminal(com.cisco.jtapi.extensions.CistoTerminal
terminal)
Removes the CiscoTerminal Ojbect from providers control.
getCall(CiscoRTPHandle)
public com.cisco.jtapi.extensions.CiscoCall0
getCall(com.cisco.jtapi.extensions.CiscoRTPHandle rtpHandle)
Returns call object with the rtpHandle associated with a specific terminal.
This method may return null if this rtpHandle is no longer associated with any
call or if there was no callObserver added on the terminal at the time when
CiscoCallOpenLogicalChannelEv which contained this handle gets sent to
applications.
Throws:
getCallbackGuardEnabled()
public boolean getCallbackGuardEnabled()
Returns the current state of the callback guard feature

Returns:
the current state of the callback guard feature
getMediaTerminal(String)
public com.cisco.jtapi.extensions.CiscoMediaTerminal
getMediaTerminal(java.lang.String name
throws InvalidArgumentException
Returns an instance of the CiscoMediaTerminal class which corresponds to

the given name. Each CiscoMediaTerminal has a unique name associated
with it, which is assigned to it by the JTAPI implementation. If no
CiscoMediaTerminal is available for the given name within the Provider’s
domain, this method throws the InvalidArgumentException. This
CiscoMediaTerminal is contained in the arrays generated by
Provider.getTerminals() and
CiscoProvider.getMediaTerminals().

2-166 OL-7242-02
CiscoProvider
Pre-conditions:
1. Let CiscoMediaTerminal terminal = this.getMediaTerminal(name);
2. terminal is an element of this.getTerminals();
3. terminal is an element of this.getMediaTerminals();
Post-conditions:
1. Let CiscoMediaTerminal terminal = this.getMediaTerminal(name);
2. terminal is an element of this.getTerminals();
3. terminal is an element of this.getMediaTerminals();
Parameters:
name - The name of desired CiscoMediaTerminal object.
Returns:
The CiscoMediaTerminal object associated with the given name.
Throws:
javax.telephony.InvalidArgumentException - The name
provided does not correspond to a name of any CiscoMediaTerminal
known to the Provider or within the Provider’s domain.
getMediaTerminals()
public com.cisco.jtapi.extensions.CiscoMediaTerminal[]
getMediaTerminals()
throws ResourceUnavailableException
Returns an array of CiscoMediaTerminals associated with the Provider and

within the Provider’s domain. Each CiscoMediaTerminal possesses a unique
name, which is assigned to it by the JTAPI implementation. If there are no
CiscoMediaTerminals associated with this Provider, then this method returns
null. This array is a subset of the array returned by
Provider.getTerminals().
Post-conditions:
1. Let CiscoMediaTerminal[] terminals = this.getMediaTerminals()
2. terminals == null or terminals.length >= 1
3. if terminals != null, terminals is a subset of this.getTerminals ()
Returns:

OL-7242-02 2-167
CiscoProvider
An array of Terminals in the Provider’s local domain.

Throws:
javax.telephony.ResourceUnavailableException -
Indicates the number of media terminals present in the Provider is too
great to return as a static array.
getVersion()
public java.lang.String getVersion()
Returns the current version of provider running if provider is in service

otherwise it will return empty string
registerFeature(int)
public void registerFeature(int featureID)
throws InvalidStateException, PrivilegeViolationException, Inva
lidArgumentException
used to register for a particular feature for which application will get Provider
events. Applications should pass in the featureID of the softkey. Current
supported features are listed in CiscoProvFeatureID interface
Throws:
setCallbackGuardEnabled(boolean)
public void setCallbackGuardEnabled(boolean enabled)
Enables or disables try/catch logic for observer callbacks

In order to protect itself from application exceptions in observer callbacks,
the Provider normally guards all invocations of application interfaces (e.g.
observers) with the following code:
try {
observer.callStateChanged ( ... );
} catch ( Throwable t ) {
// log the exception here
}

2-168 OL-7242-02
CiscoProvider
This isolates application errors from the JTAPI implementation, allowing

easier troubleshooting, since the JTAPI implementation can note the
unhandled exception and continue operating. Some errors are considered
non-recoverable and will be re-thrown by JTAPI, generally resulting in
application exit. Such errors include ThreadDeath, OutOfMemoryError, and
StackOverflowError. Applications wishing to trap errors within JTAPI
threads should create a subclass of ThreadGroup and initialize JTAPI from a
thread within that ThreadGroup. By overriding the
ThreadGroup.uncaughtException () method, the application can
be made aware of all unrecoverable errors thrown on JTAPI threads.
In some cases, JTAPI aggressive error-catching approach may make it more
difficult to troubleshoot applications within a java debugger. Microsoft Visual
J++ version 6.0, for example, does not handle breakpoints within application
observer callbacks properly if JTAPI catches Throwable. In such cases,
JTAPI application developers may choose to disable the internal JTAPI
try/catch logic.
Note Disabling callback guards in this manner is only intended for use
while troubleshooting applications, and never for use in production
environments. By default, callback guards are always enabled.
Parameters:
enabled - if true, callback guard will be enabled; if false, callback
guard will be disabled
unregisterFeature(int)
public void unregisterFeature(int featureID)
used to unregister a particular feature. Provider events for the feature will
stop after unregistering the feature
Throws:

OL-7242-02 2-169
CiscoProviderCapabilities
CiscoProviderCapabilities
Declaration
public interface CiscoProviderCapabilities extends
javax.telephony.capabilities.ProviderCapabilities
All Superinterfaces
javax.telephony.capabilities.ProviderCapabilities
Description
This interface defines the specific capabilities offered by the Cisco JTAPI
implementation.
Member Summary
Methods
boolean canObserveAnyTerminal()
Enables a user to be provisioned in the Directory to be
able to observe any terminal (and its addresses) in the
system.

Methods inherited from interface ProviderCapabilities
isObservable()

2-170 OL-7242-02
CiscoProviderObserver
Methods
canObserveAnyTerminal()
boolean canOberveAnyTerminal()
Enables a user to be provisioned in the Directory to be able to observe any

Terminal (and its addresses) in the system.
Declaration
public interface CiscoProviderObserver extends
javax.telephony.ProviderObserver
All Superinterfaces
javax.telephony.ProviderObserver
Description
Applications implement this interface in order to receive CiscoProvEv events
such as CiscoAddrCreatedEv and CiscoTermCreatedEv when
observing a Provider via the Provider.addObserver method.
See Also:
CiscoAddrCreatedEv, CiscoTermCreatedEv

Methods inherited from interface ProviderObserver
providerChangedEvent(ProvEv[])

OL-7242-02 2-171
Declaration
public class CiscoRegistrationException extends java.lang.Exception
java.lang.Object
|
+--java.lang.Throwable
|
+--java.lang.Exception
|
+--com.cisco.jtapi.extensions.CiscoRegistrationEx
ception
All Implemented Interfaces

java.io.Serializable
Description
The CiscoMediaTerminal.register method throws this exception when
the registration process fails for any reason. For example, registration would fail
if the Provider were OUT_OF_SERVICE or if the device were already registered.
See Also:
CiscoMediaTerminal.register(InetAddress, int, CiscoMediaCapability[])
Member Summary
Constructors
CiscoRegistrationException()
CiscoRegistrationException(String)

2-172 OL-7242-02
CiscoRouteAddress

Methods inherited from class Throwable

fillInStackTrace(), getLocalizedMessage(), getMessage(), printStackTrace(PrintWriter),
printStackTrace(PrintWriter), printStackTrace(PrintWriter), toString()
Constructors
CiscoRegistrationException()
public CiscoRegistrationException()
CiscoRegistrationException(String)
public CiscoRegistrationException(java.lang.String description)
CiscoRouteAddress
Declaration
public interface CiscoRouteAddress extends
javax.telephony.callcenter.RouteAddress
All Superinterfaces
javax.telephony.Address,
javax.telephony.callcenter.RouteAddress
Member Summary
Methods

OL-7242-02 2-173
CiscoRouteAddress
Member Summary
void registerRouteCallback(RouteCallback, boolean)

Fields inherited from interface RouteAddress
ALL_ROUTE_ADDRESS
Methods inherited from interface Address

addCallObserver(CallObserver), addObserver(AddressObserver),
getAddressCapabilities(Terminal), getCallObservers(), getCapabilities(),
getConnections(), getName(), getObservers(), getProvider(), getTerminals(),
removeCallObserver(CallObserver), removeObserver(AddressObserver)
Methods inherited from interface RouteAddress

cancelRouteCallback(RouteCallback), getActiveRouteSessions(), getRouteCallback(),
registerRouteCallback(RouteCallback)
Methods
registerRouteCallback(RouteCallback, boolean)
public void
registerRouteCallback(javax.telephony.callcenter.RouteCallback
routeCallback,
boolean disableAutoRehoming)throws ResourceUnavailableException
, MethodNotSupportedException
Throws:
javax.telephony.ResourceUnavailableException

2-174 OL-7242-02
CiscoRouteSession
CiscoRouteSession
Declaration
public interface CiscoRouteSession extends
javax.telephony.callcenter.RouteSession
All Superinterfaces
javax.telephony.callcenter.RouteSession
Description
The CiscoRouteSession supports application access to underlying call
associated with a RouteSession. Also, various internal ERRORs where endRoute
is called internally are exposed to the application, should they wish to handle
endRouteEvent() in any special way for these cases.
See Also:
Member Summary
Fields
static int CALLINGADDRESS_SEARCH_SPACE
This indicates that the redirect should be done using the
search space of the calling address.
static int DEFAULT_SEARCH_SPACE
search space that is the default for the implementation.
static int DONOT_RESET_ORIGINALCALLED
This is a parameter for PreferedOriginalCalledOpotion. It
specifies not to reset the OriginalCalled.

OL-7242-02 2-175
CiscoRouteSession
Member Summary
static int ERROR_INVALID_STATE
If an internal InvalidStateException occurred or some
preconditions/post-conditions were not met during routing
endRoute is called with this ERROR_INVALID_STATE error.
static int ERROR_NO_CALLBACK
For now, since there is no default route mechanism in
place, if there is no callback registered for this app,
an endRoute with this error is called.
static int ERROR_NONE
ERRORS defined for internal successful endRoute call.
static int ERROR_ROUTESELECT_TIMEOUT
Each routeEvent()/reRouteEvent() sent starts a timer for
the app to respond with a routeSelect()/ endRoute().
static int RESET_ORIGINALCALLED
A parameter value for PreferedOriginalCalledOption. If
the value of preferedOriginalCalledOption gets set to
this, it resets OriginalCalled to
preferedOriginalCalledNumber.
static int ROUTEADDRESS_SEARCH_SPACE
search space of the route point address.
Methods
javax.telephony.Call getCall()
Returns the call associated with this RouteSession.
void selectRoute(String[], int)
This method overloads the selectRoute method in the
RouteSession interface to allow applications to specify a
calling search space to be used when the call is
redirected to the route destination.
void selectRoute(String[], int, String[])
Selects one or more possible destinations for the routing
of the Call with modifying calling number.
void selectRoute(String[], int, String[], int[])
Selects one or more possible destinations for the routing
of the Call.

Fields inherited from interface RouteSession
CAUSE_INVALID_DESTINATION, CAUSE_NO_ERROR, CAUSE_PARAMETER_NOT_SUPPORTED,
CAUSE_ROUTING_TIMER_EXPIRED, CAUSE_STATE_INCOMPATIBLE, CAUSE_UNSPECIFIED_ERROR,
ERROR_RESOURCE_BUSY, ERROR_RESOURCE_OUT_OF_SERVICE, ERROR_UNKNOWN, RE_ROUTE, ROUTE,
ROUTE_CALLBACK_ENDED, ROUTE_END, ROUTE_USED

2-176 OL-7242-02
CiscoRouteSession

Methods inherited from interface RouteSession
endRoute(int), getCause(), getRouteAddress(), getState(), selectRoute(String[])
Fields
CALLINGADDRESS_SEARCH_SPACE
public static final int CALLINGADDRESS_SEARCH_SPACE
calling address.
DEFAULT_SEARCH_SPACE
public static final int DEFAULT_SEARCH_SPACE
This indicates that the redirect should be done using the search space that is
the default for the implementation. The default is to use the caller’s search
space.
DONOT_RESET_ORIGINALCALLED
public static final int DONOT_RESET_ORIGINALCALLED
This could be parameter value for PreferedOriginalCalled Option, it specifies

not to reset OriginalCalled
ERROR_INVALID_STATE
public static final int ERROR_INVALID_STATE
If an internal InvalidStateException occurred or some

preconditions/postconditions were not met during routing endRoute is called
with this ERROR_INVALID_STATE error.
ERROR_NO_CALLBACK
public static final int ERROR_NO_CALLBACK
For now, since there is no default route mechanism in place, if there is no

callback registered for this app, an endRoute with this error is called.

OL-7242-02 2-177
CiscoRouteSession
ERROR_NONE
public static final int ERROR_NONE
ERRORS defined for internal successful endRoute call. Error value set for no
error.
ERROR_ROUTESELECT_TIMEOUT
public static final int ERROR_ROUTESELECT_TIMEOUT
Each routeEvent()/reRouteEvent() sent starts a timer for the app to respond

with a routeSelect()/ endRoute(). The default value of this timer is 5secs.
Should the application not respond within this time, an endRoute is called
with this error = ERROR_ROUTESELECT_TIMOUT
RESET_ORIGINALCALLED
public static final int RESET_ORIGINALCALLED
This could be parameter value for PreferedOriginalCalled Option, it value of

preferedOriginalCalledOption is set to this, it will reset OriginalCalled to
preferedOriginalCalledNumber
ROUTEADDRESS_SEARCH_SPACE
public static final int ROUTEADDRESS_SEARCH_SPACE
route point address.
Methods
getCall()
public javax.telephony.Call getCall()
Returns the call associated with this RouteSession.

Returns:
the call associated with this RouteSession

2-178 OL-7242-02
CiscoRouteSession
selectRoute(String[], int)
public void selectRoute(java.lang.String[] routeSelected,
int callingSearchSpace)
throws MethodNotSupportedException
This method overloads the selectRoute method in the RouteSession interface

to allow applications to specify a calling search space to be used when the call
is redirected to the route destination.
1. CiscoRouteSession.DEFAULT_SEARCH_SPACE
2. CiscoRouteSession.CALLINGADDRESS_SEARCH_SPACE
3. CiscoRouteSession.ROUTEADDRESS_SEARCH_SPACE
Throws:
javax.telephony.MethodNotSupportedException
selectRoute(String[], int, String[])

public void selectRoute(java.lang.String[] routeSelected, int
callingSearchSpace, java.lang.String[] modifyingCallingNumber)
throws PrivilegeViolationException, MethodNotSupportedException
Selects one or more possible destinations for the routing of the Call with
modifying calling number. This method takes an array of string destination
telephone address names, modifying calling numbers in priority order. The
highest priority destination is the first element in the given array, and routing
is attempted with this destination first with the corresponding element of
modifying calling number. If modifiedCallingNumber is null for an element,
the calling number is not modified, if a call is routed to that particular
routeSelected element.
Successive given destination addresses are attempted until one is found which
does not fail. A RouteUsedEvent event is delivered to the application when a
successful routing destination has been selected and the Call has been routed
to that destination. Pre-conditions:
this.getRouteAddress().getProvider().getState() == Provider.IN_SERVICE
this.getState() == RouteSession.ROUTE or RouteSession.RE_ROUTE
Post-Conditions this.getRouteAddress().getProvider().getState() ==
Provider.IN_SERVICE this.getState() == RouteSession.ROUTE_USED if
Call was successfully routed. RouteUsedEvent is delivered for this
RouteSession if a successful destination was selected.

OL-7242-02 2-179
CiscoRouteSession
Parameters:
routeSelected - A list of possible destinations for the call.
Throws:
MethodNotSupportedExceptionImpl - Routing is not supported by the
implementation. The callingSearchSpace parameter may be:
CiscoRouteSession.DEFAULT_SEARCH_SPACE
CiscoRouteSession.CALLINGADDRESS_SEARCH_SPACE
CiscoRouteSession.ROUTEADDRESS_SEARCH_SPACE
The modifiedCallingNumber may be an array of elements for which
application would like to modify the calling number when call reaches
routeselected element.
selectRoute(String[], int, String[], int[])

public void selectRoute(java.lang.String[] routeSelected, int
callingSearchSpace, java.lang.String[]
preferedOriginalCalledNumber, int[] preferedOrignalCalledOption)
throws PrivilegeViolationException, MethodNotSupportedException
Selects one or more possible destinations for the routing of the Call. This
method takes an array of string destination telephone address names, in
prioritized order and array of string for PreferredOriginalCalled number.
PreferedOriginalCalled number will be selected corresponding to index of
destination telephone name Array. If index corresponding to destination array
is not found in PreferedOriginalCalled number array then
preferedOriginalCalled preferedOriginalCalled will be set to destination.
The highest priority destination is the first element in the given array, and
routing is attempted with this destination first. Successive given destination
addresses are attempted until one is found which does not fail. A
RouteUsedEvent event is delivered to the application when a successful
routing destination has been selected and the Call has been routed to that
destination.

2-180 OL-7242-02
CiscoRouteTerminal
Pre-conditions:
this.getRouteAddress().getProvider().getState() ==
Provider.IN_SERVICE this.getState() == RouteSession.ROUTE or
RouteSession.RE_ROUTE Post-Conditions
this.getRouteAddress().getProvider().getState() ==
Provider.IN_SERVICE this.getState() == RouteSession.ROUTE_USED
if Call was successfully routed. RouteUsedEvent is delivered for this
RouteSession if a successful destination was selected.
Parameters:
routeSelected - A list of possible destinations for the call.
preferedOriginalCalledOption - A list of option each corresponding to
RouteList, this option specifies whether to set OriginalCalled to
preferedOriginalCalledNumber. This takes value
CiscoRouteSession.DONOT_RESET_ORIGINALCALLED,
CiscoRouteSession.RESET_ORIGINALCALLED. If value is not
specified or it is null then, JTAPI will default it to
CiscoRouteSession.DONOT_RESET_ORIGINALCALLED
Throws:
MethodNotSupportedExceptionImpl - Routing is not supported by the
implementation.
CiscoRouteTerminal
Declaration
public interface CiscoRouteTerminal extends CiscoTerminal
All Superinterfaces
CiscoObjectContainer, CiscoTerminal, javax.telephony.Terminal

OL-7242-02 2-181
CiscoRouteTerminal
Description
A CiscoRouteTerminal is a special kind of CiscoTerminal that allows applications
to terminate RTP media streams. Unlike a CiscoTerminal, a CiscoRouteTerminal
does not represent a physical telephony endpoint, which is observable and
controllable in a third-party manner. Instead, a CiscoRouteTerminal is a logical
telephony endpoint, which may be associated with any application that desires to
route calls and also terminate media. Unlike CiscoMediaTerminal,
CiscoRouteTerminal can have multiple active calls at the same time. Typically,
CiscoRouteTerminals will be used to put callers in queue until an agent is
available to service the caller.
Note Only RoutePoint Terminals appear as CiscoRouteTerminal through JTAPI.
Terminating media is a three-step process.

1. Application registers its media capabilities with this terminal using
CiscoRouteTerminal.register method.
2. An application adds an observer that implements CiscoTerminalObserver
interface using the Terminal.addObserver method.
3. Application will either registerRouteCallBack on RouteAddress associated
with this terminal or addCallObserver on CiscoRouteTerminal.
Applications will receive CiscoMediaOpenLogicalChannelEv for each call and
will have to supply ipAddress and port number using setRTPParams method on
Note For no media termination, all applications written for or prior to CiscoJtapiClient
1.4(x) release need to be modified to register with NO_MEDIA_TERMINATION.
Multiple applications can register with same RoutePoint as long as they are
registered with same media capabilities and registrationType. All applications if
registered with CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION and
adds callObserver will receive CiscoMediaOpenLogicalChannelEv but only one
application will be able to invoke setRTPParams.

2-182 OL-7242-02
CiscoRouteTerminal
CiscoRouteTerminals can also be registered with a delayed close. On an

application or CTIManager failure the CallManager persists the
CiscoRouteTerminal resource for the duration of the delay. This allows a back-up
application to recover the route point and take over the call control for it. Calls
that are in an ACCEPTED or CONNECTED state will remain and the back-up
application's CallObserver will be delivered existing call notifications.
See Also:
CiscoTerminal
Member Summary
Fields
static int DYNAMIC_MEDIA_REGISTRATION
Applications that are interested in media termination
need to register with this type and pass in capabilities
that it supports in registration request.
static int NO_MEDIA_REGISTRATION
Applications that are not interested in media termination
need to register with this type and pass in null value
for CiscoMediaCapability in the registration request
Methods
This method returns true only if the CiscoRouteTerminal
is registered
boolean isRegisteredByThisApp()
This method returns true if this application issued a
successful registration request.
void register(CiscoMediaCapability[], int, int)
The CiscoRouteTerminal must be in the
in the Provider.IN_SERVICE state
void setRTPParams(CiscoRTPHandle, CiscoRTPParams)
Applications can set ipAddress and RTP port number to
void unregister()
The CiscoRouteTerminal must be registered and its
Provider must be in the Provider.IN_SERVICE state

OL-7242-02 2-183
CiscoRouteTerminal

Fields inherited from interface CiscoTerminal
IN_SERVICE, OUT_OF_SERVICE

Methods inherited from interface CiscoTerminal

getFilter(), getRTPInputProperties(), getRTPOutputProperties(), getRegistrationState(),
getState(), sendData(byte[]), sendData(byte[]), setFilter(CiscoTermEvFilter),
unPark(Address, String)

Fields
DYNAMIC_MEDIA_REGISTRATION
public static final int DYNAMIC_MEDIA_REGISTRATION
Applications that are interested in media termination need to register with this
type and pass in capabilities that it supports in registration request.
NO_MEDIA_REGISTRATION
public static final int NO_MEDIA_REGISTRATION
Applications that are not interested in media termination need to register with
this type and pass in null value for CiscoMediaCapability in the registration
request.

2-184 OL-7242-02
CiscoRouteTerminal
Methods
isRegistered()
public boolean isRegistered()
This method returns true only if the CiscoRouteTerminal is registered and

false otherwise. If RouteTerminal is OutOfService, this returns false and if it
is InService, it returns true. For CTIManager failure cases, this is false.
isRegisteredByThisApp()
public boolean isRegisteredByThisApp()
This method returns true if this application issued a successful registration

request. This if valid even if device is out of service because of CTIManager
failure. This will be set to true until this application unregisters the device.
register(CiscoMediaCapability[], int, int)

public void
register(com.cisco.jtapi.extensions.CiscoMediaCapability[]
capabilities, int registrationType, int failureCloseDelay)
The CiscoRouteTerminal must be in the CiscoTerminal.UNREGISTERED

successful effect of this method is to register the RouteTerminal. Registers a
Terminal with specified CiscoMediaCapabilities and register type.
1. If registrationType is
CiscoRouteTerminal.NO_MEDIA_REGISTRATION, application
cannot terminate media and can use route point for call routing purpose.
2. If registration Type is
CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION, then app
can terminate media and can have multiple active calls. This Indicates
that application is interested in supplying ipAddress and port
dynamically for each call. Applications registering with this type will
receive CiscoMediaOpenLogicalChannelEv for each call and will have
to supply ipAddress and port number using setRTPParams method on

OL-7242-02 2-185
CiscoRouteTerminal
Method Arguments
Capabilities:
1. indicates the type of RTP encodings that the application is willing to
support for this Terminal. If application is not interested in media
termination, it may pass in null value
Possible RegistrationTypes:
1. CiscoRouteTerminal.NO_MEDIA_REGISTRATION
2. CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION
FailureCloseDelay:
1. A value indicating the number of seconds the persistence is desired.
This method returns successfully when the CiscoRouteTerminal is registered.
Parameters:
registrationType -
CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION or
CiscoRouteTerminal.NO_MEDIA_REGISTRATION
CTIManager failure
setRTPParams(CiscoRTPHandle, CiscoRTPParams)
public void
setRTPParams(com.cisco.jtapi.extensions.CiscoRTPHandle0 rtpHandle,
com.cisco.jtapi.extensions.CiscoRTPParams0 rtpParams)
throws InvalidStateException, InvalidArgumentException,
CiscoCallOpenLogicalChannel on terminalObserver. Applications need to
pass in rtpHandle that is received in CiscoCallOpenLogicalChannelEv

2-186 OL-7242-02
CiscoRouteUsedEvent
Throws:
See Also:
CiscoRTPParams, CiscoMediaOpenLogicalChannelEv
unregister()
public void unregister()
throws CiscoUnregistrationException
The CiscoRouteTerminal must be registered and its Provider must be in the

Provider.IN_SERVICE state. The successful effect of this method is to
unregister the RouteTerminal.
This method returns successfully when the MediaTerminal is unregistered.
Throws:
CiscoUnregistrationException
CiscoRouteUsedEvent
Declaration
public interface CiscoRouteUsedEvent extends
javax.telephony.callcenter.events.RouteUsedEvent
All Superinterfaces
javax.telephony.callcenter.events.RouteSessionEvent
javax.telephony.callcenter.events.RouteUsedEvent

OL-7242-02 2-187
CiscoRouteUsedEvent
Description
The CiscoRouteUsedEvent event interface indicates the RouteSession
interface has moved into the RouteSession.ROUTE_USED state and the Call
has terminated at a destination as a result of routing by the application. This
interface extends the RouteUsedEvent interface and is reported via the
RouteCallback interface.
Member Summary
Methods
int getRouteSelectedIndex()
This method returns an array index of route where the
call has been routed.

Fields inherited from interface RouteSessionEvent
getRouteSession()
Methods inherited from interface RouteUsedEvent

getCallingAddress(), getCallingTerminal(), getDomain(), getRouteUsed()
Methods
getRouteSelectedIndex()
public int getRouteSelectedIndex()
This method returns an array index of route where the call has been routed.

2-188 OL-7242-02
CiscoRTPBitRate
CiscoRTPBitRate
Declaration
public interface CiscoRTPBitRate
Description
The RTPBitRate interface contains constants describing G.723 RTP bit rates.
These constants are returned by the
CiscoRTPInputProperties.getBitRate method and the
CiscoRTPOutputProperties.getBitRate method.
See Also:
CiscoRTPInputProperties.getBitRate(),
CiscoRTPOutputProperties.getBitRate()
Member Summary
Fields
static int R5_3
5.3k G.723 bit rate
static int R6_4
6.4k G.723 bit rate

OL-7242-02 2-189
CiscoRTPHandle
Fields
R5_3
public static final int R5_3
5.3k G.723 bit rate
R6_4
public static final int R6_4
6.4k G.723 bit rate
CiscoRTPHandle
Declaration
public interface CiscoRTPHandle
Description
The CiscoRTPHandle is returned in CiscoMediaCallOpenLogicalChannelEv and
applications should pass this handle in setRTPParams of CiscoMediaTerminal or
CiscoRouteTerminal depending on where
CiscoMediaCallOpenLogicalChannelEv is received. Applications can use this
object to get call reference using CiscoProvider.getCall(CiscoRTPHandle).
However, if there is no callobserver added or there was no callobserver added at
the time when CiscoMediaCallOpen LogicalChannelEv is sent,
CiscoProvider.getCall(CiscoRTPHandle) may return null method.
Member Summary
Methods
int getBitRate()
Returns the media bit rate, one of the following
constants:

2-190 OL-7242-02
CiscoRTPInputProperties
Methods
getHandle()
public int getHandle()
Returns an integer representation of this object, currently the CallManager

CallLeg ID of the call.
Returns:
Declaration
public interface CiscoRTPInputProperties
Description
Member Summary
Methods
int getBitRate()
constants:
boolean getEchoCancellation()
java.net.InetAddress getLocalAddress()
int getLocalPort()
int getPacketSize()
Returns the payload format, one of the following
constants:

OL-7242-02 2-191
Methods
getBitRate()
Returns the media bit rate, one of the following constants:

• CiscoRTPBitRate.R5_3
Returns:
payload type
getEchoCancellation()
public boolean getEchoCancellation()
Returns:
echo cancellation
getLocalAddress()
public java.net.InetAddress getLocalAddress()
Returns:
address to which media will be directed
getLocalPort()
public int getLocalPort()
Returns:
port to which media will be directed
getPacketSize()
Returns:

2-192 OL-7242-02
getPayloadType()
Returns the payload format, one of the following constants:

Returns:
payload type

OL-7242-02 2-193
Declaration
public interface CiscoRTPInputStartedEv extends CiscoEv
All Superinterfaces
javax.telephony.events.TermEv
Description
Member Summary
Fields
static int ID
Methods
returns CiscoCallID
CiscoRTPInputProperties getRTPInputProperties()

META_UNKNOWN

2-194 OL-7242-02
CiscoRTPInputStoppedEv

Methods inherited from interface TermEv

getTerminal()
Fields
ID
Methods
getCallID()
returns CiscoCallID
getRTPInputProperties()
public com.cisco.jtapi.extensions.CiscoRTPInputProperties
Returns:
RTP input properties
Declaration
public interface CiscoRTPInputStoppedEv extends CiscoTermEv

OL-7242-02 2-195
All Superinterfaces
Description
Member Summary
Fields
static int ID
Methods
returns CiscoCallID

META_UNKNOWN


getTerminal()
Fields
ID

2-196 OL-7242-02
CiscoRTPOutputProperties
Methods
getCallID()
returns CiscoCallID
Declaration
public interface CiscoRTPOutputProperties
Description
Member Summary
Methods
int getBitRate()
constants:
int getMaxFramesPerPacket()
int getPacketSize()
Returns the payload format, one of the following
constants:
int getPrecedenceValue()
java.net.InetAddress getRemoteAddress()
int getRemotePort()
boolean getSilenceSuppression()

OL-7242-02 2-197
Methods
getBitRate()
Returns the media bit rate, one of the following constants:

Returns:
payload type
public int getMaxFramesPerPacket()
Returns:
the maximum number of frames to send per packet
getPacketSize()
Returns:
getPayloadType()
Returns the payload format, one of the following constants:


2-198 OL-7242-02
Returns:
payload type
getPrecedenceValue()
public int getPrecedenceValue()
Returns:
precedence value
getRemoteAddress()
public java.net.InetAddress getRemoteAddress()
Returns:
address to which media is to be transmitted
getRemotePort()
public int getRemotePort()
Returns:
port to which media is to be transmitted

OL-7242-02 2-199
getSilenceSuppression()
public boolean getSilenceSuppression()
Returns:
silence suppression
Declaration
public interface CiscoRTPOutputStartedEv extends CiscoTermEv
All Superinterfaces
Description
Member Summary
Fields
static int ID
Methods
returns CiscoCallID
CiscoRTPOutputProperties getRTPOutputProperties()

2-200 OL-7242-02

META_UNKNOWN


getTerminal()
Fields
ID
Methods
getCallID()
returns CiscoCallID
getRTPOutputProperties()
public com.cisco.jtapi.extensions.CiscoRTPOutputProperties
Returns:
RTP output properties

OL-7242-02 2-201
Declaration
public interface CiscoRTPOutputStoppedEv extends CiscoTermEv
All Superinterfaces
Description
Member Summary
Fields
static int ID
Methods
returns CiscoCallID

2-202 OL-7242-02

META_UNKNOWN


getTerminal()
Fields
ID
Methods
getCallID()
returns CiscoCallID

OL-7242-02 2-203
CiscoRTPParams
CiscoRTPParams
Declaration
public class CiscoRTPParams
java.lang.Object
|
+--com.cisco.jtapi.extensions.CiscoRTPParams
Member Summary
Constructors
CiscoRTPParams(InetAddress, int)
Methods
java.net.InetAddress getRTPAddress()
java.lang.String getRTPAddressHostName()
byte[] getRTPByteAddress()
int getRTPPort()

Constructors
CiscoRTPParams(InetAddress, int)
public CiscoRTPParams(java.net.InetAddress rtpAddress,
int rtpPort)

2-204 OL-7242-02
CiscoRTPPayload
Methods
getRTPAddress()
public java.net.InetAddress getRTPAddress()
getRTPAddressHostName()
public java.lang.String getRTPAddressHostName()
getRTPByteAddress()
public byte[] getRTPByteAddress()
getRTPPort()
public int getRTPPort()
toString()
Overrides:
CiscoRTPPayload
Declaration
public interface CiscoRTPPayload
Description
The RTPPayload interface contains constants describing RTP formats. These
constants are returned by the
CiscoRTPInputProperties.getPayloadType method and the
CiscoRTPOutputProperties.getPayloadType method.

OL-7242-02 2-205
CiscoRTPPayload
See Also:
CiscoRTPInputProperties.getPayloadType(),
CiscoRTPOutputProperties.getPayloadType()
Member Summary
Fields
static int ACTIVEVOICE
ACTIVEVOICE payload
static int ACY_G729AASSN
ACY_G729AASSN payload
static int DATA56
DATA56 payload
static int DATA64
DATA64 payload
static int G711ALAW56K
G.711 56K a-law payload
static int G711ALAW64K
static int G711ULAW56K
G.711 56K u-law payload
static int G711ULAW64K
static int G722_48K
G.722 48K payload
static int G722_56K
G.722 56K payload
static int G722_64K
G.722 64K payload
static int G7231
G.723.1 payload
static int G728
G.728 payload
static int G729
G.729 payload
static int G729ANNEXA
G.729a payload
static int GSM
GSM payload
static int IS11172AUDIOCAP
IS11172AUDIOCAP payload
static int IS13818AUDIOCAP

2-206 OL-7242-02
CiscoRTPPayload
Member Summary
static int NONSTANDARD
A non-standard RTP payload
static int WIDEBAND_256K
Wide_Band_256K payload
Fields
ACTIVEVOICE
public static final int ACTIVEVOICE
ACTIVEVOICE payload
ACY_G729AASSN
public static final int ACY_G729AASSN
ACY_G729AASSN payload
DATA56
public static final int DATA56
DATA56 payload
DATA64
public static final int DATA64
DATA64 payload
G711ALAW56K
public static final int G711ALAW56K
G711ALAW64K
public static final int G711ALAW64K

OL-7242-02 2-207
CiscoRTPPayload
G711ULAW56K
public static final int G711ULAW56K
G711ULAW64K
public static final int G711ULAW64K
G722_48K
public static final int G722_48K
G.722 48K payload
G722_56K
G.722 56K payload
G722_64K
G.722 64K payload
G7231
public static final int G7231
G.723.1 payload
G728
G.728 payload
G729
G.729 payload

2-208 OL-7242-02
CiscoSynchronousObserver
G729ANNEXA
public static final int G729ANNEXA
G.729a payload
GSM
public static final int GSM
GSM payload
IS11172AUDIOCAP
public static final int IS11172AUDIOCAP
IS13818AUDIOCAP
public static final int IS13818AUDIOCAP
NONSTANDARD
public static final int NONSTANDARD
A non-standard RTP payload
WIDEBAND_256K
public static final int WIDEBAND_256K
Wide_Band_256k payload
Declaration
public interface CiscoSynchronousObserver

OL-7242-02 2-209
Description
The Cisco JTAPI implementation is designed to allow applications to invoke
blocking JTAPI methods such as Call.connect() and
TerminalConnection.answer() from within their observer callbacks.
This means that applications are not subject to the restrictions imposed by the
JTAPI specification, which cautions applications against using JTAPI methods
from within observer callbacks.
Normally, when an application adds a new observer to a JTAPI object, the Cisco
JTAPI implementation creates an event queue and an accompanying worker
thread to service the new observer. If the same observer is added to another object,
its queue and thread are reused; in effect, every unique observer object has a
single queue and worker thread. As noted, the advantage of this arrangement is
that an application may invoke blocking JTAPI methods from within its observer
callback. A subtle disadvantage, however, is that accessor methods such as
Call.getConnections() and Connection.getState() may not
return results that are consistent with events when invoked from within the
observer callback.
For example, suppose that an application creates and connects a call from address
“A” to address “B”. If the application is observing address “A”, it might
reasonably expect that when it receives the CallActiveEv, the state of the call
will be Call.ACTIVE. This is not necessarily so, since the worker thread
delivering events to the application is decoupled from the internal JTAPI thread
that is updating object states. In fact, if “B” rejects the call from “A”, the call
object might be in either the Call.ACTIVE state or the Call.INVALID state,
depending on the exact moment at which the worker thread delivers the
CallActiveEv.
Many applications will not be adversely affected by this asynchronous behavior.
Applications that would benefit from a coherent call model during observer
callbacks, however, can selectively disable the queueing logic of the Cisco JTAPI
implementation. By implementing the CiscoSynchronousObserver
interface on its observer objects, an application declares that it wishes events to
be delivered synchronously to its observers. Events delivered to synchronous
observers will match the states of the call model objects queried from within the
observer callback.

2-210 OL-7242-02
Usage Notes
Objects that implement the CiscoSynchronousObserver interface are
strictly forbidden from invoking blocking JTAPI methods from within their event
callbacks. The consequences of doing so are unpredictable, and may include
deadlocking the JTAPI implementation. On the other hand, they may safely use
the accessor methods of any JTAPI object, for instance
Call.getConnections() or Connection.getState().
Declaration
public interface CiscoTermButtonPressedEv extends CiscoTermEv
All Superinterfaces
Description
CiscoTermButtonPressedEv event is delivered on a TerminalObserver when a
button is pressed on the Terminal. In order to receive these events an application
must also enable the flag for these events in the CiscoTermEvFilter. The button
pressed events responds only to the numeric keypad button presses on the
Terminal as listed in the constants in this interface (such as 0-9, *, #, A, B, C, D).
Member Summary
Fields
static int CHARA
static int CHARB
static int CHARC
static int CHARD

OL-7242-02 2-211
Member Summary
static int EIGHT
static int FIVE
static int FOUR
static int ID
static int NINE
static int ONE
static int POUND
static int SEVEN
static int SIX
static int STAR
static int THREE
static int TWO
static int ZERO
Methods
int getButtonPressed()

META_UNKNOWN


getTerminal()
Fields
CHARA
public static final int CHARA

2-212 OL-7242-02
CHARB
public static final int CHARB
CHARC
public static final int CHARC
CHARD
public static final int CHARD
EIGHT
public static final int EIGHT
FIVE
public static final int FIVE
FOUR
public static final int FOUR
ID
NINE
public static final int NINE
ONE
public static final int ONE
POUND
public static final int POUND
SEVEN
public static final int SEVEN
SIX
public static final int SIX
STAR
public static final int STAR

OL-7242-02 2-213
CiscoTermConnPrivacyChangedEv
THREE
public static final int THREE
TWO
public static final int TWO
ZERO
public static final int ZERO
Methods
getButtonPressed()
public int getButtonPressed()
Returns:
the button pressed on the terminal
CiscoTermConnPrivacyChangedEv
Declaration
public interface CiscoTermConnPrivacyChangeEv
Description
This event is sent when Privacy status of TeminalConnection changes during
CallProgress. If privacy is on, you can not Barge into the Call and vice versa.
The CiscoTermConnPrivacyChangedEv event
Member Summary
Fields
static int ID

2-214 OL-7242-02
CiscoTermCreatedEv
Member Summary
Methods
javax.telephony.TerminalC
onnection
Fields
ID
Methods
public javax.telephony.TerminalConnection getTerminalConnection ()
CiscoTermCreatedEv
Declaration
public interface CiscoTermCreatedEv extends CiscoProvEv
All Superinterfaces
Description
The CiscoTermCreatedEv event

OL-7242-02 2-215
CiscoTermCreatedEv
Member Summary
Fields
static int ID
Methods

META_UNKNOWN


getProvider()
Fields
ID
Methods
getTerminal()

2-216 OL-7242-02
CiscoTermDataEv
CiscoTermDataEv
Declaration
public interface CiscoTermDataEv extends CiscoTermEv
All Superinterfaces
Description
The CiscoTermDataEv event
Member Summary
Fields
static int ID
Methods
java.lang.String getData()
byte[] getTermData()

META_UNKNOWN

OL-7242-02 2-217
CiscoTermDeviceStateActiveEv


getTerminal()
Fields
ID
Methods
getData()
public java.lang.String getData()
Deprecated.
use byte[] getTermData
getTermData()
public byte[] getTermData ()
Declaration
public interface CiscoTermDeviceStateActiveEV
extends com.cisco.jtapi.extensions.CiscoTermEv

2-218 OL-7242-02
All Super-Interfaces
CiscoTermEv, CiscoEv, javax.telephony.events.Ev,
Description
The CiscoTermDeviceStateActiveEv is sent to the application if any of the
addresses on the terminal have an outgoing call (in CTI State Dialtone, Dialing,
Proceeding, Ringback, or Connected) or an incoming call (in CTI State
Connected).
Member Summary
Methods
int getDeviceState()
void setDeviceStateActiveEvFilter(boolean filterValue)

META_UNKNOWN


getTerminal()

OL-7242-02 2-219
CiscoTermDeviceStateAlertingEv
Methods
getDeviceState()
Returns the DeviceState of the terminal, which can be one of the following
constants:
– CiscoTerminal.DEVICESTATE_IDLE
– CiscoTerminal.DEVICESTATE_ACTIVE
– CiscoTerminal.DEVICESTATE_ALERTING
– CicsoTerminal.DEVICESTATE_HELD
– CiscoTerminal.DEVICESTATE_UNKNOWN
DeviceState is the cumulative call state of all the addresses on the terminal.
CiscoTerminal.DEVICESTATE_UNKNOWN is returned if
CicsoTermEvFilter is not enabled for DeviceState events or if the terminal is
OUTOFSERVICE.
setDeviceStateActiveEvFilter(boolean filterValue)
public void setDeviceStateActiveEvFilter(boolean filterValue)
Enables and disables the CiscoTermDeviceStateActiveEv filter for the
terminal. The default value is Disable.
getDeviceStateActiveEvFilter()
public boolean getDeviceStateActiveEvFilter()
Gets the CiscoTermDeviceStateActiveEv filter status.
Declaration
public interface CiscoTermDeviceStateAlertingEv

2-220 OL-7242-02
Description
The CiscoDeviceAlertingEv event is sent to the application if none of the address
on the terminal have an outgoing call (in CTI state Dialing, Dialtone, Proceeding,
Ringback, or Connected) or an incoming call (in CTI state Offering, Accepted, or
Ringing).
Member Summary
Methods
void setDeviceStateAlertingEvFilter(boolean filterValue)
boolean getDeviceStateAlertingEvFilter()

META_UNKNOWN


getTerminal()

OL-7242-02 2-221
CiscoTermDeviceStateHeldEv
Methods
getDeviceState()
constants:
OUTOFSERVICE.
setDeviceStateAlertingEvFilter(boolean filterValue)
public void setDeviceStateAlertingEvFilter(boolean filterValue)
Enables and disables the CiscoTermDeviceStateAlertingEv filter for the
getDeviceStateAlertingEvFilter()
public boolean getDeviceStateAlertingEvFilter()
Declaration
public interface CiscoTermDeviceStateHeldEv

2-222 OL-7242-02
Description
The CiscoTermDeviceStateHeldEv is sent to the application if all the calls on any
of the address on the terminal are HELD (in CTI State OnHold).
Member Summary
Methods
void setDeviceStateHeldEvFilter(boolean filterValue)
boolean getDeviceStateHeldEvFilter()

META_UNKNOWN


getTerminal()

OL-7242-02 2-223
CiscoTermDeviceStateIdleEv
Methods
getDeviceState()
constants:
OUTOFSERVICE.
setDeviceStateHeldEvFilter(boolean filterValue)
public void setDeviceStateHeldEvFilter(boolean filterValue)
Enables and disables the CiscoTermDeviceStateHeldEv filter for the
getDeviceStateHeldEvFilter()
public boolean getDeviceStateHeldEvFilter()
Gets the CiscoTermDeviceStateHeldEv filter status.
Declaration
public interface CiscoTermDeviceStateIdleEv

2-224 OL-7242-02
All Superinterfaces
Description
The CiscoTermDeviceStateIdleEv event is sent to the application if there is no call
on any of the addresses on the terminal.
Member Summary
Methods
void setDeviceStateIdleEvFilter(boolean filterValue)
boolean getDeviceStateIdleEvFilter()

META_UNKNOWN


getTerminal()

OL-7242-02 2-225
Methods
getDeviceState()
constants:
OUTOFSERVICE.
setDeviceStateIdleEvFilter(boolean filterValue)
public void setDeviceStateIdleEvFilter (boolean filterValue)
Enables and disables the CiscoTermDeviceStateIdleEv filter for the terminal.
The default value is Disable.
getDeviceStateIdleEvFilter()
public boolean getDeviceStateIdleEvFilter()
Gets the CiscoTermDeviceStateIdleEv filter status.

2-226 OL-7242-02
CiscoTermEv
CiscoTermEv
Declaration
public interface CiscoTermEv extends CiscoEv,
All Superinterfaces
CiscoEv, javax.telephony.events.Ev,

CiscoRTPInputStartedEv, CiscoRTPInputStoppedEv,
CiscoRTPOutputStartedEv, CiscoRTPOutputStoppedEv,
CiscoTermDataEv, CiscoTermInServiceEv,
CiscoTermOutOfServiceEv,
CiscoTermDeviceStateIdleEv,
CiscoTermDeviceStateActiveEv,
CiscoTermDeviceStateAlertingEv,
Description
The CiscoTermEv interface, which extends JTAPI’s core
javax.telephony.events.TermEv interface, serves as the base interface
for all Cisco-extended JTAPI events. Every Call-related event in this package
extends this interface, directly or indirectly.
See Also:

OL-7242-02 2-227
CiscoTermEvFilter

META_UNKNOWN


getTerminal()
CiscoTermEvFilter
Declaration
public interface CiscoTermEvFilter
Description
An application can use the CiscoTermEvFilter interface to selectively restrict
those Terminal events that is not of interest to it.
Member Summary
Methods
boolean getButtonPressedEnabled()
get the enable / disable status of the button pressed
events for the Terminal, default value is disabled.

2-228 OL-7242-02
CiscoTermEvFilter
Member Summary
boolean getDeviceDataEnabled()
get the enable / disable status of the device data events
for the Terminal, default value is disabled.
boolean getRTPEventsEnabled()
get the enable / disable status of the RTP events for the
Terminal, default value is disabled
void setButtonPressedEnabled(boolean)
enable / disable the button pressed events for the
Terminal
void setDeviceDataEnabled(boolean)
enable / disable the device data status events for the
Terminal
void setRTPEventsEnabled(boolean)
enable / disable the RTP events for the Terminal
Methods
getButtonPressedEnabled()
public boolean getButtonPressedEnabled()
get the enable / disable status of the button pressed events for the Terminal,
default value is disabled.
Returns:
the button pressed events enabled status on the Terminal
getDeviceDataEnabled()
public boolean getDeviceDataEnabled()
get the enable / disable status of the device data events for the Terminal,
default value is disabled.
Returns:
the device data events status on the Terminal

OL-7242-02 2-229
CiscoTerminal
getRTPEventsEnabled()
public boolean getRTPEventsEnabled()
get the enable / disable status of the RTP events for the Terminal, default
value is disabled
Returns:
the RTP events enabled status on the Terminal
setButtonPressedEnabled(boolean)
public void setButtonPressedEnabled(boolean enabled)
enable / disable the button pressed events for the Terminal
setDeviceDataEnabled(boolean)
public void setDeviceDataEnabled(boolean enabled)
enable / disable the device data status events for the Terminal
setRTPEventsEnabled(boolean)
public void setRTPEventsEnabled(boolean enabled)
enable / disable the RTP events for the Terminal
CiscoTerminal
Declaration
public interface CiscoTerminal extends javax.telephony.Terminal,
All Superinterfaces
CiscoObjectContainer, javax.telephony.Terminal

2-230 OL-7242-02
CiscoTerminal

CiscoMediaTerminal, CiscoRouteTerminal
Description
Since JTAPI does not support the notion of dynamic terminal registration, the
CiscoTerminal interface extends the standard Terminal interface to do so. All
Cisco CallManager devices are represented by CiscoTerminals, and all
CiscoTerminals may be queried to determine whether they are currently
IN_SERVICE or OUT_OF_SERVICE.
If the Cisco CallManager device represented by the CiscoTerminal is an IP
telephone, for instance, it would become OUT_OF_SERVICE if it were to lose its
network connection. Other types of devices, such as CTIPorts, are registered on
demand by applications, and may be IN_SERVICE or OUT_OF_SERVICE
accordingly.
See Also:
javax.telephony.Terminal, CiscoMediaTerminal
Member Summary
Fields
static int IN_SERVICE
static int OUT_OF_SERVICE
Methods
CiscoTermEvFilter getFilter()
Retrieve the filter object associated with the terminal.
int getRegistrationState()
Returns the state of this terminal.
CiscoRTPInputProperties getRTPInputProperties()
The CiscoTerminal must be in the CiscoTerminal.REGISTERED
state, its Provider must be in the Provider.IN_SERVICE
state.
CiscoRTPOutputProperties getRTPOutputProperties()
The CiscoTerminal must be in the CiscoTerminal.REGISTERED
state, its Provider must be in the Provider.IN_SERVICE
state.

OL-7242-02 2-231
CiscoTerminal
Member Summary
int getState()
byte[]
Send a data object to the terminal screen.
java.lang.String sendData(String)
The preferred method is CiscoTerminal.sendData ( byte[] )
void
Allows an application to have a finer degree of control
over the events that are delivered to the
TerminalObserver.
javax.telephony.TerminalC This method Unparks a call at a terminal and returns a
onnection terminalConnection.


Fields
IN_SERVICE
public static final int IN_SERVICE
OUT_OF_SERVICE
public static final int OUT_OF_SERVICE

2-232 OL-7242-02
CiscoTerminal
Methods
getFilter()
public com.cisco.jtapi.extensions.CiscoTermEvFilter getFilter()
retrieve the filter object associated with the terminal
getRegistrationState()
public int getRegistrationState()
Deprecated.
This method has been replaced by the getState() method.
• CiscoTerminal.OUT_OF_SERVICE
• CiscoTerminal.IN_SERVICE
Returns:
the state of this terminal
public com.cisco.jtapi.extensions.CiscoRTPInputProperties
The CiscoTerminal must be in the CiscoTerminal.REGISTERED state,

its Provider must be in the Provider.IN_SERVICE state. and
Terminal.getTerminalConnections () must return at least one
terminal connection in the TerminalConnection.ACTIVE state.
Returns:
the properties to be used for the RTP input stream associated with the
ACTIVE TerminalConnection on this Terminal
Throws:

OL-7242-02 2-233
CiscoTerminal
public com.cisco.jtapi.extensions.CiscoRTPOutputProperties
The CiscoTerminal must be in the CiscoTerminal.REGISTERED state,

its Provider must be in the Provider.IN_SERVICE state. and
Terminal.getTerminalConnections () must return at least one
terminal connection in the TerminalConnection.ACTIVE state.
Returns:
the properties to be used for the RTP output stream associated with the
ACTIVE TerminalConnection on this Terminal
Throws:
getState()

• CiscoTerminal.OUT_OF_SERVICE
• CiscoTerminal.IN_SERVICE
Returns:
the state of this terminal
sendData(byte[])
public byte[] sendData (byte[] terminalData) throws
InvalidStateException, MethodNotSupportedException
Send a data object to the terminal screen.

Throws:

2-234 OL-7242-02
CiscoTerminal
sendData(String)
public java.lang.String sendData(java.lang.String terminalData)
throws InvalidStateException, MethodNotSupportedException
Throws:
setFilter(CiscoTermEvFilter)
public void setFilter(com.cisco.jtapi.extensions.CiscoTermEvFilter
terminalEvFilter)
Allows an application to have a finer degree of control over the events that are
delivered to the TerminalObserver. This method can be invoked at any time
during the execution of the code but typical use is setting up the Terminal
events as part of initialization or when a CiscoTermCreatedEv indicates the
creation of a new Terminal.
Example 1
One use might be to turn on the button pressed events that are normally not
delivered
Terminal term = provider.getTerminal ( name );
if ( term instanceof CiscoTerm ) {
CiscoTerm ciscoTerm = (CiscoTerm)term;
CiscoTermEvFilter filter = ciscoTerm.getFilter ();
filter.setButtonPressedEnabled ( true );
}
term.addObserver ( terminalObserver );
Example 2
Another use might be turning off some events that is not of interest to an
application. For example an application doing pure call control could turn off
the media (RTP) events as follows:
if ( term instanceof CiscoTerm ) {
CiscoTerm ciscoTerm = (CiscoTerm)term;
CiscoTermEvFilter filter = ciscoTerm.getFilter ();
filter.setRTPEventsEnabled ( false );
ciscoTerm.setFilter ( filter );
}

OL-7242-02 2-235
CiscoTerminal
term.getAddresses () [0].addCallObserver ( callObserver );
Note Adding a CallObserver (without explicitly setting a filter) turns the RTP
events on. This behavior of Cisco JTAPI 1.4 and earlier is still preserved.
If an explicit setFilter call is made then the filter settings will take effect.
The RTP events will not be delivered for the code snippet as in Example
2, but will be delivered for the following example.
Example 3
term.getAddresses () [0].addCallObserver ( callObserver );
unPark(javax.telephony.Address UnParkAddress,
java.lang.String ParkedAt)
throws InvalidStateException, InvalidArgumentException, Resourc
eUnavailableException
This method Unparks a call at a terminal and returns a terminalConnection.

The CiscoTerminal must be in CiscoTerminal.REGISTERED state, its
Provider must be in the Provider.IN_SERVICE state. This method takes
an address and string as input. The address is any address on the terminal and
string is system park port where a call was previously parked. This string is
returned when the a call is parked
Throws:

2-236 OL-7242-02
Declaration
public interface CiscoTerminalConnection extends
javax.telephony.callcontrol.CallControlTerminalConnection,
All Superinterfaces
javax.telephony.callcontrol.CallControlTerminalConn
ection, CiscoObjectContainer,
javax.telephony.TerminalConnection
Description
The CiscoTerminalConnection interface extends the
CallControlTerminalConnection interface with additional capabilities.
Applications can use the getReason method to obtain the reason for the
creation of this Connection.
Member Summary
Methods
boolean getPrivacyStatus()
The getPrivacyStatus interface returns privacy status of
the call on the terminal.
void setRTPParams(CiscoRTPParams)
Applications can set the ipAddress and the RTP Port
number to dynamically stream media for a call.

OL-7242-02 2-237

Fields inherited from interface CallControlTerminalConnection
BRIDGED, DROPPED, HELD, IDLE, INUSE, RINGING, TALKING, UNKNOWN
Fields inherited from interface TerminalConnection

ACTIVE, PASSIVE
Methods inherited from interface CallControlTerminalConnection

getCallControlState(), hold(), join(), leave(), unhold()

Methods inherited from interface TerminalConnection

answer(), getCapabilities(), getConnection(), getState(), getTerminal(),
getTerminalConnectionCapabilities(Terminal, Address)
Methods
getPrivacyStatus()
public boolean getPrivacyStatus()
The getPrivacyStatus interface returns privacy Status of the Call on the

terminal.
The Application can use method TerminalConnection.getPrivacyStatus() to
get privacy of the call This interface returns true if Privacy is on and vice
versa. Application should always see the Privacy status of
TerminalConnection before displaying any information about the call at
Application’s Terminal implementation.
setRTPParams(CiscoRTPParams)
public void setRTPParams(com.cisco.jtapi.extensions.CiscoRTPParams
rtpParams) throws InvalidStateException,
InvalidArgumentException, PrivilegeViolationException

2-238 OL-7242-02
CiscoTerminalObserver

CiscoCallOpenLogicalChannel on terminalObserver. This method is valid for
calls presented for CiscoMediaTerminal or CiscoRouteTerminal only.
Throws:
See Also:
CiscoRTPParams
Declaration
public interface CiscoTerminalObserver extends
javax.telephony.TerminalObserver
All Superinterfaces:
javax.telephony.TerminalObserver
Description
Applications implement this interface in order to receive CiscoTermEv events
such as CiscoRTPInputStartedEv and CiscoRTPInputStoppedEv
when observing Terminals via the Terminal.addObserver method.
See Also:
CiscoTermInServiceEv, CiscoTermOutOfServiceEv,
CiscoRTPInputStartedEv, CiscoRTPInputStoppedEv,
CiscoRTPOutputStartedEv, CiscoRTPOutputStoppedEv

OL-7242-02 2-239
CiscoTermInServiceEv

Methods inherited from interface TerminalObserver
terminalChangedEvent(TermEv[])
Declaration
public interface CiscoTermInServiceEv extends CiscoTermEv
All Superinterfaces
Description
The CiscoTermInServiceEv event
Member Summary
Fields
static int ID

2-240 OL-7242-02
CiscoTermOutOfServiceEv

META_UNKNOWN


getTerminal()
Fields
ID
Declaration
public interface CiscoTermOutOfServiceEv extends CiscoTermEv,
CiscoOutOfServiceEv
All Superinterfaces
CiscoEv, CiscoOutOfServiceEv, CiscoTermEv,
javax.telephony.events.Ev,

OL-7242-02 2-241
Description
The CiscoTermOutOfServiceEv event
Member Summary
Fields
static int ID

Fields inherited from interface CiscoOutOfServiceEv
CAUSE_CALLMANAGER_FAILURE, CAUSE_CTIMANAGER_FAILURE, CAUSE_DEVICE_FAILURE,
CAUSE_DEVICE_UNREGISTERED, CAUSE_NOCALLMANAGER_AVAILABLE,
CAUSE_REHOME_TO_HIGHER_PRIORITY_CM, CAUSE_REHOMING_FAILURE

META_UNKNOWN


getTerminal()
Fields
ID

2-242 OL-7242-02
CiscoTermRegistrationFailedEv
Declaration
public interface CiscoTermRegistrationFailedEv extends CiscoTermEv
All Superinterfaces
Description
The CiscoTermRegistrationFailedEv event.
This event is send to Application when TerminalRegistration failed by provider
for some reason. Error returned by getErrorCode() interface defines type of error.
On getting this event Application should try to re-register Terminal with proper
parameter Following are the error returned and suggested action to be taken by
Application.
ErrorCode:
CiscoTermRegistraionFailedEv.MEDIA_CAPABILITY_MISMATCH
Registration can not be done, as Terminal is already registered, second
registration should be done with same media capability. Try re-registering with
same capability.
ErrorCode:
CiscoTermRegistraionFailedEv.MEDIA_ALREADY_TERMINATED_NONE
Registration can not be done, as Terminal is already registered with Media
termination type none. Try re-registering with Media termination type none.

OL-7242-02 2-243
ErrorCode:
CiscoTermRegistraionFailedEv.MEDIA_ALREADY_TERMINATED_STATIC
Registration can not be done, as Terminal is already registered with Static media
termination For static registration, second registration is not allowed. Wait until
Terminal UnRegisters.
ErrorCode:
CiscoTermRegistraionFailedEv.MEDIA_ALREADY_TERMINATED_DYNAMI
C Registration can not be done, as Terminal already registered with Dynamic
media termination. Try re-registering with Dynamic Media termination.
ErrorCode:
CiscoTermRegistraionFailedEv.OWNER_NOT_ALIVE Registration is in race
condition while registering terminal. Try registering the Terminal again.
Member Summary
Fields
static int ID
static int MEDIA_ALREADY_TERMINATED_DYNAMIC
Registration can not be done, as Terminal is already
registered with Dynamic media termination. Try
re-registering with Dynamic Media termination.
static int MEDIA_ALREADY_TERMINATED_NONE
registered with Media termination type none. Try
re-registering with Media termination type none.
static int MEDIA_ALREADY_TERMINATED_STATIC
registered with Static media termination. For static
registration, second registration is not allowed. Wait
until Terminal UnRegisters.
static int MEDIA_CAPABILITY_MISMATCH
registered, second registration should be done with same
media capability.
static int OWNER_NOT_ALIVE
Registration is in a race condition while registering the
terminal. Try registering the Device.
Methods
int getErrorCode()
Returns the errorCode for this exception.

2-244 OL-7242-02

META_UNKNOWN


getTerminal()
Fields
ID
MEDIA_ALREADY_TERMINATED_DYNAMIC
public static final int MEDIA_ALREADY_TERMINATED_DYNAMIC
Registration can not be done, as Terminal is already registered
with Dynamic media termination. Try re-registering with Dynamic
Media termination.
MEDIA_ALREADY_TERMINATED_NONE
public static final int MEDIA_ALREADY_TERMINATED_NONE
with Media termination type none. Try re-registering with Media
termination type none.

OL-7242-02 2-245
CiscoTermRemovedEv
MEDIA_ALREADY_TERMINATED_STATIC
public static final int MEDIA_ALREADY_TERMINATED_STATIC
with Static media termination. For static registration, second
registration is not allowed. Wait until Terminal UnRegisters.
MEDIA_CAPABILITY_MISMATCH
public static final int MEDIA_CAPABILITY_MISMATCH
Registration can not be done, as Terminal is already registered,
second registration should be done with same media capability. Try
re-registering with same capability.
OWNER_NOT_ALIVE
public static final int OWNER_NOT_ALIVE
Registration has got in race condition while register terminal.
Try registering the Device.
Methods
getErrorCode()
public int getErrorCode()

Returns:
errorCode in an integer representation
CiscoTermRemovedEv
Declaration
public interface CiscoTermRemovedEv extends CiscoProvEv

2-246 OL-7242-02
CiscoTermRemovedEv
All Superinterfaces
Description
The CiscoTermRemovedEv event
Member Summary
Fields
static int ID
Methods

META_UNKNOWN


getProvider()

OL-7242-02 2-247
CiscoToneChangedEv
Fields
ID
Methods
getTerminal()
CiscoToneChangedEv
Declaration
public interface CiscoToneChangedEv extends CiscoCallEv
All Superinterfaces
CiscoCallEv, CiscoEv, javax.telephony.events.CallEv,
Description
The CiscoToneChangedEv event indicates that a tone is generated. If
getCiscoCause() returns CiscoCallEv.CAUSE_FAC_CMC, then additional digits
need to be entered using the CiscoConnection.addToAddress(String) interface.
Member Summary
Fields
public static int CMC_REQUIRED
public static int FAC_CMC_REQUIRED

2-248 OL-7242-02
CiscoToneChangedEv
Member Summary
public static int FAC_REQUIRED
public static int ID
public static int ZIPZIP
Methods
int getWhichCodeRequired()
int getTone()

CAUSE_USERBUSY

META_UNKNOWN

OL-7242-02 2-249
CiscoToneChangedEv

getCall()

getCiscoCause()

Fields
CMC_REQUIRED
public static int CMC_REQUIRED
Indicates that the client matter code (CMC) needs to be entered using
Connection.addToAddress(String) to extend the call. This is applicable only
if getCiscoCause() is CiscoCallEv.CAUSE_FAC_CMC.
FAC_CMC_REQUIRED
public static int FAC_CMC_REQUIRED
Indicates that the DN requires both the CMC and the forced authorization
code (FAC) to extend the call. This is applicable only if () is
CiscoCallEv.CAUSE_FAC_CMC.
FAC_REQUIRED
public static int FAC_REQUIRED
Indicates that the DN requires the FAC to be entered using

Connection.addToAddress(String) to extend the call. This is applicable only
if getCiscoCause() is CiscoCallEv.CAUSE_FAC_CMC.
ID
public static int ID

2-250 OL-7242-02
CiscoTransferEndEv
ZIPZIP
Indicates that the tone type is ZIPZIP.
Methods
getWhichCodeRequired()
int getWhichCodeRequired()
Returns which codes are required for the dialed DN.
getTone()
int getTone()
Returns a tone from CiscoTone.
CiscoTransferEndEv
Declaration
public interface CiscoTransferEndEv extends CiscoCallEv
All Superinterfaces
Description
The CiscoTransferEndEv event indicates that a transfer operation has
completed. This event is reported via the CallControlCallObserver
interface.

OL-7242-02 2-251
CiscoTransferEndEv
Member Summary
Fields
static int ID
Methods
Returns the call that remains active after the transfer
is completed.
getTransferController()
javax.telephony.TerminalC Returns the TerminalConnection which currently acts as
onnection the transfer controller for this call —- the final call.
javax.telephony.Address getTransferControllerAddress()
Returns the Address which currently acts as the transfer
controller for this call —- the final call.
getTransferControllers()
javax.telephony.TerminalC Returns the List of TerminalConnection which currently
onnection[] acts as the transfer controller for this call —- the
final call.
javax.telephony.Call getTransferredCall()
Returns the call that has been transferred.
boolean isSuccess()
Returns true or false, depending on whether Transfer is
successful. Application can use this interface to find
whether Transfer is successful.


2-252 OL-7242-02
CiscoTransferEndEv

CAUSE_USERBUSY

META_UNKNOWN

getCall()

getCiscoCause()


OL-7242-02 2-253
CiscoTransferEndEv
Fields
ID
Methods
getFinalCall()
Returns the call that remains active after the transfer is completed.
public javax.telephony.TerminalConnection getTransferController()
Returns the TerminalConnection which currently acts as the transfer

controller for this call —- the final call. This method returns null if the
transfer controller is not being observed.
getTransferControllerAddress()
public javax.telephony.Address getTransferControllerAddress()
Returns the Address which currently acts as the transfer controller for this
call —- the final call.
Returns the List of TerminalConnection which currently acts as the transfer

controller for this call -- the final call. When transferController is not
SharedLine, there will be only TerminalConnection in the list This method
returns null if the transfer controller is not being observed.

2-254 OL-7242-02
getTransferredCall()
public javax.telephony.Call getTransferredCall()
Returns the call that has been transferred. This call is in the Call.INVALID
state.
isSuccess()
public boolean isSuccess()
Return true or false, depending on whether Transfer is successful.

Application can use this interface to find whether Transfer is successful.
Declaration
public interface CiscoTransferStartEv extends CiscoCallEv
All Superinterfaces
Description
The CiscoTransferStartEv event indicates that a transfer operation has
started. This event is reported via the CallControlCallObserver interface.
Member Summary
Fields
static int ID
Methods

OL-7242-02 2-255
Member Summary
Returns the call that will remain active after the
transfer is completed.
javax.telephony.TerminalC Returns the TerminalConnection which currently acts as
onnection the transfer controller for this call —- the final call.
javax.telephony.Address getTransferControllerAddress()
Returns the Address which currently acts as the transfer
controller for this call —- the final call.
javax.telephony.TerminalC Returns the List of TerminalConnection which currently
onnection[] acts as the transfer controller for this call —- the
final call.
javax.telephony.Call getTransferredCall()
Returns the call that will be transferred.

CAUSE_USERBUSY

2-256 OL-7242-02

META_UNKNOWN

getCall()

getCiscoCause()

Fields
ID
Methods
getFinalCall()
Returns the call that will remain active after the transfer is completed.
public javax.telephony.TerminalConnection getTransferController()
Returns the TerminalConnection which currently acts as the transfer

controller for this call —- the final call. This method returns null if the
transfer controller is not being observed.

OL-7242-02 2-257
getTransferControllerAddress()
public javax.telephony.Address getTransferControllerAddress()
Returns the Address which currently acts as the transfer controller for this
call —- the final call.
Returns the List of TerminalConnection which currently acts as the transfer

controller for this call -- the final call. When transferController is not
SharedLine, there will be only TerminalConnection in the list This method
returns null if the transfer controller is not being observed.
public javax.telephony.Call getTransferredCall()
Returns the call that will be transferred.
Declaration
public class CiscoUnregistrationException extends java.lang.Exception
java.lang.Object
|
+--java.lang.Throwable
|
+--java.lang.Exception
|
+--com.cisco.jtapi.extensions.CiscoUnregistration
Exception

java.io.Serializable

2-258 OL-7242-02
Description
The CiscoMediaTerminal.unregister method throws this exception
when the unregistration process fails for any reason. For example, registration
would fail if the Provider were OUT_OF_SERVICE or if the device were already
unregistered.
See Also:
CiscoMediaTerminal.unregister()
Member Summary
Constructors
CiscoUnregistrationException()
CiscoUnregistrationException(String)

Methods inherited from class Throwable

fillInStackTrace(), getLocalizedMessage(), getMessage(), printStackTrace(PrintWriter),
printStackTrace(PrintWriter), printStackTrace(PrintWriter), toString()
Constructors
CiscoUnregistrationException()
public CiscoUnregistrationException()
CiscoUnregistrationException(String)
public CiscoUnregistrationException(java.lang.String description)

OL-7242-02 2-259
public class CiscoWideBandMediaCapability extends CiscoMediaCapability
java.lang.Object
|
|
+--com.cisco.jtapi.extensions.CiscoWideBandMediaCapabil
ity
Description
The CiscoWideBandMediaCapability object specifies the properties for a wide
band encoded RTP stream. Applications that support wide band media
termination use this object to specify their preferred packet size when registering
a CiscoMediaTerminal.
The default packet size is ten milliseconds.
Member Summary
Fields
static int FRAMESIZE_TEN_MILLISECOND_PACKET
The frames per packet value for 10 millisecond packets.
Constructors
CiscoWideBandMediaCapability(), int maxFramesPerPacket)
Constructs a CiscoWideBandMediaCapability object for the
default ten millisecond packet size.
CiscoWideBandMediaCapability(int)
Constructs a CiscoWideBandMediaCapability object for the
specified packet size.


2-260 OL-7242-02



Fields
FRAMESIZE_TEN_MILLISECOND_PACKET
public static final int FRAMESIZE_TEN_MILLISECOND_PACKET
Constructors
CiscoWideBandMediaCapability()
public CiscoWideBandMediaCapability()
Constructs a CiscoWideBandMediaCapability</CODE object with a default

ten millisecond packet size.
CiscoWideBandMediaCapability(int)
public CiscoWideBandMediaCapability(int maxFramesPerPacket)
Constructs a CiscoWideBandMediaCapability</CODE object with the

specified packet size.

OL-7242-02 2-261
Class com.cisco.services.alarm
Class com.cisco.services.alarm
Class Summary
Interfaces
Alarm The Alarm interface is used to define Alarms in.
AlarmWriter An AlarmWriter receives alarm messages and transmits it to

the receiving AlarmService on a TCP link.
Classes
AlarmManager The AlarmManager is used to create Alarm objects.
DefaultAlarm An Implementation of the Alarm interface.
DefaultAlarmWriter DefaultAlarmWriter implementation of the AlarmWriter

interface.
ParameterList ParameterList is a list of name value pairs that is used to

send additional (and optional) user defined parameters to
the AlarmService.
Alarm
Declaration
public interface Alarm
All Known Implementing Classes

DefaultAlarm

2-262 OL-7242-02
Alarm
Description
The Alarm interface is used to define Alarms in. An Alarm has an XML
representation that it must adhere to in order to be recognized by the Alarm
Service, with a DTD as shown below. An application can implement this interface
or use the AlarmFactory to generate Alarms of the correct format. The Alarm is
the a specification that needs to be sent to an AlarmService that will take some
action based on the Alarm. Using this specification the AlarmService will access
definitions available in a catalog. This catalog is maintained by the user requiring
the Alarm function to effect the appropriate action for the Alarm. The severity
specified the Alarm can over-ride the severity associated with this Alarm in the
catalog. If no severity is specified in the Alarm the catalog severity is used.
Alarm severities are derived from Syslog and are defined as follows:
0 = EMERGENCIES System unusable

1 = ALERTS Immediate action needed
2 = CRITICAL Critical conditions
3 = ERROR Error conditions
4 = WARNING Warning conditions
5 = NOTIFICATION Normal but significant condition
6 = INFORMATIONAL Informational messages only
7 = DEBUGGING Debugging messages
Member Summary
Fields
static int ALERTS
The application will continue working on the tasks but
all functions may not be operational (one or more devices
in the list are not accessible but others in the list can
be accessed)
Syslog severity level = 1
static int CRITICAL
A critical failure, the application can not accomplish
the tasks required due to this failure, for example, the
app cant open the database to read the device list

OL-7242-02 2-263
Alarm
Member Summary
static int DEBUGGING
Very detailed information regarding errors or processing
status that is only generated when DEBUG mode has been
enabled
static int EMERGENCIES
Emergency situation, a system shutdown is necessary
static int ERROR
An error condition of some kind has occurred and the user
needs to understand the nature of that failure
static int HIGHEST_LEVEL
The highest trace level, currently this is DEBUGGING with
a trace level of 7
static int INFORMATIONAL
Information of some form not relating to errors,
warnings, audit, or debug
Syslog severity level =6
static int LOWEST_LEVEL
The lowest trace level, currently this is EMERGENCIES
with a trace level of 0
static int NO_SEVERITY
Applications can set this level to generate Alarms
without a severity.
static int NOTIFICATION
Notification denotes a normal but significant condition
static java.lang.String UNKNOWN_MNEMONIC
String used when a mnemonic is not specified during an
Alarm send
static int WARNING
Warning that a problem of some form exists but is not
keeping the application from completing its tasks
Methods
java.lang.String getFacility()
int getSeverity()
java.lang.String getSubFacility()
void send(String)
send the Alarm with the specified mnemonic.
void send(String, ParameterList)
send an Alarm with the specified mnemonic and supplied
parameter list

2-264 OL-7242-02
Alarm
Member Summary
void send(String, String, String)
send an Alarm with the specified mnemonic and with one
parameter
Fields
ALERTS
public static final int ALERTS
The application will continue working on the tasks but all functions may not
be operational (one or more devices in the list are not accessible but others in
the list can be accessed)
CRITICAL
public static final int CRITICAL
A critical failure, the application can not accomplish the tasks required due
to this failure, for example, the app cant open the database to read the device
list
DEBUGGING
public static final int DEBUGGING
Very detailed information regarding errors or processing status that is only

generated when DEBUG mode has been enabled
EMERGENCIES
public static final int EMERGENCIES


OL-7242-02 2-265
Alarm
ERROR
public static final int ERROR
An error condition of some kind has occurred and the user needs to
understand the nature of that failure
HIGHEST_LEVEL
public static final int HIGHEST_LEVEL
The highest trace level, currently this is DEBUGGING with a trace level of 7
INFORMATIONAL
public static final int INFORMATIONAL
Information of some form not relating to errors, warnings, audit, or debug

LOWEST_LEVEL
public static final int LOWEST_LEVEL
The lowest trace level, currently this is EMERGENCIES with a trace level of
0
NO_SEVERITY
public static final int NO_SEVERITY
Applications can set this level to generate Alarms without a severity. NOTE:
This is only intended for cases where an application wants the AlarmService
to use the severity associated with the Alarm in the catalog
NOTIFICATION
public static final int NOTIFICATION


2-266 OL-7242-02
Alarm
UNKNOWN_MNEMONIC
public static final java.lang.String UNKNOWN_MNEMONIC
String used when a mnemonic is not specified during an Alarm send
WARNING
public static final int WARNING
Warning that a problem of some form exists but is not keeping the application
from completing its tasks
Methods
getFacility()
public java.lang.String getFacility()
Returns:
the facility name of this Alarm
getSeverity()
public int getSeverity()
Returns:
severity of the alarm, an integer in the range [0-7]
getSubFacility()
public java.lang.String getSubFacility()
Returns:
the subfacility of this Alarm
send(String)
public void send(java.lang.String mnemonic)
send the Alarm with the specified mnemonic. If a null or empty String is
passed a mnemonic UNK is sent

OL-7242-02 2-267
AlarmManager
send(String, ParameterList)
public void send(java.lang.String mnemonic,
com.cisco.services.alarm.ParameterList parameterList)
send an Alarm with the specified mnemonic and supplied parameter list
send(String, String, String)

java.lang.String parameterName,
java.lang.String parameterValue)
send an Alarm with the specified mnemonic and with one parameter
AlarmManager
Declaration
public class AlarmManager
java.lang.Object
|
+--com.cisco.services.alarm.AlarmManager
Description
The AlarmManager is used to create Alarm objects. The AlarmManager is created
with a facility and AlarmService hostname and port. All alarms created by the
factory will be associated with this facility. This class also maintains a reference
to a single AlarmWriter that can be used system wide. An application can make
use of this AlarmWriter. AlarmManager exposes a default implementation of an
AlarmWriter. Applications can override this with a user defined implementation
of their own AlarmWriter.
Usage:
AlarmManager AlarmManager = new AlarmManager(facilityName,
alarmServiceHost, alarmServicePort, debugTrace, errorTrace);

2-268 OL-7242-02
AlarmManager
Alarms are created by the factory by supplying the alarmName (mnemonic),

subfacility and severity Alarms can be cached for use in different parts of the
application. During a send alarm applications can specify the variable parameters
that offer specific information to the AlarmService.
Usage:
Typically applications will maintain their own AlarmManager instance.
Applications will also have to set a debug and error trace to enable the alarm
tracing to also be sent to the existing trace destinations.
Setup the manager and writer classes:

AlarmWriter alarmWriter = new DefaultAlarmWriter(port, alarmServiceHost);
AlarmManager alarmManager = new AlarmManager(“AA_IVR”, alarmWriter,
debugTrace, errorTrace);
Generating the Alarms:

create an alarm for the subfacility and a default severity.
Alarm alarm = alarmManager.createAlarm(“HTTPSS”,
Alarm.INFORMATIONAL);
alarm.send(“090T”) sends the alarm with the mnemonic
alarm.send(“090T”, “Port is stuck”, “CTIPort01”) or with a mnemonic and
parameter
Note More than one parameter can be sent by specifying a ParameterList
Member Summary
Constructors
AlarmManager(String, AlarmWriter, Trace, UnconditionalTrace)
Create an instance of the AlarmManager for the facility.
Methods
Alarm createAlarm(String, int)
Creates an Alarm of required severity for the subFacility
AlarmWriter getAlarmWriter()
void setAlarmWriter(AlarmWriter)
Allows applications to override the AlarmWriter to be
used by this AlarmManager, with a user defined
AlarmWriter

OL-7242-02 2-269
AlarmManager

Constructors
AlarmManager(String, AlarmWriter, Trace, UnconditionalTrace)
public AlarmManager(java.lang.String facility,
com.cisco.services.alarm.AlarmWriter writer,
com.cisco.services.tracing.Trace debugTrace_,
com.cisco.services.tracing.UnconditionalTrace errorTrace_)
Create an instance of the AlarmManager for the facility. Applications specify

an AlarmWriter to be used by this AlarmManager to send the Alarms to the
AlarmService.
Methods
createAlarm(String, int)
public com.cisco.services.alarm.Alarm createAlarm(java.lang.String
subfacility, int severity)
Creates an Alarm of required severity for the subFacility

Returns:
an object implementing the alarm interface
getAlarmWriter()
public com.cisco.services.alarm.AlarmWriter getAlarmWriter()
Returns:
an AlarmWriter object

2-270 OL-7242-02
AlarmWriter
setAlarmWriter(AlarmWriter)
public void setAlarmWriter(com.cisco.services.alarm.AlarmWriter
writer)
Allows applications to override the AlarmWriter to be used by this

AlarmManager, with a user defined AlarmWriter
AlarmWriter
Declaration
public interface AlarmWriter

DefaultAlarmWriter
Description
An AlarmWriter receives alarm messages and transmits it to the receiving
AlarmService on a TCP link. This interface can be used to implement other
AlarmWriters to be used with this implementation of com.cisco.service.alarm A
DefaultAlarmWriter is provided with this implementation and can be obtained
from the AlarmManager.
Member Summary
Methods
void close()
close the AlarmWriter
java.lang.String getDescription()
boolean getEnabled()
java.lang.String getName()
void send(String)
Send out the alarm message to the AlarmService.

OL-7242-02 2-271
AlarmWriter
Member Summary
void setEnabled(boolean)
Enable or disable the AlarmWriter
Methods
close()
public void close()
close the AlarmWriter
getDescription()
public java.lang.String getDescription()
Returns:
the AlarmWriter description
getEnabled()
public boolean getEnabled()
Returns:
the current enabled or disabled state of the AlarmWriter
getName()
public java.lang.String getName()
Returns:
the AlarmWriter name
send(String)
public void send(java.lang.String alarmMessage)
Send out the alarm message to the AlarmService.

Parameters:
the - Alarm to be sent

2-272 OL-7242-02
DefaultAlarm
setEnabled(boolean)
public void setEnabled(boolean enable)
Enable or disable the AlarmWriter

Parameters:
enable - or disable the AlarmWriter
DefaultAlarm
Declaration
public class DefaultAlarm implements Alarm
java.lang.Object
|
+--com.cisco.services.alarm.DefaultAlarm

Alarm
Description
An Implementation of the Alarm interface. The AlarmManager creates these
Alarms when the createAlarm() method is called.
Member Summary
Constructors
DefaultAlarm(String, String, int, AlarmWriter))
Methods
java.lang.String getFacility()
int getSeverity()

OL-7242-02 2-273
DefaultAlarm
Member Summary
void send(String)
Send the alarm with the specified mnemonic
void send(String, ParameterList)
Send the alarm with the specified name and list of
parameters.
void send(String, String, String)
Send the alarm with the specified name and parameter

Fields inherited from interface Alarm
ALERTS, CRITICAL, DEBUGGING, EMERGENCIES, ERROR, HIGHEST_LEVEL, INFORMATIONAL,
LOWEST_LEVEL, NOTIFICATION, NO_SEVERITY, UNKNOWN_MNEMONIC, WARNING

Constructors
DefaultAlarm(String, String, int, AlarmWriter)
public DefaultAlarm(java.lang.String facility,
java.lang.String subFacility, int severity,
com.cisco.services.alarm.AlarmWriter alarmWriter)
Methods
getFacility()
public java.lang.String getFacility()
Specified By:
getFacility in interface Alarm

2-274 OL-7242-02
DefaultAlarm
getSeverity()
public int getSeverity()
Specified By:
getSeverity in interface Alarm
getSubFacility()
Specified By:
getSubFacility in interface Alarm
send(String)
public void send(java.lang.String mnemonic)
Send the alarm with the specified mnemonic

Specified By:
send in interface Alarm
send(String, ParameterList)
com.cisco.services.alarm.ParameterList paramList)
Send the alarm with the specified name and list of parameters.
Specified By:
send(String, String, String)

java.lang.String paramName, java.lang.String paramValue)
Send the alarm with the specified name and parameter

Specified By:

OL-7242-02 2-275
DefaultAlarmWriter
DefaultAlarmWriter
Declaration
public class DefaultAlarmWriter implements AlarmWriter
java.lang.Object
|
+--com.cisco.services.alarm.DefaultAlarmWriter

AlarmWriter
Description
DefaultAlarmWriter implementation of the AlarmWriter interface.
DefaultAlarmWriter maintains a queue of a fixed size to which the alarms
are written. The sending of the alarms to the alarm service takes place on a
separate thread. The queue is fixed size.
Member Summary
Constructors
DefaultAlarmWriter(int, String)
Constructor for the DefaultAlarmWriter which takes the
AlarmService hostname, port and a queue size of fifty
(50).
DefaultAlarmWriter(int, String, int)
AlarmService hostname, port and queue size.
DefaultAlarmWriter(int, String, int, ConditionalTrace,
UnconditionalTrace)
AlarmService hostname, port and queue size.

2-276 OL-7242-02
DefaultAlarmWriter
Member Summary
Methods
void close()
Shutdown the send thread and close the socket
static void main(String[])
void send(String)
send the Alarm to the alarm service
void setEnabled(boolean)
Applications can dynamically enable or disable the
AlarmWriter

Constructors
DefaultAlarmWriter(int, String)
public DefaultAlarmWriter(int port,
java.lang.String alarmServiceName)
throws UnknownHostException
Constructor for the DefaultAlarmWriter which takes the AlarmService

hostname, port and a queue size of fifty (50). The AlarmService is listening
on this port for Alarm messages.
Parameters:
port: port on which the alarm service is listening
alarmServiceName: The host name of the machine with the Alarm
service
Throws:
java.net.UnknownHostException

OL-7242-02 2-277
DefaultAlarmWriter
DefaultAlarmWriter(int, String, int)

java.lang.String alarmServiceName, int queueSize)

hostname, port and queue size. The AlarmService is listening on this port for
Alarm messages.
Parameters:
port—port on which the alarm service is listening
alarmServiceName—The host name of the machine with the Alarm
service
queueSize - the size of the queue to be maintained in the alarm writer
Throws:
DefaultAlarmWriter(int, String, int, ConditionalTrace, UnconditionalTrace)

java.lang.String alarmServiceName, int queueSize,
com.cisco.services.tracing.ConditionalTrace debugTrace_,
com.cisco.services.tracing.UnconditionalTrace errorTrace_)

hostname, port and queue size. The AlarmService is listening on this port for
Alarm messages.
Parameters:
port—port on which the alarm service is listening
alarmServiceName—The host name of the machine with the Alarm
service
queueSize - the size of the queue to be maintained in the alarm writer
Throws:

2-278 OL-7242-02
DefaultAlarmWriter
Methods
close()
public void close()
Shutdown the send thread and close the socket

Specified By:
close in interface AlarmWriter
getDescription()
Specified By:
getDescription in interface AlarmWriter
Returns:
a short description of the AlarmWriter
getEnabled()
Specified By:
getEnabled in interface AlarmWriter
Returns:
the enabled state of the AlarmWriter
getName()
Specified By:
getName in interface AlarmWriter
Returns:
the name of the AlarmWriter
main(String[])
public static void main(java.lang.String[] args)

OL-7242-02 2-279
ParameterList
send(String)
public void send(java.lang.String alarmMessage)
send the Alarm to the alarm service

Specified By:
send in interface AlarmWriter
setEnabled(boolean)
public void setEnabled(boolean enable)
Applications can dynamically enable or disable the AlarmWriter

Specified By:
setEnabled in interface AlarmWriter
ParameterList
Declaration
public class ParameterList
java.lang.Object
|
+--com.cisco.services.alarm.ParameterList
Description
ParameterList is a list of name value pairs that is used to send additional (and
optional) user defined parameters to the AlarmService. These parameters can
contain the specifics of an Alarm.
As an example, a LowResourceAlarm can have a parameter that informs the
service which particular resource is low:
name=“CPUUsage”
value=“0.9”

2-280 OL-7242-02
ParameterList
These parameters are user definable but must, however, also be pre-defined in the
AlarmService catalog.
Member Summary
Constructors
ParameterList()
Default constructor for the ParameterList
ParameterList(String, String)
Constructor that takes a name value pair.
Methods
void addParameter(String, String)
method used to add additional name value pairs
(parameters) to the list
java.lang.String[] getParameterNames()
Get the parameter names in the list
java.lang.String getParameterValue(String)
get the value for a parameter
void removeAllParameters()
remove all the parameters in the list
void removeParameter(String)
remove a particular parameter if it is in the list

Constructors
ParameterList()
public ParameterList()
Default constructor for the ParameterList

OL-7242-02 2-281
ParameterList
ParameterList(String, String)
public ParameterList(java.lang.String name,
java.lang.String value)
Constructor that takes a name value pair.
Methods
addParameter(String, String)
public void addParameter(java.lang.String name,
java.lang.String value)
method used to add additional name value pairs (parameters) to the list
getParameterNames()
public java.lang.String[] getParameterNames()
Get the parameter names in the list

Returns:
array of parameters
getParameterValue(String)
public java.lang.String getParameterValue(java.lang.String
parameterName)
get the value for a parameter

Returns:
value of a parameter
removeAllParameters()
public void removeAllParameters()
remove all the parameters in the list
removeParameter(String)
public void removeParameter(java.lang.String parameterName)
remove a particular parameter if it is in the list

2-282 OL-7242-02
Class com.cisco.services.tracing
toString()
Overrides:
Class com.cisco.services.tracing
Class Summary
Interfaces
ConditionalTrace The ConditionalTrace interface extends the Trace interface
and defines the methods that allow enabling and disabling of
tracing for this particular condition.
Trace The Trace interface defines the methods that allow

application tracing.
TraceManager The TraceManager interface defines the methods that allow

applications trace management.
TraceModule The TraceModule interface serves two purposes.
TraceWriter Introduction
TraceWriterManager TraceWriterManager contains the list of TraceWriter objects

that are used to implement the tracing.
UnconditionalTrace The UnconditionalTrace interface extends the Trace

interface.
Classes
BaseTraceWriter This abstract class is useful for supplying a default,
non-printing TraceWriter to a TraceWriterManager This class
must be extended to provide the functionality to trace to
different streams.
ConsoleTraceWriter Supplies a console TraceWriter to trace to System.out.
LogFileTraceWriter Introduction
OutputStreamTraceWriter OutputStreamTraceWriter wraps an output stream in a

TraceWriter.

OL-7242-02 2-283
BaseTraceWriter
Class Summary
SyslogTraceWriter SyslogTraceWriter refines the BaseTraceWriter to allow
tracing to syslog.
TraceManagerFactory The TraceManagerFactory class is a class by which

applications obtain a TraceManager object.
BaseTraceWriter
Declaration
public abstract class BaseTraceWriter implements TraceWriter
java.lang.Object
|
+--com.cisco.services.tracing.BaseTraceWriter

TraceWriter
Direct Known Subclasses

ConsoleTraceWriter, LogFileTraceWriter, OutputStreamTraceWriter,
SyslogTraceWriter
Description
This abstract class is useful for supplying a default, non-printing TraceWriter
to a TraceWriterManager This class must be extended to provide the
functionality to trace to different streams. The doPrintln() method must
be implemented by the extending class.

2-284 OL-7242-02
BaseTraceWriter
Member Summary
Constructors
protected BaseTraceWriter(int[], String, String)
BaseTraceWriter with trace levels as passed in
traceLevels in the array falling outside the range
Trace.LOWEST_LEVEL and Trace.HIGHEST_LEVEl are ignored
protected BaseTraceWriter(int, String, String)
BaseTraceWriter that traces all levels up to the
maxTraceLevel The trace level is maintained in the range
[Trace.HIGHEST_LEVEL, Trace.LOWEST_LEVEL ]
protected BaseTraceWriter(String, String))
BaseTraceWriter which only traces the lowest level ie
severity level, Trace.LOWEST_LEVEL messages
Methods
void close()
protected void doClose()
protected void doFlush()
protected abstract void doPrintln(String, int)
Must be implemented by the various TraceWriters extending
BaseTraceWriter to provide the specific tracing
functionality
void flush()
int[] getTraceLevels()
void println(String, int)
void setTraceLevels(int[])


OL-7242-02 2-285
BaseTraceWriter
Constructors
BaseTraceWriter(int[], String, String)
protected BaseTraceWriter(int[] traceLevels,
java.lang.String name, java.lang.String description)
BaseTraceWriter with trace levels as passed in traceLevels in the array falling

outside the range Trace.LOWEST_LEVEL and Trace.HIGHEST_LEVEl are
ignored
Parameters:
traceLevels - array of trace levels
See Also:
Trace
BaseTraceWriter(int, String, String)

protected BaseTraceWriter(int maxTraceLevel,
java.lang.String name, java.lang.String description)
BaseTraceWriter that traces all levels up to the maxTraceLevel The trace

level is maintained in the range [Trace.HIGHEST_LEVEL,
Trace.LOWEST_LEVEL]
See Also:
Trace
BaseTraceWriter(String, String)
protected BaseTraceWriter(java.lang.String name,
java.lang.String description)
BaseTraceWriter which only traces the lowest level ie severity level,

Trace.LOWEST_LEVEL messages
See Also:
Trace

2-286 OL-7242-02
BaseTraceWriter
Methods
close()
public final void close()
Description copied from interface:

com.cisco.services.tracing.TraceWriter
Releases any resources associated by this TraceWriter.
Specified By:
close in interface TraceWriter
doClose()
doFlush()
doPrintln(String, int)
protected abstract void doPrintln(java.lang.String message,
int messageNumber)

BaseTraceWriter to provide the specific tracing functionality
flush()
public final void flush()

Forces output of any messages that have been printed using the println
method
Specified By:
flush in interface TraceWriter

OL-7242-02 2-287
BaseTraceWriter
getDescription()
public final java.lang.String getDescription()
Specified By:
getDescription in interface TraceWriter
getEnabled()

Returns whether the println method will print anything or not. A closed
TraceWriter will always return false from this method.
Specified By:
getEnabled in interface TraceWriter
getName()
public final java.lang.String getName()
Specified By:
getName in interface TraceWriter
getTraceLevels()
public final int[] getTraceLevels()
Specified By:
getTraceLevels in interface TraceWriter
println(String, int)
public final void println(java.lang.String message, int severity)

Prints the specified string followed by a carriage return The concrete
TraceWriter class will use the severity to block out messages from a
particular stream. Each trace writer has a notion of the highest level trace it
traces

2-288 OL-7242-02
ConditionalTrace
Specified By:
println in interface TraceWriter
setTraceLevels(int[])
public final void setTraceLevels(int[] levels)

set the trace levels that will be traced by this TraceWriter
Specified By:
setTraceLevels in interface TraceWriter
toString()
public final java.lang.String toString()
Overrides:
ConditionalTrace
Declaration
public interface ConditionalTrace extends Trace
All Superinterfaces
Trace
Description
The ConditionalTrace interface extends the Trace interface and defines
the methods that allow enabling and disabling of tracing for this particular
condition.

OL-7242-02 2-289
ConditionalTrace
Typically, applications obtain one ConditionalTrace object for each condition that
they need to trace under certain circumstances but not always (for example,
AUDIT, INFO, and so on).
Member Summary
Methods
void disable()
Disables this condition for tracing.
void enable()
Enables this condition for tracing.

Fields inherited from interface Trace
ALERTS, ALERTS_TRACE_NAME, CRITICAL, CRITICAL_TRACE_NAME, DEBUGGING,
DEBUGGING_TRACE_NAME, EMERGENCIES, EMERGENCIES_TRACE_NAME, ERROR, ERROR_TRACE_NAME,
HIGHEST_LEVEL, INFORMATIONAL, INFORMATIONAL_TRACE_NAME, LOWEST_LEVEL, NOTIFICATION,
NOTIFICATION_TRACE_NAME, WARNING, WARNING_TRACE_NAME
Methods inherited from interface Trace

getName(), getSubFacility(), getType(), isEnabled(), println(Object), println(String),
println(String, Object), println(String, String), setDefaultMnemonic(String)
Methods
disable()
public void disable()
Disables this condition for tracing.
enable()
public void enable()
Enables this condition for tracing.

2-290 OL-7242-02
ConsoleTraceWriter
ConsoleTraceWriter
Declaration
public final class ConsoleTraceWriter extends BaseTraceWriter
java.lang.Object
|
|
+--com.cisco.services.tracing.ConsoleTraceWriter

TraceWriter
Description
Supplies a console TraceWriter to trace to System.out.
See Also:
Trace
Member Summary
Constructors
ConsoleTraceWriter()
Default constructor, traces all severity levels
ConsoleTraceWriter(int)
Constructor that sets the maximum level to be traced.
ConsoleTraceWriter(int[])
Construct a ConsoleTraceWriter with an array of trace
levels Only traces with the severity in the tracelevel
array are traced
Methods

OL-7242-02 2-291
ConsoleTraceWriter
Member Summary
protected void doPrintln(String, int)

Methods inherited from class BaseTraceWriter
close(), doClose(), flush(), getDescription(), getEnabled(), getName(),
getTraceLevels(), println(String, int), setTraceLevels(int[]), toString()

Constructors
ConsoleTraceWriter()
public ConsoleTraceWriter()
Default constructor, traces all severity levels
ConsoleTraceWriter(int)
public ConsoleTraceWriter(int maxTraceLevel)
Constructor that sets the maximum level to be traced.
See Also:
Trace
ConsoleTraceWriter(int[])
public ConsoleTraceWriter(int[] traceLevels)
Construct a ConsoleTraceWriter with an array of trace levels Only traces with

the severity in the tracelevel array are traced

2-292 OL-7242-02
ConsoleTraceWriter
Parameters:
int - [] traceLevels
See Also:
Trace
Methods
doFlush()
protected final void doFlush()
Overrides:
doFlush in class BaseTraceWriter
protected final void doPrintln(java.lang.String message,
int messageNumber)
Description copied from class:

com.cisco.services.tracing.BaseTraceWriter
Overrides:
doPrintln in class BaseTraceWriter
main(String[])

OL-7242-02 2-293
LogFileTraceWriter
LogFileTraceWriter
Declaration
public final class LogFileTraceWriter extends BaseTraceWriter
java.lang.Object
|
|
+--com.cisco.services.tracing.LogFileTraceWriter

TraceWriter
Description
This class extends the BaseTraceWriter class to implement a
TraceWriter that writes to a set of log files, rotating among them as each
becomes filled to a specified capacity and stores them in a specified directory.
Each of the log files is named according to a pattern controlled by three properties,
CurrentFile, FileNameBase, and FileExtension. The
CurrentFile property determines which log file, by ordinal number, is being
written at present, the FileNameBase property determines the prefix of each
log file name, and the FileExtension property determines the suffix, e.g.
“txt”. From these properties, log files are named FileNameBase
LeadingZeroPadding CurrentFile.FileExtension. The CurrentFile property
takes on a value from 1 to the value of the MaxFiles property. Note that the
CurrentFile property, when converted to a String, is padded with leading
zeroes depending on the values of the MaxFiles and CurrentFile
properties. An index file tracks the index of the last file written. If the
logFileWriter is recreated (for example if an application is restarted) new files
will continue from the last written index.

2-294 OL-7242-02
LogFileTraceWriter
Where the log files are stored is determined by the path, dirNameBase,
useSameDir. If a path is not specified, the current path is used as default. If a
dirNameBase is not specified, it write log files in the path. Depending upon
whether useSameDir is true or false, files are written to the same directory or a
new directory, each time an instance of LogFileTraceWriter is created. In case
new directories are being made each time, the directory name will consist of the
dirNameBase and a number, separated by an ’_’. The number is one more than
the greatest number associated with directories with the same dirNameBame in
the path. While specifying the path, you may use either a “/” or “\\”, but not “\”
The LogFileTraceWriter keeps track of how many bytes have been written
to the current log file. When that number grows within approximately
LogFileTraceWriter.ROLLOVER_THRESHOLD bytes, tracing continues
to the next file, which is either CurrentFile + 1 if CurrentFile is not
equal to MaxFiles, or 1 if CurrentFile is equal to MaxFiles.
Note All properties of this class are specified in the constructor; there is no way to
change them dynamically. Caveat: If two instances of LogFileTraceWriter are
created with the same path and dirNameBase, and useSameDir is true, they
may write to the same file.
Example
The following code instantiates a LogFileTraceWriter that will create log
files called “MyLog01.log” through “MyLog12.log”. Each file will grow to
approximately 100K bytes in size before the next file is created:
LogFileTraceWriter out = new LogFileTraceWriter (
“MyLog”, “log”, 12, 100 * 1024 ); will create a log file
TraceWriter which will rotate traces to 12 files from
Mylog01.log and Mylog12.log with a file size of 100
KBytes. By default the tracing is set to the
HIGHEST_LEVEL.
Example
The following code constructs a LogFileTraceWriter which stores the log
files in the path “c:/LogFiles” in a sub directory, “Run”. The files will be named
MyLogXX.log. The number of rotating files will be 12 with a size of 100 KB. The
same directory gets used for each instance of the application.

OL-7242-02 2-295
LogFileTraceWriter
LogFileTraceWriter out = new LogFileTraceWriter (“c:/logFiles”, “Run”,

“MyLog”, “log”, 12, 100*1024, true);
See Also:
Trace
Member Summary
Fields
static java.lang.String DEFAULT_FILE_NAME_BASE
static java.lang.String DEFAULT_FILE_NAME_EXTENSION
static char DIR_BASE_NAME_NUM_SEPERATOR
static int MIN_FILE_SIZE
static int MIN_FILES
static int ROLLOVER_THRESHOLD
Constructors
LogFileTraceWriter(String, String, int, int)
Default constructor for LogFileTraceWriter that rotates
among an arbitrary number of files with tracing for all
levels.
LogFileTraceWriter(String, String, String, String, int, int,
boolean)
Default constructor for LogFileTraceWriter that rotates
among an arbitrary number of files with tracing for all
levels.
LogFileTraceWriter(String, String, String, String, int, int,
int, boolean)
Constructs a LogFileTraceWriter that rotates among an
arbitrary number of files storing them in a specified
directory.
Methods
Closes this OutputStream.
int getCurrentFile()
Returns the CurrentFile property
java.lang.String getFileExtension()
Returns the FileExtension property
java.lang.String getFileNameBase()
Returns the FileNameBase property

2-296 OL-7242-02
LogFileTraceWriter
Member Summary
java.lang.String getHeader()
Get the header string that will be written at the
beginning of each log file.
int getMaxFiles()
Returns the MaxFiles property
int getMaxFileSize()
Returns the MaxFileSize property
void setHeader(String)
Set the constant header string that will be written at
the beginning of every file, trace writing continues from
the next line after the header is written.


Fields
DEFAULT_FILE_NAME_BASE
public static final java.lang.String DEFAULT_FILE_NAME_BASE
DEFAULT_FILE_NAME_EXTENSION
public static final java.lang.String DEFAULT_FILE_NAME_EXTENSION
DIR_BASE_NAME_NUM_SEPERATOR
public static final char DIR_BASE_NAME_NUM_SEPERATOR

OL-7242-02 2-297
LogFileTraceWriter
MIN_FILE_SIZE
public static final int MIN_FILE_SIZE
MIN_FILES
public static final int MIN_FILES
ROLLOVER_THRESHOLD
public static final int ROLLOVER_THRESHOLD
Constructors
LogFileTraceWriter(String, String, int, int)
public LogFileTraceWriter(java.lang.String fileNameBase,
java.lang.String fileNameExtension, int maxFiles,
int maxFileSize)
throws IOException
Default constructor for LogFileTraceWriter that rotates among an arbitrary

number of files with tracing for all levels. Since a path and Directory Base
name is not specified, it writes the files to the current directory without any
sub directories.
Throws:
java.io.IOException
LogFileTraceWriter(String, String, String, String, int, int, boolean)

public LogFileTraceWriter(java.lang.String path,
java.lang.String dirNameBase, java.lang.String fileNameBase,
int maxFileSize, boolean useSameDir)
throws IOException
Default constructor for LogFileTraceWriter that rotates among an arbitrary

number of files with tracing for all levels.
Throws:
java.io.IOException

2-298 OL-7242-02
LogFileTraceWriter
LogFileTraceWriter(String, String, String, String, int, int, int, boolean)

public LogFileTraceWriter(java.lang.String path,
java.lang.String dirNameBase, java.lang.String fileNameBase,
int maxFileSize, int maxTraceLevel, boolean useSameDir)
throws IOException
Constructs a LogFileTraceWriter that rotates among an arbitrary number of

files storing them in a specified directory.
Throws:
java.io.IOException
Methods
doClose()
Closes this OutputStream. Any log file that is currently open will be closed
as well.
Overrides:
doClose in class BaseTraceWriter
doFlush()
Overrides:
protected void doPrintln(java.lang.String message,
int messageNumber)


OL-7242-02 2-299
LogFileTraceWriter

Overrides:
getCurrentFile()
public int getCurrentFile()
Returns the CurrentFile property

Returns:
the CurrentFile property
getFileExtension()
public java.lang.String getFileExtension()
Returns the FileExtension property

Returns:
the FileExtension property
getFileNameBase()
public java.lang.String getFileNameBase()
Returns the FileNameBase property

Returns:
the FileNameBase property
getHeader()
public java.lang.String getHeader()
Get the header string that will be written at the beginning of each log file.
Returns:
the Header Property

2-300 OL-7242-02
LogFileTraceWriter
getMaxFiles()
public int getMaxFiles()
Returns the MaxFiles property

Returns:
the MaxFiles property
getMaxFileSize()
public int getMaxFileSize()
Returns the MaxFileSize property

Returns:
the MaxFileSize property
setHeader(String)
public void setHeader(java.lang.String header)
Set the constant header string that will be written at the beginning of every
file, trace writing continues from the next line after the header is written. If
setHeader is called after a file output has started, it will take effect from
the next file to be written.
Usage:
tm = TraceManagerFactory.registerModule( this );
tw = new LogFileTraceWriter ( “trace”, “log”, 10, 1024*1024);
tw.setHeader ( header );
tm.getTraceWriterManager ().addTraceWriter (tw);

OL-7242-02 2-301
OutputStreamTraceWriter
Declaration
public final class OutputStreamTraceWriter extends BaseTraceWriter
java.lang.Object
|
|
+--com.cisco.services.tracing.OutputStreamTraceWriter

TraceWriter
Description
OutputStreamTraceWriter wraps an output stream in a TraceWriter. This
simplifies adding custom tracing classes that can co-exist with other
TraceWriters.
Member Summary
Constructors
OutputStreamTraceWriter(int, OutputStream)
Default constructor which is auto-flushing
OutputStreamTraceWriter(int, OutputStream, boolean)
Create an OutputStreamTraceWriter
Methods
java.io.OutputStream getOutputStream()

2-302 OL-7242-02


Constructors
OutputStreamTraceWriter(int, OutputStream)
public OutputStreamTraceWriter(int maxTraceLevel,
java.io.OutputStream outputStream)
Default constructor which is auto-flushing
See Also:
Trace
OutputStreamTraceWriter(int, OutputStream, boolean)

public OutputStreamTraceWriter(int maxTraceLevel,
java.io.OutputStream outputStream, boolean autoFlush)
Create an OutputStreamTraceWriter
See Also:
Trace
Methods
doClose()
Overrides:

OL-7242-02 2-303
SyslogTraceWriter
doFlush()
Overrides:
int messageNumber)

Overrides:
getOutputStream()
public java.io.OutputStream getOutputStream()
Returns:
the output stream associated with the TraceWriter
SyslogTraceWriter
Declaration
public final class SyslogTraceWriter extends BaseTraceWriter
java.lang.Object
|
|
+--com.cisco.services.tracing.SyslogTraceWriter

2-304 OL-7242-02
SyslogTraceWriter

TraceWriter
Description
SyslogTraceWriter refines the BaseTraceWriter to allow tracing to
syslog. Cisco syslog specification calls for sending low level traces to a syslog
collector in the form of UDP messages. No buffering is done in this TraceWriter.
The SyslogTraceWriter makes an exception to the println() method in that
it places a ’\0’ instead of a System specified line separator to terminate the
message packet.
Member Summary
Constructors
SyslogTraceWriter(int, String)
Default SyslogTraceWriter with a max trace level of
INFORMATIONAL
SyslogTraceWriter(int, String, int)
SyslogTraceWriter with max trace level specified
SyslogTraceWriter(int, String, int[])
SyslogTraceWriter which takes an array of trace levels.
Methods
void doClose()
Closes the socket
The SyslogTraceWriter makes an exception to the println()
method in that it places a ’\0’ instead of a System
specified line separator to terminate the message packet.


OL-7242-02 2-305
SyslogTraceWriter

Constructors
SyslogTraceWriter(int, String)
public SyslogTraceWriter(int port, java.lang.String collector)
Default SyslogTraceWriter with a max trace level of INFORMATIONAL
See Also:
Trace
SyslogTraceWriter(int, String, int)

public SyslogTraceWriter(int port, java.lang.String collector,
int maxTraceLevel)
SyslogTraceWriter with max trace level specified
See Also:
Trace
SyslogTraceWriter(int, String, int[])

public SyslogTraceWriter(int port, java.lang.String collector,
int[] traceLevels)
SyslogTraceWriter which takes an array of trace levels.
See Also:
Trace

2-306 OL-7242-02
Trace
Methods
doClose()
public void doClose()
Closes the socket

Overrides:
int messageNumber)
The SyslogTraceWriter makes an exception to the println() method in

that it places a ’\0’ instead of a System specified line separator to terminate
the message packet. The portion of the message after a ’\r’ or ’\n’ is ignored
Overrides:
main(String[])
Trace
Declaration
public interface Trace

ConditionalTrace, UnconditionalTrace

OL-7242-02 2-307
Trace
Description
The Trace interface defines the methods that allow application tracing. Trace
also defines the standard trace types as specified by Syslog Trace Logging.Syslog
currently defines 8 levels of trace. The severity of the message is indicated in the
trace as a number ranging between [0-7] (0 and 7 included). Currently 7 is
HIGHEST_LEVEL and 0 is the LOWEST_LEVEL trace. All 8 levels are
predefined here as static int types for reference in tracing sub-system
implementations.
The severities traced are as follows:
0 = EMERGENCIES System unusable
1 = ALERTS Immediate action needed
2 = CRITICAL Critical conditions
3 = ERROR Error conditions
4 = WARNING Warning conditions
5 = NOTIFICATION Normal but significant condition
6 = INFORMATIONAL Informational messages only
7 = DEBUGGING Debugging messages
Member Summary
Fields
static int ALERTS
The application will continue working on the tasks but
all functions may not be operational (one or more devices
in the list are not accessible but others in the list can
be accessed)
static java.lang.String ALERTS_TRACE_NAME
String descriptor for ALERTS trace level
static int CRITICAL
A critical failure, the application can not accomplish
the tasks required due to this failure, eg: the app cant
open the database to read the device list
static java.lang.String CRITICAL_TRACE_NAME
String descriptor for CRITICAL trace level

2-308 OL-7242-02
Trace
Member Summary
static int DEBUGGING
Very detailed information regarding errors or processing
status that is only generated when DEBUG mode has been
enabled
static java.lang.String DEBUGGING_TRACE_NAME
String descriptor for the DEBUGGING trace level
static int EMERGENCIES
static java.lang.String EMERGENCIES_TRACE_NAME
String descriptor for EMERGENCIES trace level
static int ERROR
An error condition of some kind has occurred and the user
needs to understand the nature of that failure
static java.lang.String ERROR_TRACE_NAME
String descriptor for ERROR trace level
static int HIGHEST_LEVEL
The highest trace level, currently this is DEBUGGING with
a trace level of 7
static int INFORMATIONAL
Information of some form not relating to errors,
warnings, audit, or debug
static java.lang.String INFORMATIONAL_TRACE_NAME
String descriptor for INFORMATIONAL trace level
static int LOWEST_LEVEL
The lowest trace level, currently this is EMERGENCIES
with a trace level of 0
static int NOTIFICATION
static java.lang.String NOTIFICATION_TRACE_NAME
String descriptor for NOTIFICATION trace level
static int WARNING
Warning that a problem of some form exists but is not
keeping the application from completing its tasks
static java.lang.String WARNING_TRACE_NAME
String descriptor for WARNING trace level
Methods
Returns the name of this Trace object.

OL-7242-02 2-309
Trace
Member Summary
Returns the subFacility of trace
int getType()
Returns the type of trace.
boolean isEnabled()
Returns the state of this Trace object.
void println(Object)
Prints the string returned by the Object.toString()
method and terminates the line as defined by the system.
void println(String)
Prints a message in the same format as Trace.print() and
terminates the line as defined by the system.
void println(String, Object)
Prints the string returned by the Object.toString()
method and terminates the line as defined by the system.
void println(String, String)
Prints a message in the same format as Trace.print() and
terminates the line as defined by the system.
void setDefaultMnemonic(String)
Sets a default mnemonic for all messages printed out to
this trace.
Fields
ALERTS
public static final int ALERTS
The application will continue working on the tasks but all functions may not
be operational (one or more devices in the list are not accessible but others in
the list can be accessed)
ALERTS_TRACE_NAME
public static final java.lang.String ALERTS_TRACE_NAME
String descriptor for ALERTS trace level

2-310 OL-7242-02
Trace
CRITICAL
public static final int CRITICAL
A critical failure, the application can not accomplish the tasks required due
to this failure, eg: the app cant open the database to read the device list
CRITICAL_TRACE_NAME
public static final java.lang.String CRITICAL_TRACE_NAME
String descriptor for CRITICAL trace level
DEBUGGING
public static final int DEBUGGING
Very detailed information regarding errors or processing status that is only

generated when DEBUG mode has been enabled
DEBUGGING_TRACE_NAME
public static final java.lang.String DEBUGGING_TRACE_NAME
String descriptor for the DEBUGGING trace level
EMERGENCIES
public static final int EMERGENCIES

EMERGENCIES_TRACE_NAME
public static final java.lang.String EMERGENCIES_TRACE_NAME
String descriptor for EMERGENCIES trace level
ERROR
public static final int ERROR
An error condition of some kind has occurred and the user needs to
understand the nature of that failure

OL-7242-02 2-311
Trace
ERROR_TRACE_NAME
public static final java.lang.String ERROR_TRACE_NAME
String descriptor for ERROR trace level
HIGHEST_LEVEL
public static final int HIGHEST_LEVEL
The highest trace level, currently this is DEBUGGING with a trace level of 7
INFORMATIONAL
public static final int INFORMATIONAL
Information of some form not relating to errors, warnings, audit, or debug

INFORMATIONAL_TRACE_NAME
public static final java.lang.String INFORMATIONAL_TRACE_NAME
String descriptor for INFORMATIONAL trace level
LOWEST_LEVEL
public static final int LOWEST_LEVEL
The lowest trace level, currently this is EMERGENCIES with a trace level of
0
NOTIFICATION
public static final int NOTIFICATION

NOTIFICATION_TRACE_NAME
public static final java.lang.String NOTIFICATION_TRACE_NAME
String descriptor for NOTIFICATION trace level

2-312 OL-7242-02
Trace
WARNING
public static final int WARNING
Warning that a problem of some form exists but is not keeping the application
from completing its tasks
WARNING_TRACE_NAME
public static final java.lang.String WARNING_TRACE_NAME
String descriptor for WARNING trace level
Methods
getName()
Returns the name of this Trace object.

Returns:
the name of this Trace object
getSubFacility()
Returns the subFacility of trace

Returns:
the trace subFacility type
getType()
public int getType()
Returns the type of trace.

Returns:
the trace severity as specified in Syslog. DEBUGGING,
INFORMATIONAL, WARNING, etc.

OL-7242-02 2-313
Trace
isEnabled()
public boolean isEnabled()
Returns the state of this Trace object. By default, Trace objects are enabled,
that is, println() method will always trace. The state may not be changed
through this interface, however, this object may implement additional
interfaces that allow the state to be changed.
Returns:
true if tracing is enabled, false otherwise
See Also:
ConditionalTrace
println(Object)
public void println(java.lang.Object object)
Prints the string returned by the Object.toString() method and terminates the
line as defined by the system.
Parameters:
object - the object to be printed
println(String)
public void println(java.lang.String message)
Prints a message in the same format as Trace.print() and terminates the line
as defined by the system.
Parameters:
message - the message to be printed

2-314 OL-7242-02
TraceManager
println(String, Object)
public void println(java.lang.String mnemonic,
java.lang.Object object)
Prints the string returned by the Object.toString() method and terminates the
line as defined by the system.
Parameters:
object - the object to be printed
mnemonic - the mnemonic mapped to message to be printed
println(String, String)
public void println(java.lang.String mnemonic,
java.lang.String message)
Prints a message in the same format as Trace.print() and terminates the line
as defined by the system.
Parameters:
message - the message to be printed
mnemonic - the mnemonic mapped to message to be printed
setDefaultMnemonic(String)
public void setDefaultMnemonic(java.lang.String mnemonic)
Sets a default mnemonic for all messages printed out to this trace.
Parameters:
mnemonic, - a mnemonic string
TraceManager
Declaration
public interface TraceManager

OL-7242-02 2-315
TraceManager
Description
The TraceManager interface defines the methods that allow applications trace
management.
Typically, an application obtains only one TraceManager object. All Trace objects
are created by default: Predefined Trace in accordance with Syslog definitions
are:
ConditionalTraces: INFORMATIONAL, DEBUGGING, NOTIFICATION, WARNING

UnconditionalTraces: ERROR, CRITICAL, ALERTS, EMERGENCIES
Facilities/Sub-Facilities:
• Facility—A code consisting of two or more uppercase letters that indicate the
facility to which the message refers. A facility can be a hardware device, a
protocol, or a module of the system software.
• SubFacility—A code consisting of two or more uppercase letters that
indicate the sub-facility to which the message refers. A sub-facility can be a
hardware device component, a protocol unit, or a sub-module of the system
software.
By default all 8 Conditional and UnConditional Traces are created for the Facility
and 8 for each of the subFacilities In order to use the DEBUGGING trace for the
parent FACILITY, for example, the application needs to use the
getConditionalTrace( “DEBUGGING” ) method of this object.
In order to use the DEBUGGING trace for the SUBFACILITY, for example, the
application needs to use the getConditionalTrace( SUBFACILITY + “_” +
“DEBUGGING” ) method of this object or use the getConditionalTrace(
SUBFACILITY, “DEBUGGING” ) method.
System wide TraceWriterManager is set through the setTraceWriterManager
method provided by this interface.
The Trace Manager object also allows the application to enable or disable tracing
for all trace through the enableAll() and disableAll() methods.

2-316 OL-7242-02
TraceManager
Member Summary
Methods
void addSubFacilities(String[])
Sets a set of subFacilities for this
TraceManager/Facility.
void addSubFacility(String)
Adds a single subFacility for this TraceManager/Facility.
void disableAll()
Disables tracing for all Trace objects managed by this
TraceManager.
void disableTimeStamp()
Disables prefixing a time stamp for every message printed
by this TraceManager.
void enableAll()
Enables tracing for all Trace objects managed by this
TraceManager.
void enableTimeStamp()
Enables prefixing a time stamp for every message printed
by this TraceManager.
ConditionalTrace getConditionalTrace(int)
Creates a new ConditionalTrace object or obtains an
existing ConditionalTrace object for this condition.
ConditionalTrace getConditionalTrace(String, int)
Creates a new ConditionalTrace object or obtains an
existing ConditionalTrace object for this condition and
subFacility
Returns the Facility name for this TraceManager.
java.lang.String[] getSubFacilities()
Returns the subFacility names for this
java.util.Enumeration getTraces()
Returns an enumeration of the Trace objects managed by
this TraceManager.
TraceWriterManager getTraceWriterManager()
Returns the TraceWriter used by this TraceManager.
UnconditionalTrace getUnconditionalTrace(int)
Creates a new UnconditionalTrace object or obtains an
existing UnconditionalTrace object for this condition.
UnconditionalTrace getUnconditionalTrace(String, int)
Creates a new UnconditionalTrace object or obtains an
existing UnconditionalTrace object for this condition and
subFacility
void removeTrace(Trace)
Removes a Trace object given an object.

OL-7242-02 2-317
TraceManager
Member Summary
void setSubFacilities(String[])
Sets a set of subFacilities for this
void setSubFacility(String)
void setTraceWriterManager(TraceWriterManager)
Sets the TraceWriter to be used by this TraceManager.
Methods
addSubFacilities(String[])
public void addSubFacilities(java.lang.String[] names)
Sets a set of subFacilities for this TraceManager/Facility.
addSubFacility(String)
public void addSubFacility(java.lang.String name)
disableAll()
public void disableAll()
Disables tracing for all Trace objects managed by this TraceManager.
disableTimeStamp()
public void disableTimeStamp()
Disables prefixing a time stamp for every message printed by this

TraceManager.
enableAll()
public void enableAll()
Enables tracing for all Trace objects managed by this TraceManager.

2-318 OL-7242-02
TraceManager
enableTimeStamp()
public void enableTimeStamp()
Enables prefixing a time stamp for every message printed by this

TraceManager.
getConditionalTrace(int)
public com.cisco.services.tracing.ConditionalTrace
getConditionalTrace(int severity)
Creates a new ConditionalTrace object or obtains an existing

ConditionalTrace object for this condition.
getConditionalTrace(String, int)
public com.cisco.services.tracing.ConditionalTrace
getConditionalTrace(java.lang.String subFacility, int severity)
Creates a new ConditionalTrace object or obtains an existing

ConditionalTrace object for this condition and subFacility
getName()
Returns the Facility name for this TraceManager.
getSubFacilities()
public java.lang.String[] getSubFacilities()
Returns the subFacility names for this TraceManager/Facility.
getTraces()
public java.util.Enumeration getTraces()
Returns an enumeration of the Trace objects managed by this TraceManager.
getTraceWriterManager()
public com.cisco.services.tracing.TraceWriterManager
getTraceWriterManager()
Returns the TraceWriter used by this TraceManager.

OL-7242-02 2-319
TraceManager
getUnconditionalTrace(int)
public com.cisco.services.tracing.UnconditionalTrace
getUnconditionalTrace(int severity)
Creates a new UnconditionalTrace object or obtains an existing

UnconditionalTrace object for this condition.
getUnconditionalTrace(String, int)
public com.cisco.services.tracing.UnconditionalTrace
getUnconditionalTrace(java.lang.String subFacility,
int severity)
Creates a new UnconditionalTrace object or obtains an existing

UnconditionalTrace object for this condition and subFacility
removeTrace(Trace)
public void removeTrace(com.cisco.services.tracing.Trace tc)
Removes a Trace object given an object.
setSubFacilities(String[])
public void setSubFacilities(java.lang.String[] names)
Deprecated.
and replaced with TraceManager.addSubFacilities method
Sets a set of subFacilities for this TraceManager/Facility.
setSubFacility(String)
public void setSubFacility(java.lang.String name)
Deprecated.
and replaced with TraceManager.addSubFacility method
setTraceWriterManager(TraceWriterManager)
public void
setTraceWriterManager(com.cisco.services.tracing.TraceWriterMan
ager twm)
Sets the TraceWriter to be used by this TraceManager.

2-320 OL-7242-02
TraceManagerFactory
TraceManagerFactory
Declaration
public class TraceManagerFactory
java.lang.Object
|
+--com.cisco.services.tracing.TraceManagerFactory
Description
The TraceManagerFactory class is a class by which applications obtain a
TraceManager object. The TraceModule passed in the constructor is registered in
a list. The list can be enumerated using the getModules() method.
Member Summary
Methods
static getModules()
java.util.Enumeration Returns an enumeration of the TraceModules registered
with this factory.
static TraceManager registerModule(TraceModule)
Returns an instance of a TraceManager object.
static TraceManager registerModule(TraceModule, String[], TraceWriterManager))
static TraceManager registerModule(TraceModule, TraceWriterManager)


OL-7242-02 2-321
TraceManagerFactory
Methods
getModules()
public static java.util.Enumeration getModules()
Returns an enumeration of the TraceModules registered with this factory.
registerModule(TraceModule)
public static com.cisco.services.tracing.TraceManager
registerModule(com.cisco.services.tracing.TraceModule module)
Returns an instance of a TraceManager object. The contained

TraceWriterManager will not have any default TraceWriters.
registerModule(TraceModule, String[], TraceWriterManager)

registerModule(com.cisco.services.tracing.TraceModule module,
java.lang.String[] subFacilities,
com.cisco.services.tracing.TraceWriterManager traceWriterManage
r)
Returns an instance of a TraceManager object. Trace output will be redirected

to the TraceWriterManager object specified.
registerModule(TraceModule, TraceWriterManager)
registerModule(com.cisco.services.tracing.TraceModule module,
com.cisco.services.tracing.TraceWriterManager traceWriterManage
r)
Returns an instance of a TraceManager object. Trace output will be redirected

to the TraceWriterManager object specified.

2-322 OL-7242-02
TraceModule
TraceModule
Declaration
public interface TraceModule

com.cisco.jtapi.extensions.CiscoJtapiPeer
Description
The TraceModule interface serves two purposes. First, it allows applications to
discover the TraceManager object used by other packages that they use. Second,
applications that register with the TraceManagerFactory must identify themselves
by implementing this interface.
Member Summary
Methods
TraceManager getTraceManager()
Returns the TraceManager that an object is using for
tracing.
java.lang.String getTraceModuleName()
Returns the module name.
Methods
getTraceManager()
public com.cisco.services.tracing.TraceManager getTraceManager()
Returns the TraceManager that an object is using for tracing.

OL-7242-02 2-323
TraceWriter
getTraceModuleName()
public java.lang.String getTraceModuleName()
Returns the module name.
TraceWriter
Declaration
public interface TraceWriter

TraceWriterManager

BaseTraceWriter
Description
The TraceWriter interface abstracts the details of trace message output. The
TraceWriter uses its enabled method to advertise whether or not the
print and println methods will have any effect. Users of TraceWriter should
use the value returned by the getEnabled method as an indication of whether
they should invoke the print and println methods at all.
Member Summary
Methods
void close()

2-324 OL-7242-02
TraceWriter
Member Summary
void flush()
Forces output of any messages that have been printed
using the println method
Returns whether the println method will print anything or
not.
int[] getTraceLevels()
void println(String, int)
Prints the specified string followed by a carriage return
The concrete TraceWriter class will use the severity to
block out messages from a particular stream.
void setTraceLevels(int[])
set the trace levels that will be traced by this
TraceWriter
Methods
close()
public void close()
flush()
public void flush()
Forces output of any messages that have been printed using the println
method
getDescription()
Returns:
a short description of this TraceWriter

OL-7242-02 2-325
TraceWriter
getEnabled()
Returns whether the println method will print anything or not. A closed
TraceWriter will always return false from this method.
Returns:
true if this TraceWriter is enabled, false if not
getName()
Returns:
the name of this TraceWriter
getTraceLevels()
public int[] getTraceLevels()
Returns:
the array of trace levels that will be traced by this TraceWriter
println(String, int)
public void println(java.lang.String message, int severity)
Prints the specified string followed by a carriage return The concrete

TraceWriter class will use the severity to block out messages from a
particular stream. Each trace writer has a notion of the highest level trace it
traces
Parameters:
message - the string to print
severity - of the trace.
See Also:
Trace

2-326 OL-7242-02
TraceWriterManager
setTraceLevels(int[])
public void setTraceLevels(int[] levels)
set the trace levels that will be traced by this TraceWriter

Parameters:
int[] - levels
See Also:
Trace
TraceWriterManager
Declaration
public interface TraceWriterManager extends TraceWriter
All Superinterfaces
TraceWriter
Description
TraceWriterManager contains the list of TraceWriter objects that are used to
implement the tracing. The list is populated at startup from the switches in a .ini
file. A LogFileTraceWriter, a ConsoleTraceWriter, and a SyslogTraceWriter are
available. Users can override the existing TraceWriters by setting a user
implemented TraceWriter[] or adding to the existing TraceWriters. This makes it
possible to add other TraceWriters that can function along with existing trace
writers.

OL-7242-02 2-327
TraceWriterManager
Member Summary
Methods
void addTraceWriter(TraceWriter)
Add another TraceWriter to the array
TraceWriter[] getTraceWriters()
void removeTraceWriter(TraceWriter)
Remove the TraceWriter from the array in the manager
void setTraceWriters(TraceWriter[])
Implementations can use this method to override or
enhance the provided TraceWriters

Methods inherited from interface TraceWriter
close(), flush(), getDescription(), getEnabled(), getName(), getTraceLevels(),
println(String, int), setTraceLevels(int[])
Methods
addTraceWriter(TraceWriter)
public void
addTraceWriter(com.cisco.services.tracing.TraceWriter
traceWriter)
Add another TraceWriter to the array

Parameters:
TraceWriter - to be added to the list
getTraceWriters()
public com.cisco.services.tracing.TraceWriter[] getTraceWriters()
Returns:
the array of TraceWriters in the manager

2-328 OL-7242-02
UnconditionalTrace
removeTraceWriter(TraceWriter)
public void
removeTraceWriter(com.cisco.services.tracing.TraceWriter
traceWriter)
Remove the TraceWriter from the array in the manager
setTraceWriters(TraceWriter[])
public void
setTraceWriters(com.cisco.services.tracing.TraceWriter[]
traceWriters)
Implementations can use this method to override or enhance the provided

TraceWriters
Parameters:
set - the array of TraceWriters.
UnconditionalTrace
Declaration
public interface UnconditionalTrace extends Trace
All Superinterfaces
Trace
Description
The UnconditionalTrace interface extends the Trace interface. Note that
because this object extends Trace, its state is enabled by default and it may not be
changed.

OL-7242-02 2-329
UnconditionalTrace
Typically, applications would obtain one UnconditionalTrace object per each

condition that they need to trace always under any circumstances (such as,
ERROR, FATAL, and so on).

Fields inherited from interface Trace
ALERTS, ALERTS_TRACE_NAME, CRITICAL, CRITICAL_TRACE_NAME, DEBUGGING,
DEBUGGING_TRACE_NAME, EMERGENCIES, EMERGENCIES_TRACE_NAME, ERROR, ERROR_TRACE_NAME,
HIGHEST_LEVEL, INFORMATIONAL, INFORMATIONAL_TRACE_NAME, LOWEST_LEVEL, NOTIFICATION,
NOTIFICATION_TRACE_NAME, WARNING, WARNING_TRACE_NAME
Methods inherited from interface Trace

getName(), getSubFacility(), getType(), isEnabled(), println(Object), println(String),
println(String, Object), println(String, String), setDefaultMnemonic(String)

2-330 OL-7242-02
C H A P T E R 3
JTAPI Examples
This chapter provides the source code for makecall, the Cisco JTAPI program that
is used to test the JTAPI installation. The makecall program comprises a series of
programs that were written in Java by using the Cisco JTAPI implementation.
This chapter contains the following sections:
• MakeCall.java
• Actor.java
• Originator.java
• Receiver.java
• StopSignal.java
• Trace.java
• TraceWindow.java
This Chapter also provides instructions on how to invoke makecall:
• Running makecall

OL-7242-02 3-1
Chapter 3 JTAPI Examples
MakeCall.java
MakeCall.java
/**
* makecall.java
*
* Copyright Cisco Systems, Inc.
*
* Performance-testing application (first pass) for Cisco JTAPI
* implementation.
*
* Known problems:
*
* Due to synchronization problems between Actors, calls may
* not be cleared when this application shuts down.
*
*/
//import com.ms.wfc.app.*;
import java.util.*;
import javax.telephony.*;
import javax.telephony.events.*;
import com.cisco.cti.util.Condition;
public class makecall extends TraceWindow implements ProviderObserver

{
Vector actors = new Vector ();
ConditionconditionInService = new Condition ();
Providerprovider;
public makecall ( String [] args ) {
super ( "makecall" + ": "+ new CiscoJtapiVersion());

try {
println ( "Initializing Jtapi" );

int curArg = 0;
String providerName = args[curArg++];
String login = args[curArg++];
String passwd = args[curArg++];
int actionDelayMillis = Integer.parseInt ( args[curArg++] );
String src = null;
String dest = null;
JtapiPeer peer = JtapiPeerFactory.getJtapiPeer ( null );

if ( curArg < args.length ) {

3-2 OL-7242-02
MakeCall.java
String providerString = providerName + ";login=" + login + ";passwd=" +

passwd;
println ( "Opening " + providerString + "...\n" );
provider = peer.getProvider ( providerString );
provider.addObserver ( this );
conditionInService.waitTrue ();
println ( "Constructing actors" );
for ( ; curArg < args.length; curArg++ ) {

if ( src == null ) {
src = args[curArg];
}
else {
dest = args[curArg];
Originator originator = new Originator ( provider.getAddress ( src
), dest, this, actionDelayMillis );
actors.addElement ( originator );
actors.addElement (
new Receiver ( provider.getAddress ( dest ), this,
actionDelayMillis, originator )
);
src = null;
dest = null;
}
}
if ( src != null ) {
println ( "Skipping last originating address \"" + src + "\"; no
destination specified" );
}
Enumeration e = actors.elements ();

while ( e.hasMoreElements () ) {
Actor actor = (Actor) e.nextElement ();
actor.initialize ();
}
Enumeration en = actors.elements ();

while ( en.hasMoreElements () ) {
Actor actor = (Actor) en.nextElement ();
actor.start ();
}
}
println ( "Caught exception " + e );
}

OL-7242-02 3-3
MakeCall.java
public void dispose () {

println ( "Stopping actors" );
Enumeration e = actors.elements ();
while ( e.hasMoreElements () ) {
Actor actor = (Actor) e.nextElement ();
actor.dispose ();
}
}
public static void main ( String [] args )

{
if ( args.length < 6 ) {
System.out.println ( "Usage: makecall <server> <login> <password> <delay>
<origin> <destination> ..." );
System.exit ( 1 );
}
new makecall ( args );
}
public void providerChangedEvent ( ProvEv [] eventList ) {

if ( eventList != null ) {
for ( int i = 0; i < eventList.length; i++ )
{
if ( eventList[i] instanceof ProvInServiceEv ) {
conditionInService.set ();
}
}
}
}
}

3-4 OL-7242-02
Actor.java
Actor.java
/**
* Actor.java
*
*
*/
import javax.telephony.callcontrol.*;
import javax.telephony.callcontrol.events.*;
import com.cisco.jtapi.extensions.*;
public abstract class Actor implements AddressObserver, TerminalObserver,
CallControlCallObserver, Trace
{
public static final int ACTOR_OUT_OF_SERVICE = 0;

public static final int ACTOR_IN_SERVICE =1;
private Tracetrace;
protected intactionDelayMillis;
private AddressobservedAddress;
private Terminal observedTerminal;
private boolean addressInService;
private boolean terminalInService;
protected int state = Actor.ACTOR_OUT_OF_SERVICE;
public Actor ( Trace trace, Address observed, int actionDelayMillis ) {

this.trace = trace;
this.observedAddress = observed;
this.observedTerminal = observed.getTerminals ()[0];
this.actionDelayMillis = actionDelayMillis;
}
public void initialize () {
try {
if ( observedAddress != null ) {
bufPrintln (
"Adding Call observer to address "
+ observedAddress.getName ()
);
observedAddress.addCallObserver ( this );
//Now add observer on Address and Terminal

OL-7242-02 3-5
Actor.java
bufPrintln (
"Adding Adddress Observer to address "
);
observedAddress.addObserver ( this );
bufPrintln (
"Adding Terminal Observer to Terminal"
+ observedTerminal.getName ()
);
observedTerminal.addObserver ( this );
}
}
} finally {
flush ();
}
}
public final void start () {

onStart ();
}
public final void dispose () {
try {
onStop ();
if ( observedAddress != null ) {
bufPrintln (
"Removing observer from Address "
);
observedAddress.removeObserver ( this );
bufPrintln (
"Removing call observer from Address "
);
observedAddress.removeCallObserver ( this );
}
if ( observedTerminal != null ){
bufPrintln (

3-6 OL-7242-02
Actor.java
"Removing observer from terminal "

+ observedTerminal.getName ()
);
observedTerminal.removeObserver ( this );
}
}
}
finally {
flush ();
}
}
public final void stop () {

onStop ();
}
public final void callChangedEvent ( CallEv [] events ) {

//
// for now, all metaevents are delivered in the
// same package...
//
metaEvent ( events );
}
public void addressChangedEvent ( AddrEv [] events ) {
for ( int i=0; i<events.length; i++ ) {

Address address = events[i].getAddress ();
switch ( events[i].getID () ) {
case CiscoAddrInServiceEv.ID:
bufPrintln ( "Received " + events[i] + "for "+ address.getName ());
addressInService = true;
if ( terminalInService ) {
if ( state != Actor.ACTOR_IN_SERVICE ) {
state = Actor.ACTOR_IN_SERVICE ;
fireStateChanged ();
}
}
break;
case CiscoAddrOutOfServiceEv.ID:
bufPrintln ( "Received " + events[i] + "for "+ address.getName ());
addressInService = false;
if ( state != Actor.ACTOR_OUT_OF_SERVICE ) {
state = Actor.ACTOR_OUT_OF_SERVICE; // you only want to notify when
you had notified earlier that you are IN_SERVICE

OL-7242-02 3-7
Actor.java
}
break;
}
}
flush ();
}
public void terminalChangedEvent ( TermEv [] events ) {
for ( int i=0; i<events.length; i++ ) {

Terminal terminal = events[i].getTerminal ();
switch ( events[i].getID () ) {
case CiscoTermInServiceEv.ID:
bufPrintln ( "Received " + events[i] + "for " + terminal.getName ());
terminalInService = true;
if ( addressInService ) {
if ( state != Actor.ACTOR_IN_SERVICE ) {
state = Actor.ACTOR_IN_SERVICE;
}
}
break;
case CiscoTermOutOfServiceEv.ID:
bufPrintln ( "Received " + events[i] + "for " + terminal.getName () );
terminalInService = false;
if ( state != Actor.ACTOR_OUT_OF_SERVICE ) { // you only want to
notify when you had notified earlier that you are IN_SERVICE
state = Actor.ACTOR_OUT_OF_SERVICE;
}
break;
}
}
flush();
}
final void delay ( String action ) {

if ( actionDelayMillis != 0 ) {
println ( "Pausing " + actionDelayMillis + " milliseconds before " + action );
try {
Thread.sleep ( actionDelayMillis );
}
catch ( InterruptedException e ) {}
}
}
protected abstract void metaEvent ( CallEv [] events );

3-8 OL-7242-02
Actor.java
protected abstract void onStart ();

protected abstract void onStop ();
protected abstract void fireStateChanged ();
public final void bufPrint ( String string ) {

trace.bufPrint ( string );
}
public final void bufPrintln ( String string ) {
trace.bufPrint ( string );
trace.bufPrint ("\n");
}
public final void print ( String string ) {
trace.print ( string );
}
public final void print ( char character ) {
trace.print ( character );
}
public final void print ( int integer ) {
trace.print ( integer );
}
public final void println ( String string ) {
trace.println ( string );
}
public final void println ( char character ) {
trace.println ( character );
}
public final void println ( int integer ) {
trace.println ( integer );
}
public final void flush () {
trace.flush ();
}
}

OL-7242-02 3-9
Originator.java
Originator.java
/**
* originator.java
*
*
*/
import com.ms.com.*;
import com.cisco.jtapi.extensions.*;
public class Originator extends Actor

{
Address srcAddress;
String destAddress;
int iteration;
StopSignalstopSignal;
boolean ready = false;
int receiverState = Actor.ACTOR_OUT_OF_SERVICE;
boolean callInIdle = true;
public Originator ( Address srcAddress, String destAddress, Trace trace, int

actionDelayMillis ) {
super ( trace, srcAddress, actionDelayMillis );// observe srcAddress
this.srcAddress = srcAddress;
this.destAddress = destAddress;
this.iteration = 0;
}
protected final void metaEvent ( CallEv [] eventList ) {

for ( int i = 0; i < eventList.length; i++ ) {
try {
CallEv curEv = eventList[i];
if ( curEv instanceof CallCtlTermConnTalkingEv ) {

TerminalConnection tc =
((CallCtlTermConnTalkingEv)curEv).getTerminalConnection ();
Connection conn = tc.getConnection ();
if ( conn.getAddress ().getName ().equals ( destAddress ) ) {
delay ( "disconnecting" );
bufPrintln ( "Disconnecting Connection " + conn );

3-10 OL-7242-02
Originator.java
conn.disconnect ();
}
}
else if ( curEv instanceof CallCtlConnDisconnectedEv ) {
Connection conn = ((CallCtlConnDisconnectedEv)curEv).getConnection ();
if ( conn.getAddress ().equals ( srcAddress ) ) {
stopSignal.canStop ();
setCallProgressState ( true );
}
}
}
}
finally {
flush ();
}
}
}
protected void makecall ()

throws ResourceUnavailableException, InvalidStateException,
PrivilegeViolationException, MethodNotSupportedException,
InvalidPartyException, InvalidArgumentException {
println ( "Making call #" + ++iteration + " from " + srcAddress + " to " +
destAddress + " " + Thread.currentThread ().getName () );
Call call = srcAddress.getProvider ().createCall ();
call.connect ( srcAddress.getTerminals ()[0], srcAddress, destAddress );
setCallProgressState ( false );
println ( "Done making call" );
}
protected final void onStart () {

stopSignal = new StopSignal ();
new ActionThread ().start ();
}
protected final void fireStateChanged () {

checkReadyState ();
}
protected final void onStop () {

stopSignal.stop ();
Connection[] connections = srcAddress.getConnections ();
try {
if ( connections != null ) {

OL-7242-02 3-11
Originator.java
for (int i=0; i< connections.length; i++ ) {

connections[i].disconnect ();
}
}
}catch ( Exception e ) {
println (" Caught Exception " + e);
}
}
public int getReceiverState () {

return receiverState;
}
public void setReceiverState ( int state ) {

if ( receiverState != state ){
receiverState = state;
checkReadyState ();
}
}
public synchronized void checkReadyState () {

if ( receiverState == Actor.ACTOR_IN_SERVICE && state == Actor.ACTOR_IN_SERVICE )
{
ready = true;
}else {
ready = false;
}
notifyAll ();
}
public synchronized void setCallProgressState ( boolean isCallInIdle ) {

callInIdle = isCallInIdle;
notifyAll ();
}
public synchronized void doAction () {

if ( !ready || !callInIdle ) {
try {
wait ();
println (" Caught Exception from wait state" + e );
}
} else {
if ( actionDelayMillis != 0 ) {
println ( "Pausing " + actionDelayMillis + " milliseconds before making
call " );

3-12 OL-7242-02
Originator.java
flush ();
try {
wait ( actionDelayMillis );
}
catch ( Exception ex ) {}
}
//make call after waking up, recheck the flags before making the call
if ( ready && callInIdle ) {
try {
makecall ();
println (" Caught Exception in MakeCall " + e + " Thread =" +
Thread.currentThread ().getName ());
}
}
}
}
class ActionThread extends Thread {
ActionThread ( ) {
super ( "ActionThread");
}
public void run () {

while ( true ) {
doAction ();
}
}
}

OL-7242-02 3-13
Receiver.java
Receiver.java
/**
* Receiver.java
*
*
*/
public class Receiver extends Actor

{
Address address;
StopSignalstopSignal;
Originatororiginator;
public Receiver ( Address address, Trace trace, int actionDelayMillis, Originator

originator ) {
super ( trace, address, actionDelayMillis );
this.address = address;
this.originator = originator;
}
protected final void metaEvent ( CallEv [] eventList ) {

for ( int i = 0; i < eventList.length; i++ ) {
TerminalConnection tc = null;
try {
CallEv curEv = eventList[i];
if ( curEv instanceof CallCtlTermConnRingingEv ) {

tc = ((CallCtlTermConnRingingEv)curEv).getTerminalConnection ();
delay ( "answering" );
bufPrintln ( "Answering TerminalConnection " + tc );
tc.answer ();
stopSignal.canStop ();
}
}
bufPrintln ( "Caught exception " + e );
bufPrintln ( "tc = " + tc );
}
finally {
flush ();

3-14 OL-7242-02
Receiver.java
}
}
}
protected final void onStart () {

stopSignal = new StopSignal ();
}
protected final void onStop () {

stopSignal.stop ();
Connection[] connections = address.getConnections ();
try {
if ( connections != null ) {
for (int i=0; i< connections.length; i++ ) {
connections[i].disconnect ();
}
}
println (" Caught Exception " + e);
}
}
protected final void fireStateChanged () {

originator.setReceiverState ( state );
}
}

OL-7242-02 3-15
StopSignal.java
StopSignal.java
/**
* StopSignal.java
*
*
*/
class StopSignal {
boolean stopping = false;
boolean stopped = false;
synchronized boolean isStopped () {
return stopped;
}
synchronized boolean isStopping () {
return stopping;
}
synchronized void stop () {
if ( !stopped ) {
stopping = true;
try {
wait ();
}
catch ( InterruptedException e ) {}
}
}
synchronized void canStop () {
if ( stopping = true ) {
stopping = false;
stopped = true;
notify ();
}
}
}

3-16 OL-7242-02
Trace.java
Trace.java
/**
* Trace.java
*
*
*/
public interface Trace
{
/**
* bufPrint (str) puts str in buffer only.
*/
public void bufPrint ( String string );
/**
* print () println () bufPrint and invoke flush ();
*/
public void print ( String string );
public void print ( char character );
public void print ( int integer );
public void println ( String string );
public void println ( char character );
public void println ( int integer );
/**
* flush out the buffer.
*/
public void flush ();
}

OL-7242-02 3-17
TraceWindow.java
TraceWindow.java
/**
* TraceWindow.java
*
*
*/
import java.awt.*;
import java.awt.event.*;
public class TraceWindow extends Frame implements Trace

{
TextArea textArea;
booleantraceEnabled = true;
StringBuffer buffer = new StringBuffer ();
public TraceWindow (String name ) {

super ( name );
initWindow ();
}
public TraceWindow(){
this("");
}
private void initWindow() {

this.addWindowListener(new WindowAdapter () {
public void windowClosing(WindowEvent e){
dispose ();
}
});
textArea = new TextArea();
setSize(400,400);
add(textArea);
setEnabled(true);
this.show();
public final void bufPrint ( String str ) {

if ( traceEnabled ) {

3-18 OL-7242-02
TraceWindow.java
buffer.append ( str );
}
public final void print ( String str ) {

buffer.append ( str );
flush ();
}
}
public final void print ( char character ) {
buffer.append ( character );
flush ();
}
}
public final void print ( int integer ) {
buffer.append ( integer );
flush ();
}
}
public final void println ( String str ) {
print ( str );
print ( '\n' );
flush ();
}
}
public final void println ( char character ) {
print ( character );
print ( '\n' );
flush ();
}
}
public final void println ( int integer ) {
print ( integer );
print ( '\n' );
flush ();
}
}
public final void setTrace ( boolean traceEnabled ) {

this.traceEnabled = traceEnabled;
}

OL-7242-02 3-19
TraceWindow.java
public final void flush () {

textArea.append ( buffer.toString());
buffer = new StringBuffer ();
}
}
public final void clear () {
textArea.setText("");
}
}

3-20 OL-7242-02
Running makecall
Running makecall
To Invoke makecall on the client workstation, from the Windows NT command
line, navigate to the makecall directory where JTAPI Tools directory was
installed and execute the following command:
jview makecall <server name> <login> <password> 1000 <device 1>

<device2>
<server name> specifies the hostname or IP address of your Cisco CallManager

and <device1> <device2> are directory numbers of IP phones. Make sure that the
phones are part of the associated devices of a given user as administered in the
Cisco CallManager’s directory administration. The <logic> and <password>
apply similarly as administered in the directory. This will test that you have
installed and configured everything correctly. The application will make calls
between the two devices with an action delay of 1000 msecs until terminated.

OL-7242-02 3-21
Running makecall

3-22 OL-7242-02
A P P E N D I X A
Message Sequence Charts
This appendix contains the message sequence charts, which illustrate the message
flows for the following scenarios:
• Shared Line Support
– AddressInService/AddressOutofService Events
– Incoming Call to Shared Address
– Outgoing Call from Shared Address
– Shared Address Calling Itself
• Transfer and Direct Transfer
– DirectTransfer/Arbitrary Transfer Scenario—Page 1
– Consult Transfer Scenario
• Conference and Join
– Join/Arbitrary Conference Scenario—Page 1
– Consult Conference Scenario
• Barge and Privacy
– Barge Feature
– CBarge Feature
– Privacy
• CallSelect and UnSelect
• Dynamic CTIPort Registration Per Call
• Media Termination at Route Point

OL-7242-02 A-1
Appendix A Message Sequence Charts
Shared Line Support
• Redirect Set OriginalCalledID

• Single Step Transfer
• Modifying Calling Number
• AutoAccept for CTIPort and RoutePoint
• Forced Authorization and Customer Matter Codes Scenarios
• Super Provider Message Flow
• QSIG Path Replacement Use Cases
• Device State Server Message Flow
Shared Line Support

The following diagrams illustrate the message flows for Shared Line support.

A-2 OL-7242-02
Shared Line Support
AddressInService/AddressOutofService Events
Scenario: Shared Address 2005 at terminal SEP003094C25AFF(T1) and Terminal SEP003094C2A0B0(T2)
Application
Events delivered at JTAPI CTI
AddressObserver
Application adds AddressObserver at 2005
JTAPI opens Line 2005 at T1 with CTI

LineInServiceEvent for 2005 at T!
CiscoAddressInService(2005 at T1)
JTAPI opens Line 2005 at T2 with CTI
Terminal T1 unregisters
LineOutOfService for 2005 at T1
CiscoAddressOutOfService(2005 at T1)
Note: At this point Address 2005 is still InService at T2,
so Address State for 2005 would be still InService
Terminal T2 unregisters
LineOutOfService for 2005 at T2
CiscoAddressOutOfService(2005 at T2)
Note: At this point both the SharedLines for Address
2005 has gone OutOfServic, so Address State for
2005 would be OutOfService
Terminal T1 re-registers
Terminal T2 re-registers
LineInServiceEvent for 2005 at T2
Application removes AddressObserver at 2005
AddressObservationEnded event
JTAPI closes Line 2005 at T1 with CTI
JTAPI closes Line 2005 at T2 with CTI
At this point Address state will be OutOfService

92473

OL-7242-02 A-3
Shared Line Support
Incoming Call to Shared Address
Scenario: 2005 is Shared line appearing on terminal SEP003094C25AFF (T1) and Terminal SEP003094C2A0B0(T2).
2000 makes calls to 2005, 2005-T2 answers the call
Application
AddressCallObserver
NewCallEvent for 2000

NEW META EVENT____META_CALL_STARTING
CallActiveEv for callID=101
ConnCreatedEv for 2000
ConnConnectedEv for 2000
CallCtlConnInitiatedEv for 2000
TermConnCreatedEv for SEP0002FD3BA460
TermConnActiveEv for SEP0002FD3BA460
CallCtlTermConnTalkingEv for SEP0002FD3BA460
CallStateDialing
NEW META EVENT____META_CALL_PROGRESS
CallCtlConnDialingEv for 2000
CallStateProceeding
CallCtlConnEstablishedEv for 2000
NewCallEvent for T1
NewCallEvent for T2
NEW META EVENT____META_CALL_ADDITIONAL_PARTY CallStateOfferingT1
ConnCreatedEv for 2005 CallStateOfferingT2
ConnInProgressEv for 2005
CallCtlConnOfferedEv for 2005
NEW META EVENT____META_CALL_PROGRESS CallStateAccepted-T2

ConnAlertingEv for 2005
CallCtlConnAlertingEv for 2005
TermConnCreatedEv for SEP003094C2A0B0
TermConnRingingEv for SEP003094C2A0B0
CallCtlTermConnRingingEvlmp for SEP003094C2A0B0

TermConnCreatedEv for SEP003094C25AFF
TermConnRingingEv for SEP003094C25AFF
CallCtlTermConnRingingEvlmp for SEP003094C25AFF
SEP003094C2A0B0 answers the call
NEW META EVENT____META_CALL_PROGRESS CallStateConnected-T1

TermConnActiveEv for SEP003094C2A0B0
CallCtlTermConnTalkingEv for SEP003094C2A0B0
NEW META EVENT____META_CALL_PROGRESS CallStateConnected-RIU-T2

TermConnPassiveEv for SEP003094C25AFF
92474
CallCtlTermConnBridgedEv for SEP003094C25AFF

A-4 OL-7242-02
Shared Line Support
Outgoing Call from Shared Address
Scenario: 2005 is Shared line appearing on terminal SEP003094C25AFF and Terminal SEP003094C2A0B0.
2005 makes calls to 2000
Application
AddressCallObserver
NewCallEvent for T1
NEW META EVENT____META_CALL_STARTING NewCallEvent for T2
CallActiveEv for callID=101
ConnCreatedEv for 2005
ConnConnectedEv for 2005
CallCtlConnInitiatedEv for 2005
TermConnCreatedEv for SEP0003094C2A0B0
TermConnActiveEv for SEP0003094C2A0B0
CallCtlTermConnTalkingEv for SEP0003094C2A0B0
CallStateDialing
CallCtlConnDialingEv for 2005
NEW META EVENT____META_CALL_ADDITIONAL_PARTY

TermConnCreatedEv for SEP003094C25AFF
TermConnInPassiveEv for SEP003094C25AFF
CallCtlTermConnBridgedEv for SEP003094C25AFF
NEW META EVENT____META_CALL_PROGRESS CallStateProceeding

CallCtlConnEstablishedEv for 2005
NEW META EVENT____META_CALL_ADDITIONAL_PARTY NewCallEvent for 2000

ConnCreatedEv for 2000 CallStateOffering
ConnInProgressEv for 2000
CallCtlConnOfferedEv for 2000
CallStateAccepted
ConnAlertingEv for 2000
CallCtlConnAlertingEv for 2000
TermConnCreatedEv for SEP002FD3BA460
TermConnRingingEv for SEP002FD3BA460
CallCtlTermConnRingingEvlmp for SEP002FD3BA460
CallStateConnected
TermConnActiveEv for SEP002FD3BA460
CallCtlTermConnTalkingEv for SEP002FD3BA460
92475

OL-7242-02 A-5
Shared Line Support
Shared Address Calling Itself
Scenario: 2005 at terminal SEP003094C25AFF(T1) call 2005 at Terminal SEP003094C2A0B0(T2) answers the call
Application
AddressCallObserver
2005-T1 calls 2005-T2
12/1 CallActiveEv for callID=102

12/1 ConnCreatedEv for 2005 NewCallEvent for T1
12/1 ConnConnectedEv for 2005
21/1 CallCtlConnInitiatedEv for 2005
12/1 TermConnCreatedEv for SEP003094C25AFF

12/1 TermConnActiveEv for SEP003094C25AFF
12/1 CallCtlTermConnTalkingEv for SEP003094C25AFF
12/1 TermConnCreatedEv for SEP003094C2A0B0 NewCallEvent for T2

12/1 TermConnPassiveEv for SEP003094C2A0B0
12/1 CallCtlTermConnBridgedEv for SEP003094C2A0B0
12/1 CallCtlConnDialingEv for 2005

CallStateDialing
12/1 CallCtlConnEstablishedEv for 2005 CallStateProceeding
12/1 TermConnRingingEv for SEP003094C2A0B0 CallStateOffering

12/1 CallCtTermConnRingingEvlmp for SEP003094C2A0B0 CallStateAccepted
12/1 TermConnActiveEv for SEP003094C2A0B0 CallStateConnected

12/1 CallCtTermConnTalkingEv for SEP003094C2A0B0
Now 2005 drops the Call
12/1 TermConnDroppedEv for SEP003094C25AFF CallStateIdle for T1

12/1 CallCtlTermConnDroppedEv for SEP003094C25AFF
12/1 TermConnDroppedEv for SEP003094C2A0B0 CallStateIdle for T2

12/1 CallCtlTermConnDroppedEv for SEP003094C2A0B0
12/1 ConnDisconnectedEv for 2005

12/1 CallCtlConnDisconnectedEv for 2005
92476
12/1 CallInvalidEv for callID-102

A-6 OL-7242-02
Transfer and Direct Transfer

The following diagrams illustrate the message flows for Transfer and Direct
Transfer.
DirectTransfer/Arbitrary Transfer Scenario—Page 1
Scenario: 2000 Calls 2001, 2001 calls 2002, 2001 does arbitrary transfer PAGE-1
Application
AddressCallObserver

2/1 CallActiveEv for callID=101 NewCallEvent for 2000
2/1 ConnCreatedEv for 2000 Cause
2/1 ConnConnectedEv for 2000 Cause
2/1 CallCtlConnInitiatedEv for 2000 Cause
2/1 TermConnCreatedEv for SEP0002FD3BA460
2/1 TermConnActiveEv for SEP0002FD3BA460
2/1 CallCtlTermConnTalkingEv for SEP0002FD3BA460
NEW META EVENT____META_CALL_PROGRESS CallStateDialing
2/1 CallCtlConnEstablishedEv for 2000
2/1 ConnCreatedEv for 2001 CallStateOffering2001
2/1 ConnInProgressEv for 2001
2/1 CallCtlConnOfferedEv for 2001
NEW META EVENT____META_CALL_PROGRESS CallStateAccepted-2001
2/1 ConnAlertingEv for 2001
2/1 CallCtlConnAlertingEv for 2001
2/1 TermConnCreatedEv for SEP003094C2A0B0
2/1 TermConnRingingEv for SEP003094C2A0B0
2/1 CallCtlTermConnRingingEvlmp for SEP003094C2A0B0
NEW META EVENT____META_CALL_PROGRESS SEP003094C2A0B0 answers the call
2/1 ConnConnectedEv for 2001 CallStateConnected-2001
2/1 TermConnActiveEv for SEP003094C2A0B0
2/1 CallCtlTermConnTalkingEv for SEP003094C2A0B0
SEP003094C2A0B0 answers the call

CallStateHold 2001
92477
2/1 CallCtlTermConnHeldEv for SEP003094C2A0B0

OL-7242-02 A-7
Direct Transfer/Arbitrary Transfer—Page 2

Scenario: 2000 Calls 2001, 2001 calls 2002, 2001 does arbitrary transfer PAGE-2
Application
AddressCallObserver

3/1 ConnCreatedEv for 2001
3/1 CallCtlConnDialingEv for 2001 CalStateProceeding
NEW META EVENT____META_CALL_PROGRESS NewCallEvent for 2000
3/1 TermConnCreatedEv for SEP003094C2573E
3/1 TermConnRingingEv for SEP003094C2573E
3/1 CallCtlTermConnRingingEvlmp for SEP003094C2573E 2002 answers the call
NEW META EVENT____META_CALL_PROGRESS CallStateConnected-2002
3/1 TermConnActiveEv for SEP003094C2573E
3/1 CallCtlTermConnTalkingEv for SEP003094C2573E
2001 Completes the Transfer
NEW META EVENT____META_CALL_UNKNOWN TransferStartec
2/1 CiscoTransferStartEv for callID=1073754118
NEW META EVENT____META_CALL_TRANSFERRING GCIDChangedEvent
NEW META EVENT____META_CALL_TRANSFERRING CallStateIdle for 2001
3/1 TermConnDroppedEv for SEP003094C2A0B0
NEW META EVENT____META_UNKNOWN
3/1 CallObservationEndedEv for callID=103
NEW META EVENT____META_CALL_TRANSFERRING CallStateIdle for 2001
TransferEndec
2/1 CiscoTransferEndEv for callID=1073754117
92478


A-8 OL-7242-02
Conference and Join
Consult Transfer Scenario

The message flow for Consult Transfer acts the same as the flow for Arbitrary
Transfer.
Conference and Join

The following diagrams illustrate the message flows for Conference and Join.

OL-7242-02 A-9
Conference and Join
Join/Arbitrary Conference Scenario—Page 1
Scenario: 2000 Calls 2001, 2001 calls 2002, 2001 does arbitrary Conference PAGE-1
Application
AddressCallObserver
2000 Calls 2001

2/1 ConnCreatedEv for 2000 Cause
2/1 ConnConnectedEv for 2000 Cause
2/1 CallCtlConnInitiatedEv for 2000 Cause
NEW META EVENT____META_CALL_PROGRESS CallStateAccepted-2001
2/1 TermConnRingingEv for SEP003094C2A0B0
2/1 CallCtlTermConnRingingEvlmp for SEP003094C2A0B0
NEW META EVENT____META_CALL_PROGRESS SEP003094C2A0B0 answers the call
2/1 ConnConnectedEv for 2001 CallStateConnected-2001
2001 Calls 2002

CallStateHold 2001
92479
2/1 CallCtlTermConnHeldEv for SEP003094C2A0B0

A-10 OL-7242-02
Conference and Join
Join/Arbitrary Conference Scenario—Page 2

Scenario: 2000 Calls 2001, 2001 calls 2002, 2001 does arbitrary Conference PAGE-2
Application
JTAPI CTI
Events delivered at
AddressCallObserver
2000 Calls 2001
3/1 CallCtlConnDialingEv for 2001 CalStateProceeding
3/1 CallCtlTermConnRingingEvlmp for SEP003094C2573E 2002 answers the call
NEW META EVENT____META_CALL_PROGRESS CallStateConnected-2002
2001 Completes the Conference/Application completes arbitrary conference
NEW META EVENT____META_UNKNOWN TransferStartec
2/1 CiscoConferenceStartedEv for callID=1073754118
NEW META EVENT____META_CALL_MERGING CallStateConnected for 2001

NEW META EVENT____META_CALL_MERGING GCIDChangedEvent

NEW META EVENT____META_CALL_MERGING CallStateIdle for 2001

NEW META EVENT____META_UNKNOWN ConferenceEndec

2/1 CiscoConferenceEndedEv for callID=1073754117
92480


OL-7242-02 A-11
Barge and Privacy
Consult Conference Scenario

The message flow for Consult Conference acts the same as the flow for Arbitrary
Conference.
Barge and Privacy

The following diagrams illustrate the message flows for Barge and Privacy.

A-12 OL-7242-02
Barge and Privacy
Barge Feature
2000 makes calls to 2005, 2005-T1 answers the Call. Now T2 Barges into
Application Events delivered
JTAPI CTI
at AddressCallObserver
13/1 CallActiveEv for callID=101 NewCallEvent for T2
13/1 ConnCreatedEv for 2000 CallStateOfferingT1
13/1 CallCtlConnEstablishedEv for 2000 CallStateOfferingT2
13/1 TermConnRingingEv for SEP003094C25AFF
13/1 CallCtlTermConnRingingEv for SEP003094C25AFF CallStateAccepted-T2
13/1 TermConnCreatedEv for SEO003094C2A0B0
13/1 TermConnRingingEv for SEO003094C2A0B0 SEP003094C25AFF answers the call
13/1 CallCtlTermConnRingingEv for SEO003094C2A0B0
13/1 CallCtlConnEstablishedEv for 2005 CallStateConnected-RIU-T2
13/1 CallCtlTermConnBridgeEv for SEP003094C2A0B0
T2 Barges into the Call. A new call is temporarily created due to Barge
NEW META EVENT____META_CALL_STARTING NewCallEvent for 2001
14/1 CallCtlConnDialingEv for 2005 NewCallEvent for 2001
14/1 TermConnPassiveEv for SEP00394C25AFF
14/1 CallCtlTermConnBridgeEv for SEP00394C25AFF
14/1 ConnCreatedEv for Unknown
14/1 ConnCreatedEv for Unknown GlobalCallIDChangedEv-T1-RIU
NEW META EVENT____META_CALL_REMOVING_PARTY GlobalCallIDChangedEv-T2
14/1 TermConnDroppedEv for SEP003094C25AFF
13/1 TermConnActiveEv for SEP003094C2A0B0 TerminalConnection of T2 goes to
13/1 CallCtlTermConnTalkingEv for SEP003094C2A0B0 Active/Talking state after Barge
NEW META EVENT____META_CALL_ENDING
14/1 CallInvalidEv for callID=102
NEW META EVENT____META_CALL_UNKNOWN T2 Drops Out of the Barged Call
14/1 CallObservationEndedEv for callID=103 CallStateIdle-T2
13/1 TermConnPassiveEv for SEP003094C2A0B0 CallStateIdle-T1-RIU
92481
13/1 CallCtlTermConnBridgedEv for SEP003094C2A0B0 TerminalConnection T2 goes back to Passive/Bridged

OL-7242-02 A-13
Barge and Privacy
CBarge Feature
2000 makes calls to 2005, 2005-T1 answers the Call. Now T2 CBages into
Application Events delivered
JTAPI CTI
at AddressCallObserver
13/1 CallActiveEv for callID=101 NewCallEvent for T2
13/1 ConnCreatedEv for 2000 CallStateOfferingT1
13/1 CallCtlConnEstablishedEv for 2000 CallStateOfferingT2
13/1 TermConnRingingEv for SEP003094C25AFF
13/1 CallCtlTermConnRingingEv for SEP003094C25AFF CallStateAccepted-T2
13/1 TermConnCreatedEv for SEO003094C2A0B0
13/1 TermConnRingingEv for SEO003094C2A0B0 SEP003094C25AFF answers the call
13/1 CallCtlTermConnRingingEv for SEO003094C2A0B0
13/1 CallCtlConnEstablishedEv for 2005 CallStateConnected-RIU-T2
13/1 CallCtlTermConnBridgeEv for SEP003094C2A0B0
T2 Barges into the Call. A new call is temporarily created due to CBarge
NEW META EVENT____META_CALL_STARTING NewCallEvent for T1-RIU
14/1 CallActiveEv for callID=101 NewCAllEvent for T2
NEW META EVENT____META_CALL_PROGRESS CallStateDialingT1-RIU
14/1 CallCtlConnDialingEv for 2005 CallStateDialingT2
14/1 TermConnPassiveEv for SEP00394C25AFF
14/1 CallCtlTermConnBridgeEv for SEP00394C25AFF
NEW META EVENT____META_CALL_PROGRESS CallStateProceedingT1-RIU
14/1 CallCtlConnEstablishedEv for 2003 CallStateProceedingT1
14/1 ConnCreatedEv for Unknown
14/1 ConnCreatedEv for Unknown GlobalCallIDChangedEv-T1-RIU
NEW META EVENT____META_CALL_REMOVING_PARTY GlobalCallIDChangedEv-T2
14/1 TermConnDroppedEv for SEP003094C25AFF
13/1 TermConnActiveEv for SEP003094C2A0B0 TerminalConnection of T2 goes to
13/1 CallCtlTermConnTalkingEv for SEP003094C2A0B0 Active/Talking state after CBarge
NEW META EVENT____META_CALL_ENDING
14/1 CallInvalidEv for callID=102
NEW META EVENT____META_CALL_UNKNOWN T2 Drops Out of the CBarged Call
14/1 CallObservationEndedEv for callID=103 CallStateIdle-T2
13/1 TermConnPassiveEv for SEP003094C2A0B0 CallStateIdle-T1-RIU
2482
13/1 CallCtlTermConnBridgedEv for SEP003094C2A0B0 TerminalConnection T2 goes back to Passive/Bridged

A-14 OL-7242-02
CallSelect and UnSelect
Privacy
A,A' are SharedLine, A calls B. Now A presses Privacy key to enable privacy
Application CallObserver CallManager/ ICCNLineA/A' CTI

CallImpl
CallPrivacyChangedEvent-A'
CallEvents
CiscoTermConnPrivChgEv
CallCtlTermConninUse
Now A pressed Privacy key to disable privacy on the cal
CallEvent
CiscoTermConnPrivChgEv
CallCtlTermConnBridged
92483
CallSelect and UnSelect
The following diagram illustrates the message flows for CallSelect and UnSelect.

OL-7242-02 A-15
CallSelect and UnSelect Scenario
A,A' are SharedLine, A calls B. Now A presses Select Softkey to Select the call
Application CallObserver CallManager/ ICCNLineA/A' CTI

CallImpl
CallSelectChangedEvent-A'
CallEvents
CallCtlTermConninUse
Now A pressed Select Softkey again to UnSelect the call
CallEvent
CallCtlTermConnBridged
92484
The following diagram illustrates the message flows for Dynamic CTIPort
Registration per call.

A-16 OL-7242-02
Dynamic Registration for CTIPort

The following diagram illustrates the message flows for Media Termination at
Route Point.

OL-7242-02 A-17
Media Termination at Route Point Scenario

A-18 OL-7242-02
Redirect Set OriginalCalledID

The following scenario illustrates the message flows for Redirect Set
OriginalCalledID.
Scenario One
A, B, and C appear in an applications controlled list.
D is does not appear in the control list.
A calls B.

OL-7242-02 A-19
B redirects call to D with C as preferredOriginalCalledParty.

Application will see following events for parties A and B

META_CALL_ADDING_PARTY Call ConnCreatedEv for D CallingParty=A
1 ConnConnectedEv for D CalledParty = B
CallCtlConnEstablishedEv for D LastRedirectedParty=
C
CurrentCalledParty=D
META_CALL_REMOVE_PARTY Call ConnDisconnectedEv for B CallingParty=A

1 CallCtlConnDisconnectedEv for CalledParty = B
B LastRedirectedParty=
TermConnDroppedEv for B C
CallCtlTermConnDroppedEv for CurrentCalledParty=D
B
CallObservationEndedEv for B
Note The specified event group may not be in the same order and might change
depending on where parties are present in the cluster, on the load, and other
conditions.
Scenario Two
A, B, and C do not appear in the Control list, and
D is in the application control list.
A calls B.
B redirects the call to D with C as preferredOriginalCalledParty.
The application will see following events for party D.

A-20 OL-7242-02

META_CALL_STARTING Call CallActiveEv CallingParty=A
1 ConnCreatedEv for D CalledParty = D
ConnInProgressEv for D LastRedirectedParty=
CallCtlConnOfferedEv for D C
ConnCreatedEv for A CurrentCalledParty=D
CallCtlConnInitiatedEv for A
META_CALL_PROGRESS Call ConnAlertingEv for D CallingParty=A
1 CallCtlConnAlertingEv for D CalledParty = D
TermConnCreatedEv for D LastRedirectedParty=
CallCtlTermConnRingingEv for C
D CurrentCalledParty=D
ConnConnectedEv for A
CallCtlConnEstablishedEv for A
META_CALL_PROGRESS Call ConnConnectedEv for D CallingParty=A
CallCtlConnEstablishedEv for D CalledParty = D
TermConnActiveEv for D LastRedirectedParty=
CallCtlTermConnTalkingEv for C
D CurrentCalledParty=D

OL-7242-02 A-21

Adresses A, B, and C appear in the control list, and the call between A and B is
then gets transferred to C with B as the transfer controller. Applications will see
the following events:
Address A (5001) Address B (5002) Address C (5003)

Action Terminal CTIP1 Terminal CTIP2 Terminal CTIP3
Call.transfer(string) ConnCreatedEv 5003 NEW META CallActiveEv Cause:
Cause: EVENT_________META CAUSE_NEW_CALL
CAUSE_NORMAL _CALL_REMOVING_PA
ConnCreatedEv 5003
RTY
ConnInProgressEv Cause:
5003 Cause: CAUSE_NORMAL
CAUSE_NORMAL
TermConnDroppedEv ConnInProgressEv 5003
CallCtlConnOfferedE CTIP2 Cause: Cause:
v 5003 Cause: CAUSE_NORMAL CAUSE_NORMAL
CAUSE_NORMAL CallCtlConnOfferedEv
CallControlCause: 5003 Cause:
CallCtlTermConnDroppe
CAUSE_TRANSFER CAUSE_NORMAL
dEv CTIP2 Cause:
CallControlCause:
ConnAlertingEv 5003 CAUSE_NORMAL
CAUSE_TRANSFER
Cause: CallControlCause:
CAUSE_NORMAL CAUSE_TRANSFER ConnCreatedEv
5001Cause:
CallCtlConnAlerting
CAUSE_NORMAL
Ev 5003 Cause: ConnDisconnectedEv
CAUSE_NORMAL 5002 Cause: ConnConnectedEv 5001
CallControlCause: CAUSE_NORMAL Cause:
CAUSE_TRANSFER CAUSE_NORMAL
CallCtlConnEstablishedE
CallCtlConnDisconnected v 5001Cause:
Ev 5002 Cause: CAUSE_NORMAL
CAUSE_NORMAL CallControlCause:
CallControlCause: CAUSE_NORMAL
CAUSE_TRANSFER

A-22 OL-7242-02

Call.transfer(string) CiscoRTPInputStarte ConnAlertingEv 5003
dEv Cause: Cause:
(continued) NEW META
CAUSE_NORMAL CAUSE_NORMALCallC
EVENT_________META
tlConnAlertingEv 5003
CiscoRTPOutputStart _UNKNOWN
Cause:
edEv Cause:
CAUSE_NORMAL
CAUSE_NORMAL
CallObservationEndedEv CallControlCause:
ConnConnectedEv CAUSE_NORMAL
Cause:
5003
CAUSE_NORMAL TermConnCreatedEv
CAUSE_NORMAL
CTIP3
CallCtlConnEstablish
TermConnRingingEv
edEv 5003 Cause:
CTIP3Cause:
CAUSE_NORMAL
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL CallCtlTermConnRinging
EvImpl CTIP3 Cause:
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL
Cause:
CAUSE_NORMAL
CiscoRTPOutputStartedE
v Cause:
CAUSE_NORMAL
ConnConnectedEv 2004
Cause:
CAUSE_NORMAL
CallCtlConnEstablishedE
v 5003Cause:
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL

OL-7242-02 A-23

Call.transfer(string) TermConnActiveEv
CTIP3 Cause:
(continued)
CAUSE_NORMAL
CallCtlTermConnTalking
Ev CTIP3 Cause:
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL
Cause:
CAUSE_NORMAL
CiscoRTPOutputStopped
Ev Cause:
CAUSE_NORMAL
ConnDisconnectedEv
5001 Cause:
CAUSE_NORMAL
CallCtlConnDisconnected
Ev 5001 Cause:
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL
TermConnDroppedEv
CTIP3 Cause:
CAUSE_NORMAL
CallCtlTermConnDroppe
dEv CTIP3 Cause:
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL

A-24 OL-7242-02

Call.transfer(string) ConnDisconnectedEv
5003 Cause:
(continued)
CAUSE_NORMAL
CallCtlConnDisconnected
Ev 5003 Cause:
CAUSE_NORMAL
CallControlCause:
CAUSE_NORMAL
META_UNKNOWN
CallInvalidEv [#32]
Cause:
CAUSE_NORMAL

The following scenario illustrates the message flows for Modifying Calling
Number.
Scenario One
The application controls the device Route Point (RP) and registers RP .
A and B are PNO and appear within the Cisco CallManager cluster.

OL-7242-02 A-25
A calls RP.
Call arrives at RP
Action Event Fields

Call Arrives at RP RouteEvent State = ROUTE
getCurrentRouteAddress () =
RP
getCallingAddress () = A
getCallingTerminal () = SEPA
(Terminal associated with A)
Application invokes RouteUsedEvent State = ROUTE_USED

selectRoute( routeselected[], (Terminal associated with A)
callingsearchspace, getRouteUsed () = C
modifiyingcallingnumber[] )
where
routeSelected[] = C
callingSearchSpace =
CiscoRouteSession.DEFAULT_
SEARCH_SPACE
Application invokes RouteEndEvent State = ROUTE_END
getRouteAddress () = RP
endRoute (ERROR_NONE)
Scenario Two
The application is controls A and B.
A calls RP, which selectsRoute call to B with modified calling number as M.

A-26 OL-7242-02
Action Event Fields

A calls RP, which is not in NEW META getCallingAddress() = A
controlled list. EVENT_________META_CALL_ getCalledAddress() =
STARTING getLastRedirectedAddress ()=
CallActiveEv Cause: getCurrentCallingAddress ()= A
CAUSE_NEW_CALL getCurrentCalledAddress()=
ConnCreatedEv A Cause: getModifiedCallingAddress()=A
CAUSE_NORMAL getModifiedCalledAddress() =
ConnConnectedEv A Cause:
CAUSE_NORMAL
CallCtlConnInitiatedEv Cause:
CAUSE_NORMAL CallControlCause: getCallingAddress() = A
CAUSE_NORMAL getCalledAddress() =
TermConnCreatedEv SEPA Cause: getLastRedirectedAddress ()=
Other: 0 getCurrentCallingAddress ()= A
TermConnActiveEv SEPA Cause: getCurrentCalledAddress()=
CAUSE_NORMAL getModifiedCallingAddress()=A
CallCtlTermConnTalkingEv SEPA getModifiedCalledAddress() =
Cause: CAUSE_NORMAL
getCallingAddress() = A
getCalledAddress() = B
NEW META getLastRedirectedAddress ()=
EVENT_________META_CALL_ getCurrentCallingAddress ()= A
PROGRESS getCurrentCalledAddress()= B
CallCtlConnDialingEv A getModifiedCallingAddress()=A
getModifiedCalledAddress() =B
NEW META
EVENT_________META_CALL_
PROGRESS
CallCtlConnEstablishedEv A
ConnCreatedEv RP
ConnInProgressEv RP
CallCtlConnOfferedEv RP

OL-7242-02 A-27
Action Event Fields

Another application NEW META getCallingAddress() = A
controls the RP EVENT_________META_CALL_ getCalledAddress() = B
selectRoute to B with ADDITIONAL_PARTY getLastRedirectedAddress ()=
modifying calling number ConnCreatedEv B RP
as M. ConnInProgressEv B getCurrentCallingAddress ()= A
CallCtlConnOfferedEv B getCurrentCalledAddress()= B
ConnDisconnectedEv RP getModifiedCallingAddress()=
CallCtlConnDisconnectedEv RP M
NEW META getCallingAddress() = A

EVENT_________META_CALL_ getCalledAddress() = B
PROGRESS getLastRedirectedAddress ()=
ConnAlertingEv B RP
CallCtlConnAlertingEv B
TermConnCreatedEv B
TermConnRingingEv B getCurrentCallingAddress ()= A
CallCtlTermConnRingingEv B getCurrentCalledAddress()= B
getModifiedCallingAddress()=
M
B answers the call. ConnConnectedEv B getCallingAddress() = A
CallCtlConnEstablishedEv B getCalledAddress() = B
TermConnActiveEv B getLastRedirectedAddress ()=
CallCtlTermConnTalkingEv B RP
getCurrentCallingAddress ()= A
getCurrentCalledAddress()= B
getModifiedCallingAddress()=
M

A-28 OL-7242-02
Forced Authorization and Customer Matter Codes Scenarios
AutoAccept for CTIPort and RoutePoint
Forced Authorization and Customer Matter Codes

Scenarios
Scenario One
The application controls A and B; B requires a forced authorization code (FAC)
to extend the call.

OL-7242-02 A-29
Action Event
A calls B by using NEW META EVENT_________META_CALL_STARTING
call.Connect(), or A places a CallActiveEv Cause: CAUSE_NEW_CALL
consult call to B by using ConnCreatedEv A Cause: CAUSE_NORMAL
Call.Consult(). ConnConnectedEv A Cause: CAUSE_NORMAL
CallCtlConnInitiatedEv Cause: CAUSE_NORMAL
TermConnCreatedEv SEPA Cause: Other: 0
TermConnActiveEv SEPA Cause: CAUSE_NORMAL
CallCtlTermConnTalkingEv SEPA Cause: CAUSE_NORMAL
NEW META EVENT_________META_CALL_PROGRESS
CallCtlConnDialingEv A
CiscoToneChangedEv
ToneType = CiscoTone.ZIPZIP
cause = CiscoCallEv.CAUSE_FAC_CMC
getWhichCodRequired =
CiscoToneChangedEv. FAC_REQUIRED
Application enters additional NEW META
digits by using EVENT_________META_CALL_ADDITIONAL_PARTY
CiscoConnection.addToAddress ConnCreatedEv B
. ConnInProgressEv B
CallCtlConnOfferedEv B
ConnAlertingEv B
TermConnCreatedEv B
TermConnRingingEv B
CallCtlTermConnRingingEv B
ConnConnectedEv B
CallCtlConnEstablishedEv B
B answers the call. TermConnActiveEv B

A-30 OL-7242-02
Scenario Two
The application controls A and B; B requires both an FAC and a CMC (client
matter code) to extend the call.
Action Event
CallCtlTermConnTalkingEv SEPA Cause:
CAUSE_NORMAL CallControlCause: CAUSE_NORMAL
CiscoToneChangedEv
CiscoToneChangedEv. FAC_CMC_REQUIRED
Application enters FAC code NEW META EVENT_________META_CALL_PROGRESS
digits with # termination by CiscoToneChangedEv
using ToneType = CiscoTone.ZIPZIP
CiscoConnection.addToAddress cause = CiscoCallEv.CAUSE_FAC_CMC
within the T302 timer. getWhichCodRequired =
CiscoToneChangedEv. CMC_REQUIRED

OL-7242-02 A-31
Action Event
Application enters CMC code NEW META
digits with # terminated by using EVENT_________META_CALL_ADDITIONAL_PARTY
CiscoConnection.addToAddress ConnCreatedEv B
within T302 timer. ConnInProgressEv B
ConnAlertingEv B
TermConnCreatedEv B
TermConnRingingEv B
CallCtlTermConnRingingEv B
B answers the call. ConnConnectedEv B
TermConnActiveEv B
CallCtlTermConnTalkingEv B
Scenario Three
The application controls A and B;
B requires a CMC, and the application enters an invalid code.

A-32 OL-7242-02
Action Event
CallCtlTermConnTalkingEv SEPA Cause:
CAUSE_NORMAL
CiscoToneChangedEv
CiscoToneChangedEv. CMC_REQUIRED
The application enters the NEW META EVENT_________META_CALL_PROGRESS
incorrect CMC digits (# ConnFailedEv A
terminated) by using CallCtlConnFailedEv A getCiscoCause () =
CiscoConnection.addToAddress CiscoCallEv.FAC_CMC
within the T302 timer limit.
The application receives reorder
NEW META EVENT_________META_CALL_ENDING
tone.
TermConnDroppedEv
CallCtlTermConnDropped
ConnDisconnectedEv
CallCtlConnDisconnectedEv
CallInvalidEv
CallObservationEndedEv

OL-7242-02 A-33
Scenario Four
The application controls both A and B; A calls B; B redirects the call to C, which
needs both an FAC and a CMC.

A-34 OL-7242-02
Action Event
CallCtlTermConnTalkingEv SEPA Cause: CAUSE_NORMAL
NEW
METAEVENT_________META_CALL_ADDITIONAL_PARTY
ConnCreatedEv B
ConnInProgressEv B
ConnAlertingEv B
TermConnCreatedEv SEPB
TermConnRingingEv SEPB
CallCtlTermConnRingingEv SEPB
ConnConnectedEv B
TermConnActiveEv SEPB
CallCtlTermConnTalkingEv SEPB

OL-7242-02 A-35
Action Event
B issues a redirect request to C NEW META
and passes an FAC and a CMC EVENT_________META_CALL_REMOVING_PARTY
code. TermConnDroppedEv SEPB
CallCtlTermConnDroppedEv SEPB Cause: CAUSE_NORMAL
CallControlCause: CAUSE_REDIRECTED CiscoCause:
ConnDisconnectedEv B Cause: CAUSE_NORMAL CiscoCause:
CallCtlConnDisconnectedEv B Cause: CAUSE_NORMAL
ConnCreatedEv C Cause: CAUSE_NORMAL CiscoCause:
ConnInProgressEv C Cause: CAUSE_NORMAL CiscoCause:
CallCtlConnOfferedEv C Cause: CAUSE_NORMAL
ConnAlertingEv A Cause: CAUSE_NORMAL CiscoCause:
CallCtlConnAlertingEv C Cause: CAUSE_NORMAL
CallControlCause: CAUSE_NORMAL CiscoCause:
ConnConnectedEv C Cause: CAUSE_NORMAL CiscoCause:
CAUSE_NOERROR
CallCtlConnEstablishedEv C Cause: CAUSE_NORMAL
CallControlCause: CAUSE_NORMAL CiscoCause:
CAUSE_NOERROR

A-36 OL-7242-02
Scenario Five
Application controls the device Route Point (RP) and registers the RP.
A and B are PNO and within the Cisco CallManager cluster.
Action Event Fields

Call arrives at RP RouteEvent State = ROUTE
getCurrentRouteAddress () = RP
(Terminal associated with A)
Application invokes RouteUsedEvent State = ROUTE_USED
selectRoute( routeselected[],
getCallingTerminal () =
callingsearchspace,
SEPA (Terminal associated with A)
modifiyingcallingnumber[],
getRouteUsed () = B
preferredOriginalCdNumber[],
preferredOriginalCdOption[],
facCode[],
cmcCode[] ) where
routeSelected[] = B
callingSearchSpace =
CiscoRouteSession.DEFAULT_
SEARCH_SPACE
modifyingCgNumber = null,
preferredOriginalCdNumber =
null,
preferredOriginalCdOption =
CiscoRouteSession.DONOT_R
ESET_ORIGINALCALLED,
facCode[] = "facCode for B"
cmcCode[] = "cmcCode for B"
Application invokes RouteEndEvent State = ROUTE_END
getRouteAddress () = RP
endRoute ( ERROR_NONE )

OL-7242-02 A-37
Super Provider Message Flow
Super Provider Message Flow

The application tries to create Terminal for CTIPort1 that has Addresses 2000 and
2001. The following events get sent to the application.
No. Action Event

1 Application invokes JTAPI would returm CiscoTerminal object and the
CiscoProvider.CreateTerminal following events get sent:
(CTIPort1) CiscoTermCreatedEv CTIPort1<------------------
where
CiscoAddrCreated 2000<---------------------------
CiscoProviderCapabilities.
canObserveAnyTerminal() returns CiscoAddrCreated 2001<----------------------------
TRUE.
2 If the application already has a terminal JTAPI would returm CiscoTerminal object and the
where the 2001 address already exists, following events get sent
that is, 2001 is a SharedLine Address.
CiscoTermCreatedEv CTIPort1<-------------------
Now, the application invokes CiscoAddrCreated 2000<---------------------------
CiscoProvider.
CreateTerminal(CTIPort1) CiscoAddrAddedToTerminalEv 2001<-----------
3 Application invokes JTAPI would throw an exception:
InvalidArgumentException
CiscoProvider.
CreateTerminal(CTIPortX)
where CTIPortX does not exist in
Cisco CallManager cluster.
4 Application invokes JTAPI would throw an exception:
CiscoProvider.
CreateTerminal(CTIPort1)
where
CiscoProviderCapabilities.
canObserveAnyTerminal() returns
FALSE.

A-38 OL-7242-02
QSIG Path Replacement Use Cases

The following table shows the JTAPI events that are delivered to applications
when calls between PBXs that are connected by Q.Signaling (QSIG) trunks are
transferred and forwarded. This table also shows the events that are delivered to
applications when the real-time path (RTP) is optimized by the QSIG Path
Replacement feature.
Calls going out on a QSIG trunk may not have a connection for the far end if any
translation pattern is changing the pattern. In other words, when the application
sees two calls in the trombone case, B may not serve as the common connection
on the calls.
No. Action Event

1 A registered with CM1, B is registered with These events get delivered to applications:
CM2, and C registered with CM3.
CallCtrlConnectionEstablishedEv A
A calls B (GC1); B transfers the call to C.
CallCtrlConnectionDisConnectEv B
The application is monitors C. The PR
feature replaces the path after the call gets OpenLogicalChannelEvent if C is a CTI device
connected to C. (Dynamically registered CTIPorts and RP)
The same action applies to scenarios that
involve call forward at B. (The called party
transfers the call.)
2 A registered with CM1, B registered with In this case, both A are C represent called parties
CM2, and C registered with CM3. B calls C; when transfer completes. After the call is
C answers; B transfers the call to A. A answered, PR replaces the path. In this case, A
answers. The application is monitors only and C represent IP phones; the display will be
C. (The calling party transfers the call.) updated as a part of PR feature operation, that
makes either A or C as calling.
JTAPI events:
GC1: CallCtlConnEstablishedEv A
GC1: CallCtlConnDisconnectedEv B

OL-7242-02 A-39
No. Action Event

3 3.Trombone case: A registered to CM1, B For GC1 Call Observer:
registered to CM2, and C registered to
GC1: CallCtlConnEstablishedEv C
CM1. A calls B (GC1); B answers and
transfers the call to C (GC2). Path GC1: CallCtlConnDisconnected B
replacement connects A and C bypassing Before the PR feature replaces the path, the
CM2. The application observes both A and application sees two calls: GC1 with connections
C. (The called party transfers the call.) to A and C (external) and GC2 with connections to
C and A(external).
When the PR feature replaces the path, either GC1
changes GC2, or GC2 changes to GC1.
Assuming A's GCID changes from GC1 to GC2:
GC1: CiscoCallChangedEv
(oldGCID=GC1,newGCID=GC2 )
GC1: CallCtlConnDisconnected for A
GC1: CallCtlConnDisconnected for C
GC1: CallInValid
GC2: TermConnTalkingEvent for TerminalA
cause= CAUSE_QSIG_PR

A-40 OL-7242-02
No. Action Event

4 Trombone case: A registered to CM1, B Before the PR feature replaces the path, the
registered to CM2, and C registered to application will see two calls: GC1 with
CM1. B calls A and transfers the call to C. connections to A and B (external) and GC2 with
Path replacement connects A and C, connections to C and B(external). In this case, the
bypassing CM2. Application observes both application will not see any transfer start events.
A and C. (The calling party transfers the
When PR feature replaces the path, it updates the
call.)
display of A and C and path gets replaced,
resulting in a GCID change. Assuming A's GCID
is changed and made the calling party, the
following JTAPI events occur:
GC1: CiscoCallChangedEv (GC1 to GC2)
GC1: CallCtlConnDisconnected for A
GC1: CallCtlConnDisconnected for C
GC1: CallInValid
GC2: ConnCreatedEv A
GC2: ConnConnectedEv A
GC2: TermConnTalkingEvent for TerminalA
cause= CAUSE_QSIG_PR
5 A registered to CM1, B registered to CM2, Path replacement gets abandoned.
and C registered to CM1. A calls B; B
transfers the call to C. C answers and before
path replacement completes, C invokes a
feature (park, redirect, and so on).
6 In some conditions, call processing ignores JTAPI:
feature requests (redirect, park, transfer, Exception will be trhown from JTAPI for feature
and so on). This happens when a setup requests.
request is sent out, and the local CM is
waiting for connect from the other end.
7 In some cases, the application could receive No events
dead air when CM goes down when the PR
JTAPI Apps: Hang up the call
feature is trying to switch the RTP path.
This could happen to a previously
connected call.

OL-7242-02 A-41
Device State Server Message Flow
Device State Server Message Flow

DeviceStateServer Event flow for JTAPI Application
Terminal JTAPI
Application CiscoTerminal Implementation CTI
Observer Layer
CtiDeviceStateIdle
DeviceStateIdleEv
CiscoTermDSIdleEv
CtiDeviceStateActive
CiscoTermDSActiveEv
CtiDeviceStateAlerting
DeviceStateAlertingEv
CiscoTermDSAlertingEv
CtiDeviceStateHeld
DeviceStateHeldEv
CiscoTermDSHeldEv
120189

A-42 OL-7242-02
A P P E N D I X B
Cisco JTAPI Classes and Interfaces
This appendix contains a listing of all classes and interfaces that are available in
the Cisco JTAPI implementation for Cisco CallManager:
• Cisco JTAPI Version 1.2 Classes and Interfaces, page B-2, which lists all the
JTAPI v 1.2 classes and methods. The supported classes and methods have a
check mark in the Cisco JTAPI Support column.
• Cisco JTAPI Extension Classes and Interfaces, page B-23, which lists the
Cisco extension classes and methods.
• Cisco Trace Logging Classes and Interfaces, page B-27, which lists the error
tracing classes and methods.

OL-7242-02 B-1
Appendix B Cisco JTAPI Classes and Interfaces
Cisco JTAPI Version 1.2 Classes and Interfaces
Core Package
Table B-1 lists each JTAPI interface in the JTAPI Core Package followed by the
associated method(s) and whether the Cisco JTAPI implementation supports the
classes.
Table B-1 Support for javax.telephony
Cisco
JTAPI
Class Names Method Names Support Comments
Address addCallObserver Yes
addressObserver Yes
getAddressCapabilities Yes
getCallObservers Yes
getCapabilities Yes
getConnections Yes
getName Yes
getObservers Yes
getProvider Yes
getTerminals Yes
removeCallObserver Yes
removeObserver Yes
AddressObserver addressChangedEvent Yes
Call addObserver Yes
connect Yes A CallObserver must exist for the
Terminal or Address that originates
the call.
getCallCapabilities Yes
getCapabilities Yes

B-2 OL-7242-02
Table B-1 Support for javax.telephony (continued)
Cisco
JTAPI
getConnections Yes
getObservers Yes
getProvider Yes
getState Yes
removeObserver Yes
CallObserver callChangedEvent Yes
Connection disconnect Yes
getAddress Yes
getCall Yes
getCapabilities Yes
getConnectionCapabilities Yes
getState Yes
getTerminalConnections Yes
JtapiPeer getName Yes
getProvider Yes
getServices Yes
JtapiPeerFactory getJtapiPeer Yes
Provider addObserver Yes
createCall Yes
getAddress Yes
getAddressCapabilities() Yes
getAddressCapabilities(Ter- Yes
minal)
getAddresses Yes
getCallCapabilities() Yes

OL-7242-02 B-3
Cisco
JTAPI
getCallCapabilities(Termi- Yes
nal, Address)
getCalls Yes This method returns calls only
when CallObservers attach to
Addresses or Terminals, when a
RouteAddress is registered for
routing, or when a CiscoMediaTer-
minal is registered.
getCapabilities Yes
getConnectionCapabilities() Yes
getConnectionCapabili- Yes
ties(Terminal, Address)
getName Yes
getObservers Yes
getProviderCapabilities() Yes
getProviderCapabilities(Ter- Yes
minal)
getState Yes
getTerminal Yes
getTerminalCapabilities() Yes
getTerminalCapabilities(Ter- Yes
minal)
getTerminalConnectionCapa- Yes
bilities()
bilities(Terminal)
getTerminals Yes
removeObserver Yes

B-4 OL-7242-02
Cisco
JTAPI
shutdown Yes
ProviderObserver providerChangedEvent Yes
Terminal addCallObserver Yes
addObserver Yes
getAddresses Yes
getCallObservers Yes
getCapabilities Yes
getName Yes
getObservers Yes
getProvider Yes
getTerminalCapabilities Yes
getTerminalConnections Yes
removeCallObserver Yes
removeObserver Yes
TerminalConnection answer Yes
getCapabilities Yes
getConnection Yes
getState Yes
getTerminal Yes
bilities
TerminalObserver terminalChangedEvent Yes

OL-7242-02 B-5
Call Center Package

Table B-2 lists each JTAPI interface in the JTAPI Call Center Package followed
by the associated method(s) and whether the Cisco JTAPI implementation
supports the classes.
Table B-2 Support for javax.telephony.callcenter
Class Names Method Names Cisco JTAPI Support

ACDAddress getACDManagerAddress
getLoggedOnAgents
getNumberQueued
getOldestCallQueued
getQueueWaitTime
getRelativeQueueLoad
ACDAddressObserver
ACDConnection getACDManagerConnection
ACDManagerAddress getACDAddresses
ACDManagerConnection getACDConnections
Agent getACDAddress
getAgentAddress
getAgentID
getAgentTerminal
getState
setState
AgentTerminal addAgent
getAgents
removeAgents
setAgents
AgentTerminalObserver
CallCenterAddress addCallObserver

B-6 OL-7242-02
Table B-2 Support for javax.telephony.callcenter (continued)

CallCenterCall connectPredictive
getApplicationData
getTrunks
setApplicationData
CallCenterCallObserver
CallCenterProvider getACDAddresses
getACDManagerAddresses
getRouteableAddresses
CallCenterTrunk getCall
getName
getState
getType
RouteAddress cancelRouteCallback Yes
getActiveRouteSessions Yes
getRouteCallback Yes
registerRouteCallback Yes
RouteCallback reRouteEvent Yes
routeCallbackEndedEvent Yes
routeEndEvent Yes
routeEvent Yes
routeUsedEvent Yes
RouteSession endRoute Yes
getCause Yes
getRouteAddress Yes
getState Yes
selectRoute Yes

OL-7242-02 B-7
Call Center Capabilities Package

Table B-3 lists each JTAPI interface in the JTAPI Call Center Capabilities
Package followed by the associated method(s) and whether the Cisco JTAPI
implementation supports the classes.
Table B-3 Support for javax.telephony.callcenter.capabilities

ACDAddressCapabilities canGetACDManagerAddress
canGetLoggedOnAgents
canGetNumberQueued
canGetOldestCallQueued
canGetQueueWaitTime
canGetRelativeQueueLoad
ACDConnectionCapabilities canGetACDManagerConnection
ACDManagerAddressCapabilities canGetACDAddresses
ACDManagerConnectionCapabilities canGetACDConnections
AgentTerminalCapabilities canHandleAgents
CallCenterAddressCapabilities canAddCallObserver
CallCenterCallCapabilities canConnectPredictive
canGetTrunks
canHandleApplicationData
CallCenterProviderCapabilities canGetACDAddresses Yes
canGetACDManagerAddresses Yes
canGetRouteableAddresses Yes
RouteAddressCapabilities canRouteCalls Yes

B-8 OL-7242-02
Call Center Events Package

Table B-4 lists each JTAPI interface in the JTAPI Call Center Events Package
followed by the associated method(s) and whether the Cisco JTAPI
.
Table B-4 Support for javax.telephony.callcenter.events

ACDAddrBusyEv
ACDAddrEv getAgent
getAgentAddress
getAgentTerminal
getState
getTrunks
ACDAddrLoggedOffEv
ACDAddrLoggedOnEv
ACDAddrNotReadyEv
ACDAddrReadyEv
ACDAddrUnknownEv
ACDAddrWorkNotReadyEv
ACDAddrWorkReadyEv
AgentTermBusyEv
AgentTermEv getACDAddress
getAgent
getAgentAddress
getAgentID
getState
AgentTermLoggedOffEv
AgentTermLoggedOnEv
AgentTermNotReadyEv

OL-7242-02 B-9
Table B-4 Support for javax.telephony.callcenter.events (continued)

AgentTermReadyEv
AgentTermUnknownEv
AgentTermWorkNotReadyEv
AgentTermWorkReadyEv
CallCentCallAppDataEv getApplicationData
CallCentCallEv getCalledAddress
getCallingAddress
getCallingTerminal
getLastRedirectedAddress
getTrunks
CallCentConnEv
CallCentConnInProgressEv
CallCentEv getCallCenterCause
CallCentTrunkEv getTrunk
CallCentTrunkInvalidEv
CallCentTrunkValidEv
ReRouteEvent Yes
RouteCallbackEndedEvent getRouteAddress Yes
RouteEndEvent Yes
RouteEvent getCallingAddress Yes
getCallingTerminal Yes
getCurrentRouteAddress Yes
getRouteSelectAlgorithm Yes
getSetupInformation Yes
RouteSessionEvent getRouteSession Yes
RouteUsedEvent getCallingAddress Yes

B-10 OL-7242-02
Table B-4 Support for javax.telephony.callcenter.events (continued)

getDomain Yes
getRouteUsed Yes
Call Control Package

Table B-5 lists each JTAPI interface in the JTAPI Call Control Package followed
by the associated method(s) and whether the Cisco JTAPI Implementation
Table B-5 Support for javax.telephony.callcontrol
Cisco
JTAPI
CallControlAddress cancelForwarding Yes Only for Call Forward
All
getDoNotDisturb
getForwarding Yes Only for Call Forward
All
getMessageWaiting
setDoNotDisturb
setForwarding Yes Only for Call Forward
All
setMessageWaiting
setMessageWaitingSupport Yes Sets messageWaiting on
any Address that
belongs to the same
partition as the address
on which this method is
invoked
CallControlCall addParty

OL-7242-02 B-11
Table B-5 Support for javax.telephony.callcontrol (continued)
Cisco
JTAPI
conference Yes In a consult conference
scenario, only Original-
Call.conference (Con-
sultCall ) is supported.
ConsultCall.conference
(OriginalCall) is
supported.
consult(TerminalConnection) Yes
consult(TerminalConnection, Yes
String)
drop Yes
getCalledAddress Yes
getCallingAddress Yes
getConferenceController Yes
getConferenceEnable Yes
getLastRedirectedAddress Yes
getTransferController Yes
getTransferEnable Yes
offHook Yes
setConferenceController Yes
setConferenceEnable Yes
setTransferController Yes
setTransferEnable Yes

B-12 OL-7242-02
Cisco
JTAPI
transfer(Call) Yes In a consult transfer
scenario, only Original-
Call.transfer (Consult-
Call) is supported.
ConsultCall.transfer
(OriginalCall) is
supported.
transfer(String) Yes
CallControlCallObserver Yes
CallControlConnection accept Yes
addToAddress Yes
getCallControlState Yes
park Yes
redirect Yes Redirect allows a con-
nection in the CallCon-
trolConnection.ESTAB
LISHED state and Call-
ControlConnection.OF-
FERED state to be
redirect.
reject Yes
CallControlForwarding getDestinationAddress
getFilter
getSpecificCaller
getType
CallControlTerminal getDoNotDisturb
pickup (Address, Address)
pickup (Connection, Address)

OL-7242-02 B-13
Cisco
JTAPI
pickup (TerminalConnection,
Address)
pickupFromGroup(Address)
pickupFromGroup(String,
Address)
setDoNotDisturb
CallControlTerminalConnection getCallControlState Yes
hold Yes
join
leave
unhold Yes
CallControlTerminalObserver

B-14 OL-7242-02
Call Control Capabilities Package

Table B-6 lists each JTAPI interface in the JTAPI Call Control Capabilities
Package followed by the associated method(s) and whether the Cisco JTAPI
Table B-6 Support for javax.telephony.callcontrol.capabilities
Cisco
JTAPI Sup-
Class Names Method Names port
CallControlAddressCapabilities canCancelForwarding Yes
canGetDoNotDisturb Yes
canGetForwarding Yes
canGetMessageWaiting Yes
canSetDoNotDisturb Yes
canSetForwarding Yes
canSetMessageWaiting Yes
CallControlCallCapabilities canAddParty Yes
canConference Yes
canConsult Yes
canConsult(TerminalConnection) Yes
canConsult(TerminalConnection, Yes
String)
canDrop Yes
canOffHook Yes
canSetConferenceController Yes
canSetConferenceEnable Yes
canSetTransferController Yes
canSetTransferEnable Yes
canTransfer Yes
canTransfer(Call) Yes

OL-7242-02 B-15
Table B-6 Support for javax.telephony.callcontrol.capabilities (continued)
Cisco
JTAPI Sup-
Class Names Method Names port
canTransfer(String) Yes
CallControlConnectionCapabilities canAccept Yes
canAddToAddress Yes
canPark Yes
canRedirect Yes
canReject Yes
CallControlTerminalCapabilities canGetDoNotDisturb Yes
canPickup Yes
canPickup(Address, Address) Yes
canPickup(Connection, Address) Yes
canPickup(TerminalConnection, Yes
Address)
canPickupFromGroup Yes
canPickupFromGroup(Address) Yes
canPickupFromGroup(String, Address) Yes
canSetDoNotDisturb Yes
CallControlTerminalConnectionCapabilities canHold Yes
canJoin Yes
canLeave Yes
canUnhold Yes

B-16 OL-7242-02
Call Control Events Package

Table B-7 lists each JTAPI interface in the JTAPI Call Control Events Package
Table B-7 Support for javax.telephony.callcontrol.events

CallCtlAddrDoNotDisturbEv getDoNotDisturbState
CallCtlAddrEv
CallCtlAddrForwardEv getForwarding Yes
CallCtlAddrMessageWaitingEv getMessageWaitingState
CallCtlCallEv getCalledState Yes
getCallingAddress Yes
getLastRedirectedAddress Yes
CallCtlConnAlertingEv Yes
CallCtlConnDialingEv getDigits Yes
CallCtlConnDisconnectedEv Yes
CallCtlConnEstablishedEv Yes
CallCtlConnEv Yes
CallCtlConnFailedEv Yes
CallCtlConnInitiatedEv Yes
CallCtlConnNetworkAlertingEv Yes
CallCtlConnNetworkReachedEv Yes
CallCtlConnOfferedEv Yes
CallCtlConnQueuedEv getNumberInQueue Yes
CallCtlConnUnknownEv Yes
CallCtlEv getCallControlCause Yes
CallCtlTermConnBridgedEv

OL-7242-02 B-17
Table B-7 Support for javax.telephony.callcontrol.events (continued)

CallCtlTermConnDroppedEv Yes
CallCtlTermConnEv Yes
CallCtlTermConnHeldEv Yes
CallCtlTermConnInUseEv
CallCtlTermConnRingingEv Yes
CallCtlTermConnTalkingEv Yes
CallCtlTermConnUnknownEv Yes
CallCtlTermDoNotDisturbEv
CallCtlTermEv
Capabilities Package
Table B-8 lists each JTAPI interface in the JTAPI Capabilities Package followed
by the associated method(s) and whether the Cisco JTAPI implementation
Table B-8 Support for javax.telephony.capabilities

AddressCapabilities isObservable Yes
CallCapabilities canConnect Yes
isObservable Yes
ConnectionCapabilities canDisconnect Yes
ProviderCapabilities isObservable Yes
TerminalCapabilities isObservable Yes
TerminalConnectionCapabilities canAnswer Yes

B-18 OL-7242-02
Events Package
Table B-9 lists each JTAPI interface in the JTAPI Events Package followed by the
associated method(s) and whether the Cisco JTAPI Implementation supports the
classes.
Table B-9 Support for javax.telephony.events

AddrEv getAddress Yes
AddrObservationEndedEv Yes
CallActiveEv Yes
CallEv getCall Yes
CallInvalidEv Yes
CallObservationEndedEv getEndedObject Yes
ConnAlertingEv Yes
ConnConnectedEv Yes
ConnCreatedEv Yes
ConnDisconnectedEv Yes
ConnEv getConnection Yes
ConnFailedEv Yes
ConnInProgressEv Yes
ConnUnknownEv Yes
Ev getCause Yes
getID Yes
getMetaCode Yes
getObserved Yes
isNewMetaEvent Yes
ProvEv getProvider Yes
ProvInServiceEv Yes
ProvObservationEndedEv Yes

OL-7242-02 B-19
Table B-9 Support for javax.telephony.events (continued)

ProvOutOfServiceEv Yes
ProvShutdownEv Yes
TermConnActiveEv Yes
TermConnCreatedEv Yes
TermConnDroppedEv Yes
TermConnEvgetTerminalConnection Yes
TermConnPassiveEv Yes
TermConnRingingEv Yes
TermConnUnknownEv Yes
TermEv getTerminal Yes
TermObservationEndedEv Yes
Media Package
Table B-10 lists each JTAPI interface from the JTAPI Media Package followed by
the associated method(s) and whether the Cisco JTAPI implementation supports
the classes.
Table B-10 Support for javax.telephony.media

MediaCallObserver Yes
MediaTerminalConnection generateDtmf Yes
getMediaAvailability
getMediaState
setDtmfDetection Yes
startPlaying
startRecording
stopPlaying

B-20 OL-7242-02
Table B-10 Support for javax.telephony.media

stopRecording
useDefaultMicrophone
useDefaultSpeaker
usePlayURL
useRecordURL
Media Capabilities Package

Table B-11 lists each JTAPI interface in the JTAPI Media Capabilities Package
Table B-11 Support for javax.telephony.media.capabilities

MediaTerminalConnectionCapabilities canDetectDtmf Yes
canGenerateDtmf Yes
canStartPlaying Yes
canStartRecording Yes
canStopPlaying Yes
canStopRecording Yes
canUseDefaultMicrophone Yes
canUseDefaultSpeaker Yes
canUsePlayURL Yes
canUseRecordURL Yes

OL-7242-02 B-21
Media Events Package

Table B-12 lists each JTAPI interface in the JTAPI Media Events Package
Table B-12 Support for javax.telephony.media.events

MediaEv getMediaCause Yes
MediaTermConnAvailableEv
MediaTermConnDtmfEv getDtmfDigit Yes
MediaTermConnEv Yes
MediaTermConnStateEv getMediaState
MediaTermConnUnavailableEv
Unsupported Packages
Table B-13 shows the JTAPI packages that the Cisco JTAPI implementation
Table B-13 Unsupported JTAPI Packages
Unsupported JTAPI Packages

JTAPI Phone Package
JTAPI Phone Capabilities Package
JTAPI Phone Events Package
JTAPI Private Data Package
JTAPI Private Data Capabilities Package
JTAPI Private Data Events Package

B-22 OL-7242-02
Cisco JTAPI Extension Classes and Interfaces
Cisco JTAPI Extension Classes

Table B-14 Cisco JTAPI Extension Classes
Cisco Extension Classes Method Names

CiscoMediaCapability getMaxFramesPerPacket()
getPayloadType()
toString()
CiscoG723MediaCapability getBitRate()
toString()
RegistrationException
UnregistrationException
Cisco JTAPI Extension Interfaces

Table B-15 Cisco JTAPI Extension Interfaces and Their Methods
Cisco Extension Interfaces Method Names

CiscoAddrCreatedEv getAddress()
CiscoAddress getType()
CiscoAddrEv
CiscoAddrInService
CiscoAddrOutOfService
CiscoCall getCallID()

OL-7242-02 B-23
Table B-15 Cisco JTAPI Extension Interfaces and Their Methods (continued)

CiscoCallEv
CiscoCallID getCall()
intValue()
CiscoConferenceEndEv getConferenceCall()
getFinalCall()
CiscoConferenceStartEv getConferenceCall()
getFinalCall()
CiscoConnection getConnectionID()
getReason()
CiscoConnectionID getConnection()
intValue()
CiscoConsultCall getConsultingTerminalConnection()
CiscoConsultCallActiveEv getHeldTerminalConnection()
CiscoEv
CiscoJtapiPeer
CiscoMediaTerminal getRTPInputProperties()
register(InetAddress, int)
unregister()
CiscoProvEv

B-24 OL-7242-02

CiscoProvider getCallbackGuardEnabled()
getMediaTerminal()
getMediaTerminals()
setCallbackGuardEnabled()
CiscoRouteSession getCall()
CiscoRTPInputProperties getBitRate()
getEchoCancellation()
getLocalAddress()
getLocalPort()
getPacketSize()
getPayloadType()
CiscoRTPInputStartedEv getRTPInputProperties()
CiscoRTPOutputProperties getBitRate()
getPacketSize()
getPayloadType()
getPrecedenceValue()
getRemoteAddress()
getRemotePort()
CiscoRTPOutputStartedEv getRTPOutputProperties()
CiscoSynronousObserver
CiscoTermCreatedEv getTerminal()
CiscoTermEv

OL-7242-02 B-25

CiscoTerminal getRegistrationState()
CiscoTransferEndEv getFinalCall()
CiscoTransferStartEv getFinalCall()
ObjectContainer getObject()
setObject()
RTPBitRate
RTPPayload

B-26 OL-7242-02
Cisco Trace Logging Classes and Interfaces
Cisco Trace Logging Classes

Table B-16 Cisco Trace Logging Classes
Cisco Trace Logging Class Method Names

LogFileOutputStream close()
flush()
getCurrentFile()
getFileExtension()
getFileNameBase()
getMaxFiles()
getMaxFileSize()
write(byte[], int, int)
write(int)
NullTraceWriter close()
flush()
getEnabled()
print(String)
println(String)

OL-7242-02 B-27
Table B-16 Cisco Trace Logging Classes (continued)
Cisco Trace Logging Class Method Names

OutputStreamTraceWriter close()
flush()
getEnabled()
print(String)
println(String)
setOutputStream(OUputStream
TraceManagerFactory getModules()
registerModule(String)
registerModule(TraceModule)
registerModule(TraceModule, OutputStream)

B-28 OL-7242-02
Cisco Trace Logging Interfaces
Table B-17 Cisco Trace Logging Interfaces
Cisco Trace Logging Interfaces Method Names

ConditionalTrace disable()
enable()
Trace append(Object)
append(String)
getName()
isEnabled()
print(Object)
print(String)
print(String, Object)
print(String, String)
println(Object)
println(String)
println(String, Object)
println(String, String)
setDefaultMnemonic(String)

OL-7242-02 B-29
Table B-17 Cisco Trace Logging Interfaces (continued)

TraceManager disableAll()
disableTimeStamp()
enableAll()
enableTimeStamp()
getConditionalTrace(String)
getConditionalTrace(String, String)
getName()
getOutputStream()
getSubFacilities()
getTraces()
getTraceWriter()
getUnconditionalTrace(String)
getUnconditionalTrace(String, String)
removeTrace(String)
removeTrace(Trace)
setOutputStream(OutputStream)
setSubFacilities()
setTraceWriter()
TraceModule getTraceManager()
getTraceModuleName()
TRACETYPE

B-30 OL-7242-02
Table B-17 Cisco Trace Logging Interfaces (continued)

TraceWriter close()
flush()
getEnabled()
print(String)
println(String)
UnconditionalTrace

OL-7242-02 B-31

B-32 OL-7242-02
A P P E N D I X C
Troubleshooting CiscoJTAPI
This section contains CTI Error Codes, CiscoEvent IDs, and other information to
assist with troubleshooting efforts.
CTI Error Codes

Table C-1 CTI Error Codes
Error Name Description

CALL_DROPPED The call is dropped after the
feature request (hold, unhold,
transfer, conference) but before
completing the request.
CFWDALL_ALREADY_OFF Attempt to turn off CFWALL
while it is already off
CFWDALL_ALREADY_SET Attempt to set CFWALL while it
is already set
CFWDALL_DESTN_INVALID Attempt to CFWALL to an
invalid destination
COMMAND_NOT_IMPLEMENTED_ON_DEVICE Internal call processing error:
device does not support the
command.
CONFERENCE_ALREADY_PRESENT Attempt to conference a party
that is already in conference

OL-7242-02 C-1
Appendix C Troubleshooting CiscoJTAPI
CTI Error Codes
Table C-1 CTI Error Codes (continued)

CONFERENCE_FAILED Conference complete was not
successful.
CONFERENCE_FULL All conference bridges are busy.
CONFERENCE_INACTIVE Attempt to complete conference
while consult conference is not
active
CONFERENCE_INVALID_PARTICIPANT Trying to conference to self or an
invalid participant
CTIERR_ASSOCIATED_LINE_NOT_OPEN Command issued on a line that
must be open
CTIERR_CALL_AREADY_EXISTS Another call already exists on
the line.
CTIERR_CALLHANDLE_NOTINCOMINGCALL Attempt to answer a call that
either does not exists or is not in
the correct state
CTIERR_CALLHANDLE_UNKNOWN_TO_LINECONTROL Attempt to redirect call that was
unknown to line control
CTIERR_CANNOT_OPEN_DEVICE Device open failed because the
associated device is shutting
down (unregistering).
CTIERR_CANNOT_TERMINATE_MEDIA_ON_PHONE An application cannot terminate
media when the device has a
physical phone (the phone
always terminates the media).
CTIERR_CLUSTER_LINK_FAILURE Link failed to one of the call
managers in the cluster (network
error).
CTIERR_COMMAND_NOT_IMPLEMENTED_ON_DEVICE Device does not support the
command.
CTIERR_DB_ERROR Device query contained an
illegal device type.
CTIERR_DB_ILLEGAL_DEVICE_TYPE No longer used

C-2 OL-7242-02
CTI Error Codes

CTIERR_DB_NO_MORE_DEVICES No longer used
CTIERR_DEVICE_NOT_OPEN Attempt to open either a line on
a device that is not open or a
device that must already be reg-
istered (that is, an IP phone
device)
CTIERR_DIRECTORY_LOGIN_FAILED Login to the directory server
failed when the provider was
opened.
CTIERR_FAC_CMC_REASON_CMC_INVALID Client Matter Code (CMC)
entered is invalid
CTIERR_FAC_CMC_REASON_CMC_NEEDED Client Matter Code (CMC) is
required to offer the call
CTIERR_FAC_CMC_REASON_FAC_CMC_NEEDED Forced Authorization Code
(FAC) and Client Matter Code
(CMC) are required to offer the
call
CTIERR_FAC_CMC_REASON_FAC_INVALID Forced Authorization Code
(FAC) entered is invalid
CTIERR_FAC_CMC_REASON_FAC_NEEDED Forced Authorization Code
(FAC) is required to offer the call
CTIERR_HOLDFAILED Line control or call control
rejected hold.
CTIERR_ILLEGAL_CALLINGPARTY Attempt to originate call by using
a calling party that is not on the
device
CTIERR_ILLEGAL_CALLSTATE Line is not in a legal state to
invoke the command.
CTIERR_ILLEGAL_HANDLE Handle is unknown to the
system.
CTIERR_ILLEGAL_MESSAGE_FORMAT QBE protocol error (bug)

OL-7242-02 C-3
CTI Error Codes

CTIERR_INCORRECT_MEDIA_CAPABILITY Device registration failed due to
incorrect media capability.
CTIERR_INVALID_DTMFDIGITS Play DTMF request failed
because it is an invalid DTMF
digit.
CTIERR_LINECONTROL_FAILURE Line control refuses to let a new
call be initiated because of its
state (probably bug).
CTIERR_MEDIA_ALREADY_TERMINATED Attempt to terminate on a media
device that already has media
terminated
CTIERR_NOT_INITIALIZED Attempt to open a provider
before CTI initialization
completes
CTIERR_OPERATION_FAILED_QUIETCLEAR Feature unavailable for this call
due to temporary failure
CTIERR_PROVIDER_ALREADY_OPEN Attempt to reopen a provider
CTIERR_PROVIDER_NOT_OPEN Attempt to issue a CTI command
before the provider was open
CTIERR_REDIRECT_CALL_CALL_TABLE_FULL Internal error returned from call
control
CTIERR_REDIRECT_CALL_DESTINATION_BUSY Redirect destination is busy.
CTIERR_REDIRECT_CALL_DESTINATION_OUT_OF_ORDER Redirect destination is out of
order.
CTIERR_REDIRECT_CALL_DIGIT_ANALYSIS_TIMEOUT Internal error returned from call
control
CTIERR_REDIRECT_CALL_DOES_NOT_EXIST Attempt to redirect a call that
does not exist or is not longer
active
CTIERR_REDIRECT_CALL_INCOMPATIBLE_STATE Internal error returned from call
control

C-4 OL-7242-02
CTI Error Codes

CTIERR_REDIRECT_CALL_MEDIA_CONNECTION_FAILED Internal error returned from call
control
CTIERR_REDIRECT_CALL_NORMAL_CLEARING Internal error returned from call
control
CTIERR_REDIRECT_CALL_ORIGINATOR_ABANDONED Far end hung up on the call being
redirected
CTIERR_REDIRECT_CALL_PARTY_TABLE_FULL Internal error returned from call
control
CTIERR_REDIRECT_CALL_PENDING_REDIRECT_TRANSACTION Internal error returned from call
control
CTIERR_REDIRECT_CALL_PROTOCOL_ERROR Internal error returned from call
control
CTIERR_REDIRECT_CALL_UNKNOWN_DESTINATION Attempt to redirect to an
unknown destination
CTIERR_REDIRECT_CALL_UNKNOWN_ERROR Internal error returned from call
control
CTIERR_REDIRECT_CALL_UNKNOWN_PARTY Internal error returned from call
control
CTIERR_REDIRECT_CALL_UNRECOGNIZED_MANAGER Internal error returned from call
control
CTIERR_REDIRECT_CALLINFO_ERR Internal error returned from call
control
CTIERR_REDIRECT_ERR Internal error returned from call
control
CTIERR_RETRIEVEFAILED Line control or call control
rejected retrieve.
CTIERR_SSAPI_NOT_REGISTERED Redirect command was issued
when the internal supporting
interface was not initialized;
either CTI has not yet finished its
initialization or internal error
occurred.

OL-7242-02 C-5
CTI Error Codes

CTIERR_TIMEOUT No longer used
CTIERR_TRANSFERFAILED Transfer failed (probable cause
is one of the call legs was hung
up or disconnected from the far
end).
CTIERR_TRANSFERFAILED_CALLCONTROL_TIMEOUT Expected response from call
control not received during a
transfer
CTIERR_TRANSFERFAILED_DESTINATION_BUSY Attempt to transfer to a busy des-
tination
CTIERR_TRANSFERFAILED_DESTINATION_UNALLOCATED Attempt to transfer to a directory
number that is not registered
CTIERR_TRANSFERFAILED_TRANSFER_ALREADY_OUTSTANDING Existing transfer is still in
progress.
CTIERR_UNDEFINED_LINE Line was specified that was not
found on the device.
CTIERR_UNKNOWN_GLOBAL_CALL_HANDLE No longer used
CTIERR_UNRECOGNIZABLE_PDU QBE protocol error (bug)
DARES_INVALID_REQ_TYPE Internal call processing error:
DaRes invalid request type
DATA_SIZE_LIMIT_EXCEEDED XML data object size is bigger
than allowed.
DEVICE_OUT_OF_SERVICE Device is out of service.
DIGIT_GENERATION_ALREADY_IN_PROGRESS Digit generation is already in
progress.
DIGIT_GENERATION_CALLSTATE_CHANGED Call state invalid to continue
DIGIT_GENERATION_WRONG_CALL_HANDLE Call handle is invalid and call
may be already gone.
DIGIT_GENERATION_WRONG_CALL_STATE Call state is not valid to generate
digits.

C-6 OL-7242-02
CTI Error Codes

DIRECTORY_TEMPORARY_UNAVAILABLE Directory is temporarily unavail-
able.
INVALID_LINE_HANDLE Attempt to perform a line
operation on an invalid line
handle
LINE_INFO_DOES_NOT_EXIST Line information does not exist
in database DbDNResponse.
LINE_NOT_PRIMARY Internal error returned from call
control
MAX_NUMBER_OF_CTI_CONNECTIONS_REACHED The maximum number of CTI
connections reached; may need
to reconfigure the maximum
number of CTI connections or
log out of some applications to
be able to log in
MSGWAITING_DESTN_INVALID Attempt to set message waiting
lamp for an invalid DN; Message
Waiting Destination not found
OPERATION_NOTA_AVAILABLE_IN_CURRENT_STATE Feature operation is not available
in the current state.
PROTOCOL_TIMEOUT Internal error returned from call
control
PROVIDER_CLOSED Attempt to close provider while
it is already closed
RETRIEVEFAILED_ACTIVE_CALL_ON_LINE Error occurred in retrieving held
call; call may be already
dropped.
TRANSFER_INACTIVE Attempt to complete transfer
while consult transfer is not
there

OL-7242-02 C-7
CiscoEvent IDs
CiscoEvent IDs
//Prov Ev
CiscoProvFeatureUnRegisteredEv = 0x40000008;
//Term Ev
CiscoTermCreatedEv = 0x40001001;
CiscoTermDataEv = 0x40001002;
CiscoTermInServiceEv = 0x40001003;
CiscoTermOutOfServiceEv = 0x40001004;
CiscoTermRemovedEv = 0x40001005;
CiscoTermActiveStatusEv = 0x40001006;
CiscoTermAlertingStatusEv = 0x40001007;
CiscoTermHoldStatusEv = 0x40001008;
CiscoTermIdleStatusEv = 0x40001009;
CiscoTermButtonPressedEv = 0x40001010;
CiscoTermRegistraionFailedEv = 0x40001011;
//Addr Ev
CiscoAddrCreatedEv = 0x40002001;
CiscoAddrInServiceEv = 0x40002002;
CiscoAddrOutOfServiceEv = 0x40002003;
CiscoAddrRemovedEv = 0x40002004;
CiscoOutOfServiceEv = 0x40002005;
CiscoAddrAddedToTerminalEv = 0x40002006;
CiscoAddrRemovedFromTerminalEv = 0x40002007;
CiscoAddrAutoAcceptStatusChangedEv = 0x40002008;
//Call Ev
CiscoProvCallParkEv = 0x40003001;
CiscoConferenceEndEv = 0x40003002;
CiscoConferenceStartEv = 0x40003003;
CiscoConsultCallActiveEv = 0x40003004;
CiscoTransferEndEv = 0x40003005;
CiscoTransferStartEv = 0x40003006;
//RTP/Misc Ev
CiscoRTPInputStartedEv = 0x40004001;
CiscoRTPInputStoppedEv = 0x40004002;
CiscoRTPOutputStartedEv = 0x40004003;
CiscoRTPOutputStoppedEv = 0x40004004;
CiscoMediaOpenLogicalChannelEv = 0x40004005;
// TermConnEvent
CiscoTermConnPrivacyChangedEv = 0x40005001;
CiscoConsultCallActiveEv = 0x40003004;
CiscoTransferEndEv = 0x40003005;
CiscoTransferStartEv = 0x40003006;
CiscoToneChangedEv = 0x40003007;
CiscoCallChangedEv = 0x40003008;

C-8 OL-7242-02
Additional Troubleshooting Information
Viewing JTAPI Debug Output

To view JTAPI debug output, use the JTPREFS application to change the trace
settings. The JTPREFS application allows you to enable or disable various kinds
of tracing.
JTPREFS is installed in the %SystemRoot%\java\lib directory along with the
JTAPI classes. Cisco JTAPI Preferences is installed by default in Program
Files\JTAPITools.
To open the Cisco JTAPI Preferences utility, choose Start > Programs > Cisco
JTAPI > JTAPI Preferences.
The following trace levels are defined:
• WARNING - warning events
• INFORMATIONAL - status events
• DEBUG - debugging events
If DEBUG is enabled, JTPREFS allows you to enable or disable various
debugging levels.
The following debugging levels are defined:
• TAPI_DEBUGGING - to trace JTAPI methods and events
• TAPI_IMPLDEBUGGING - internal JTAPI implementation trace
• CTI_DEBUGGING - to trace CallManager events that are sent to the JTAPI
implementation
• CTIIMPL_DEBUGGING - internal CTICLIENT implementation trace
• PROTOCOL_DEBUGGING - full CTI protocol decoding
• MISC_DEBUGGING - miscellaneous low-level debug trace
Traces can be directed to a specific path and folder rather than to the application
directory by default. The same trace folder could be used for successive or more
than one simultaneous launch of JTAPI. Different launches of JTAPI would also
send the traces to different folders. This allows simultaneous JTAPI instances to
maintain independent trace destinations

OL-7242-02 C-9

C-10 OL-7242-02
I N D EX
Cisco JTAPI 1-3

A
classes and interfaces B-1
Actor.java install internationalization 1-17
Cisco JTAPI examples 3-5 JTAPI examples 3-1
addresses and terminals Cisco JTAPI examples
relationship 1-8 Actor.java 3-5
unobserved 1-8 MakeCall.java 3-2
alarm services 1-11 makecall.java 3-2
AutoAccept support for CTIPort and Originator.java 3-10
RoutePoint 1-82
Receiver.java 3-14
auto update of API 1-75
running makecall 3-21
StopSignal.java 3-16
B Trace.java 3-17
TraceWindow.java 3-18
barge and privacy event notification 1-66 CiscoJtapiExceptions 1-17
CiscoTerminal filter and
ButtonPressedEvents 1-78
C
CiscoTermRegistrationFailed event 1-83
call forward setting 1-15 clear calls interface 1-17
call park 1-15 conference
reminder 1-16 Cisco extensions 1-24
retrieval 1-16 events 1-26
CallSelect and UnSelect event notification 1-67 scenarios 1-25
CiscoCallID 1-9 transfer and conference enhancement 1-27
CiscoConnectionID 1-9 conference and join 1-63

OL-7242-02 IN-1
Index
connection 1-9 endpoint model 1-29

initialization 1-30
media termination extensions 1-28
D
payload and parameter negotiation 1-29
device recovery 1-17 payload selection 1-30
CTI ports 1-18 receive channel allocation 1-31
CTIRoutePoint 1-18 receiving and responding to media flow
events 1-36
phones 1-18
starting transmission and reception 1-31
directory change notification 1-19
stopping transmission and reception 1-32
display name interface 1-51
media termination at route point 1-70
dynamic CTIPort registration per call 1-68
message sequence charts A-1
modifying calling number 1-79
I multiple calls per DN 1-57
invoking makecall 3-21

N
J new and changed information xxxiii
JTAPI parameters
application control 1-12 O
Jtapi.ini 1-12
Originator.java
Cisco JTAPI examples 3-10
M
MakeCall.java P
Cisco JTAPI Examples 3-2
presentation indicator (PI) for the call 1-88
makecall.java 3-2
media

IN-2 OL-7242-02
Index
R T
Receiver.java TerminalConnection 1-9

Cisco JTAPI examples 3-14 threaded callbacks 1-9
redirect 1-38 Trace.java
redirect set original called ID 1-74 Cisco JTAPI examples 3-17
redundancy 1-44 TraceWindow.java
cluster abstraction 1-44 Cisco JTAPI examples 3-18
CTIManager failure 1-50 transfer and conferece
CTIManagers 1-48 conference 1-23
heartbeats 1-51 transfer and conference
invoking CTIManager 1-49 consult without media 1-27
server failure 1-46 transfer and DirectTransfer 1-62
related documentation xlii troubleshooting
required software xlii CiscoJTAPI c-1
ringer
enable or disable 1-19
X
routing 1-40
running makecall.java 3-21 xsi object pass through 1-55
SelectRoute interface enhancement 1-85

SetMessageWaiting interface 1-52
shared line support 1-57
single step transfer 1-75
StopSignal.java
Cisco JTAPI examples 3-16

OL-7242-02 IN-3
Index

IN-4 OL-7242-02

Cisco JTAPI Developer Guide For CCM 4.1

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cisco JTAPI Developer Guide For CCM 4.1

Uploaded by

Copyright:

Available Formats

Cisco JTAPI Developer Guide for

Cisco CallManager 4.1(3)

Customer Order Number:

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Documentation DVD xliv

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

CiscoSynchronousObserver Interface 1-10

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco Route Session Implementation 1-41

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Barge and Privacy Event Notification 1-66

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Implementation 2-1

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

All Superinterfaces 2-31

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

All Superinterfaces 2-83

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Direct Known Subclasses 2-136

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

All Superinterfaces 2-153

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

All Implemented Interfaces 2-276

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

JTAPI Examples 3-1

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

APPENDIX A Message Sequence Charts A-1

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Redirect Set OriginalCalledID A-19

APPENDIX B Cisco JTAPI Classes and Interfaces B-1

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Media Package B-20

APPENDIX C Troubleshooting CiscoJTAPI c-1

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

This chapter introduces Cisco JTAPI implementation, describes the purpose of

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

New and Changed Information

Cisco CallManager 4.1(3)

Windows 2003 Support

Auto Call Pickup

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Call Information for Existing Call Pickup Feature

Call Information for New Auto Call Pickup Feature

CP Requires Previous Calls on the Device to be in the Connected Call State

Cisco JTAPI Developer Guide for Cisco CallManager 4.1(3)

Cisco CallManager Release 4.1(2)

Caveats for Cisco CallManager Release 4.1(2)