-
Americas HeadquartersCisco Systems, Inc.170 West Tasman DriveSan
Jose, CA 95134-1706 USAhttp://www.cisco.comTel: 408 526-4000
800 553-NETS (6387)Fax: 408 527-0883
Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
Text Part Number: OL-18531-01
http://www.cisco.com
-
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 UCBs 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.
CCDE, CCENT, CCSI, Cisco Eos, Cisco Explorer, Cisco
HealthPresence, Cisco IronPort, the Cisco logo, Cisco Nurse
Connect, Cisco Pulse, Cisco SensorBase, Cisco StackPower, Cisco
StadiumVision, Cisco TelePresence, Cisco TrustSec, Cisco Unified
Computing System, Cisco WebEx, DCE, Flip Channels, Flip for Good,
Flip Mino, Flipshare (Design), Flip Ultra, Flip Video, Flip Video
(Design), Instant Broadband, and Welcome to the Human Network are
trademarks; Changing the Way We Work, Live, Play, and Learn, Cisco
Capital, Cisco Capital (Design), Cisco:Financed (Stylized), Cisco
Store, Flip Gift Card, and One Million Acts of Green are service
marks; and Access Registrar, Aironet, AllTouch, AsyncOS, Bringing
the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP,
CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo,
Cisco IOS, Cisco Lumin, Cisco Nexus, Cisco Press, Cisco Systems,
Cisco Systems Capital, the Cisco Systems logo, Cisco Unity,
Collaboration Without Limitation, Continuum, EtherFast,
EtherSwitch, Event Center, Explorer, Follow Me Browsing, GainMaker,
iLYNX, IOS, iPhone, IronPort, the IronPort logo, Laser Link,
LightStream, Linksys, MeetingPlace, MeetingPlace Chime Sound, MGX,
Networkers, Networking Academy, PCNow, PIX, PowerKEY, PowerPanels,
PowerTV, PowerTV (Design), PowerVu, Prisma, ProConnect, ROSA,
SenderBase, SMARTnet, Spectrum Expert, StackWise, WebEx, and the
WebEx logo are registered trademarks of Cisco 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. (1002R)
Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2) Copyright 2002-2009, Cisco
Systems, Inc. All rights reserved.
-
Cisco Unified JTAOL-18531-01
C O N T E N T S
Preface xxxix
Purpose xxxix
Audience xxxix
Organization xl
Related Documentation xli
Developer Support xli
Conventions xlii
Obtaining Documentation and Submitting a Service Request
xliii
Cisco Product Security Overview xliii
OpenSSL Notice xliii
C H A P T E R 1 Overview 1-1
JTAPI Overview 1-1Cisco Unified JTAPI and Contact Centers
1-2Cisco Unified JTAPI and Enterprises 1-2Cisco Unified JTAPI
Applications 1-3Jtprefs Application 1-3
Cisco Unified JTAPI Concepts 1-4CiscoObjectContainer Interface
1-4JtapiPeer and Provider 1-4Address and Terminal Relationships
1-6CiscoConnectionID 1-11
Threaded Callbacks 1-11CiscoSynchronousObserver Interface
1-11Querying Dynamic Objects 1-12
Alarm Services 1-12
Software Requirements 1-13
1-13
C H A P T E R 2 New and Changed Information 2-1
Cisco Unified Communications Manager Release 7.1(2) 2-1
Features Supported in Previous Releases 2-2Cisco Unified
Communications Manager Release 7.0(1) 2-2
iiiPI Developers Guide for Cisco Unified Communications Manager
Release 7.1(2)
-
Contents
Cisco Unified Communications Manager Release 6.1 2-3Cisco
Unified Communications Manager Release 6.0 2-3Cisco Unified
Communications Manager Release 5.1 2-4Cisco Unified Communications
Manager Release 5.0 2-4
Backward Compatibility 2-5
C H A P T E R 3 Features Supported by Cisco Unified JTAPI
3-1Drop Any Party 3-1IPv6 Support 3-2Direct Transfer Across Lines
3-3Join Across Lines or Connected Conference Across Lines 3-7Swap
or Cancel and Transfer or Conference Behavior 3-12Message Waiting
Indicator Enhancement 3-13Park Monitoring and Assisted DPark
Support 3-13Logical Partitioning 3-15Component Updater 3-16Support
for Cisco Unified IP Phone 6900 Series 3-16Join Across Lines with
Conference Enhancements 3-17Locale Infrastructure Development
3-18Do Not DisturbReject 3-19Calling Party Normalization 3-20Click
to Conference 3-20Extension Mobility Username Login 3-20Java Socket
Connect Timeout 3-21selectRoute() with Calling Search Space and
Feature Priority 3-21Call Pickup 3-21Certificate Download API
Enhancement 3-22Join Across Lines 3-22Intercom Support for
Extension Mobility 3-23Recording and Silent Monitoring 3-23Intercom
3-26Arabic and Hebrew Language Support 3-27Do Not Disturb
3-28Secure Conferencing 3-29Cisco Unified IP 7931G Phone
Interaction 3-30Version Format Change 3-31Calling Party IP Address
3-31Multilevel Precedence and Preemption Support 3-31Noncontroller
Adding of Parties to Conferences 3-31Conference Chaining 3-31
ivCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Forwarding on No Bandwidth and Unregistered DN 3-33Directed Call
Park 3-33Voice MailBox Support 3-34Privacy On Hold
3-34CiscoRTPHandle Interface on Cisco RTP Events 3-35Hold Reversion
3-35Translation Pattern Support 3-35Calling Party IP Address
3-36Join Across Lines 3-37New Error Code in
CiscoTermRegistrationFailedEv 3-37Star (*) 50 Update 3-38Call
Forward Override 3-38Partition Support 3-39Hairpin Support 3-42QoS
Support 3-42Transport Layer Security (TLS) 3-43SIP Phone Support
3-49Secure Real-Time Protocol Key Material 3-52SIP REFER or REPLACE
3-59SIP 3XX Redirection 3-61Terminal and Address Restrictions
3-62Unicode Support 3-65Linux, Windows, and Solaris Installation
3-68Silent Install 3-69Command Line Invocation 3-69JTAPI Client
Installer 3-69JRE 1.2 and JRE 1.3 Support Removal 3-70Superprovider
and Change Notification 3-71Alternate Script Support
3-73Half-Duplex Media Support 3-73Network Alerting 3-75Auto Updater
for Linux 3-75Call Select Status 3-76JTAPI Version Information
3-76Call Forward 3-76Call Park 3-76Park Retrieval 3-77Park Reminder
3-77Park DN Monitor 3-77CiscoJtapiExceptions 3-77
vCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Cisco Unified JTAPI Install Internationalization 3-78Clear Calls
3-78Device Recovery 3-78Device Recovery for Phones 3-78CTI
RoutePoints 3-78CTI Ports 3-78Directory Change Notification
3-79Enable or Disable Ringer 3-79Transfer and Conference Extensions
3-79Transfer 3-79Conference 3-82Consult Without Media 3-85Media
Termination Extensions 3-85Cisco Unified Communications Manager
Media Endpoint Model 3-86Cisco MediaTerminal 3-88Receiving and
Responding to Media Flow Events 3-91Redirect 3-92Routing
3-93Redundancy 3-96Cluster Abstraction 3-96Cisco Unified
Communications Manager Server Failure 3-98Redundancy in CTI
Managers 3-98Calling Party Display Name 3-100Set MessageWaiting
3-101Quiet Clear 3-101GetCallInfo 3-102DeleteCall
3-102GetGlobalCallID 3-102GetCallID in RTP Events 3-103XSI Object
Pass Through 3-103Cisco VG248 and ATA 186 Analog Phone Gateways
3-104Multiple Calls Per DN 3-104Shared Line Support 3-104Transfer
and DirectTransfer 3-107Conference and Join 3-107Barge and Privacy
Event Notification 3-109CallSelect and UnSelect Event Notification
3-109Dynamic CTI Port Registration 3-110Media Termination at Route
Point 3-111Redirect Set Original Called ID 3-113
viCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Single Step Transfer 3-114Autoupdate of API 3-115Changes in
DeviceType Name Handling 3-117CiscoTerminal Filter and
ButtonPressedEvents 3-117Modifying Calling Number 3-118AutoAccept
Support for CTI Ports and Route Points
3-120CiscoTermRegistrationFailed Event 3-121SelectRoute Interface
Enhancement 3-123Presentation Indicator for Calls 3-124Progress
State Converted to Disconnect State 3-125Device State Server
3-126Forced Authorization and Client Matter Codes 3-127Super
Provider (Disable Device Validation) 3-129Q.Signaling (QSIG) Path
Replacement 3-130Network Events 3-130
C H A P T E R 4 Cisco Unified JTAPI Installation 4-1
Overview 4-1Determining the Current JTAPI Version 4-2
Installing the Cisco Unified JTAPI Software 4-3Silent Install
Invocation 4-3Command Line Invocation 4-4End User Installation
4-4Installation Procedures 4-4
Auto Install for Upgrades 4-7
Configuring Cisco Unified JTAPI Preferences 4-7JTAPI Tracing Tab
4-8Log Destination Tab 4-10CallManagers Tab 4-13Advanced Tab
4-14Security Tab 4-16Language Tab 4-18
Administering User Information for JTAPI Applications 4-19
Fields in the jtapi.ini File 4-19
C H A P T E R 5 Hierarchy for All Cisco Unified JTAPI Packages
5-1
Class Hierarchy 5-1
Interface Hierarchy 5-2
viiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
C H A P T E R 6 Cisco Unified JTAPI Extensions 6-1
Class Hierarchy 6-1
CiscoAddressCallInfo 6-2Declaration 6-2Constructors 6-2Fields
6-2Methods 6-2Related Documentation 6-3
CiscoG711MediaCapability 6-3Declaration 6-3Constructors
6-3Fields 6-4Methods 6-4Related Documentation 6-4
CiscoG723MediaCapability 6-4Declaration 6-5Constructors
6-5Fields 6-5Methods 6-6Related Documentation 6-6
CiscoG729MediaCapability 6-6Declaration 6-6Constructors
6-7Fields 6-7Methods 6-7Related Documentation 6-8
CiscoGSMMediaCapability 6-8Declaration 6-8Constructors 6-8Fields
6-8Methods 6-9Related Documentation 6-9
CiscoJtapiVersion 6-9Declaration 6-9Constructors 6-9Fields
6-10Methods 6-10Related Documentation 6-10
CiscoMediaCapability 6-10
viiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 6-11Subclasses 6-11Constructors 6-11Fields
6-11Methods 6-12Related Documentation 6-12
CiscoRegistrationException 6-12Declaration 6-13Implemented
Interfaces 6-13Constructors 6-13Methods 6-13Related Documentation
6-13
CiscoRTPParams 6-14Declaration 6-14Constructors 6-14Fields
6-14Methods 6-14Related Documentation 6-15
CiscoUnregistrationException 6-15Declaration 6-15Implemented
Interfaces 6-15Constructors 6-15Fields 6-16Methods 6-16Related
Documentation 6-16
CiscoWideBandMediaCapability 6-16Declaration 6-16Constructors
6-17Fields 6-17Methods 6-17Related Documentation 6-17
Interface Hierarchy 6-18
CiscoAddrActivatedEv 6-26Superinterfaces 6-26Declaration
6-26Fields 6-26Methods 6-27Related Documentation
6-27Superinterfaces 6-28
ixCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 6-28Fields 6-28Methods 6-29Related Documentation
6-30
CiscoAddrActivatedOnTerminalEv 6-30Superinterfaces
6-30Declaration 6-30Fields 6-30Methods 6-31Related Documentation
6-31
CiscoAddrAddedToTerminalEv 6-31Superinterfaces 6-32Declaration
6-32Fields 6-32Methods 6-33Related Documentation 6-33
CiscoAddrAutoAcceptStatusChangedEv 6-33Superinterfaces
6-33Declaration 6-33Fields 6-34Methods 6-34Related Documentation
6-35
CiscoAddrCreatedEv 6-35Superinterfaces 6-35Declaration
6-35Fields 6-35Methods 6-36Inherited Methods 6-36Related
Documentation 6-36
CiscoAddress 6-36Superinterfaces 6-37Subinterfaces 6-37Fields
6-37Methods 6-38Related Documentation 6-48
CiscoAddressObserver 6-48Superinterfaces 6-48Declaration
6-48Fields 6-48
xCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Methods 6-48Related Documentation 6-49
CiscoAddrEv 6-49Superinterfaces 6-49Subinterfaces
6-49Declaration 6-49Fields 6-49Methods 6-50Related Documentation
6-50
CiscoAddrCreatedEv 6-51Fields 6-51Methods 6-51Inherited Methods
6-52Parameters 6-52Value Range 6-52Related Documentation 6-52
CiscoAddrInServiceEv 6-52Superinterfaces 6-52Declaration
6-52Fields 6-53Methods 6-53Related Documentation 6-54
CiscoAddrIntercomInfoChangedEv 6-54Superinterfaces
6-54Declaration 6-54Fields 6-54Methods 6-55Related Documentation
6-55
CiscoAddrIntercomInfoRestorationFailedEv 6-55Superinterfaces
6-56Declaration 6-56Fields 6-56Methods 6-57Related Documentation
6-57
CiscoAddrOutOfServiceEv 6-57Superinterfaces 6-57Declaration
6-58Fields 6-58Methods 6-59
xiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Related Documentation 6-59
CiscoAddrParkStatusEv 6-59Declaration 6-60Fields 6-60Methods
6-60Value Ranges 6-61Related Documentation 6-61
CiscoAddrRecordingConfigChangedEv 6-61Superinterfaces
6-61Declaration 6-61Fields 6-62Methods 6-63Related Documentation
6-63
CiscoAddrRemovedEv 6-63Superinterfaces 6-63Declaration
6-64Fields 6-64Methods 6-64Related Documentation 6-65
CiscoAddrRemovedFromTerminalEv 6-65Superinterfaces
6-65Declaration 6-65Fields 6-66Methods 6-66Related Documentation
6-67
CiscoAddrRestrictedEv 6-67Superinterfaces 6-67Declaration
6-67Fields 6-67Methods 6-68Related Documentation 6-69
CiscoAddrRestrictedOnTerminalEv 6-69Superinterfaces
6-69Declaration 6-69Fields 6-69Methods 6-70Related Documentation
6-70
CiscoCall 6-70Superinterfaces 6-71
xiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Subinterfaces 6-71Declaration 6-71Fields 6-71Methods
6-72Parameters 6-75Conference Controller 6-76Related Documentation
6-81
CiscoCallChangedEv 6-82Superinterfaces 6-82Declaration
6-82Fields 6-82Methods 6-84Related Documentation 6-85
CiscoCallConsultCancelledEv 6-85Superinterfaces 6-85Declaration
6-85Fields 6-85Methods 6-86Related Documentation 6-86
CiscoCallCtlConnOfferedEv 6-86Superinterfaces 6-86Declaration
6-86Fields 6-87Methods 6-88Related Documentation 6-88
CiscoCallCtlTermConnHeldReversionEv 6-89Superinterfaces
6-89Declaration 6-89Fields 6-89Methods 6-90Related Documentation
6-91
CiscoCallEv 6-91Superinterfaces 6-91Subinterfaces
6-91Declaration 6-91Fields 6-91Methods 6-101Related Documentation
6-101
CiscoCallFeatureCancelledEv 6-102
xiiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 6-102Methods 6-102Related Documentation 6-102
CiscoCallID 6-102Superinterfaces 6-102Declaration 6-103Fields
6-103Methods 6-103Related Documentation 6-103
CiscoMediaCallSecurityIndicator 6-103Declaration 6-104Fields
6-104Methods 6-104Related Documentation 6-104
CiscoCallSecurityStatusChangedEv 6-104Superinterfaces
6-105Declaration 6-105Fields 6-105Methods 6-107Related
Documentation 6-107
CiscoConferenceChain 6-107Declaration 6-108Fields 6-108Methods
6-108Related Documentation 6-108
CiscoConferenceChainAddedEv 6-108All Superinterfaces
6-109Declaration 6-109Fields 6-109Methods 6-111Related
Documentation 6-111
CiscoConferenceChainRemovedEv 6-111Superinterfaces
6-112Declaration 6-112Fields 6-112Methods 6-114Related
Documentation 6-114
CiscoConferenceEndEv 6-115Superinterfaces 6-115
xivCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 6-115Fields 6-115Methods 6-117Related Documentation
6-118
CiscoConferenceStartEv 6-118Superinterfaces 6-119Declaration
6-119Fields 6-119Methods 6-121Related Documentation 6-122
CiscoConnection 6-122All Superinterfaces 6-123Declaration
6-123Fields 6-123Methods 6-124Documentation 6-133
CiscoConnectionID 6-133Superinterfaces 6-133Declaration
6-134Fields 6-134Methods 6-134Related Documentation 6-134
CiscoConsultCall 6-134Superinterfaces 6-134Declaration
6-135Fields 6-135Methods 6-135Related Documentation 6-137
CiscoConsultCallActiveEv 6-137Superinterfaces 6-137Declaration
6-137Fields 6-138Methods 6-140Related Documentation 6-140
CiscoEv 6-141Superinterfaces 6-141Subinterfaces 6-141Declaration
6-141Fields 6-141
xvCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Methods 6-142Related Documentation 6-142
CiscoFeatureReason 6-142Declaration 6-142Fields 6-143Related
Documentation 6-144
CiscoIntercomAddress 6-144Superinterfaces 6-145Declaration
6-145Fields 6-145Methods 6-146Related Documentation 6-148
CiscoJtapiException 6-148Declaration 6-148Fields 6-149Methods
6-159Related Documentation 6-160
CiscoJtapiPeer 6-160Superinterfaces 6-160Declaration 6-161Fields
6-161Methods 6-161Related Documentation 6-161
CiscoJtapiProperties 6-162Declaration 6-162Fields 6-162Methods
6-162Related Documentation 6-169
CiscoLocales 6-169Declaration 6-170Fields 6-170Methods
6-172Related Documentation 6-172
CiscoMediaConnectionMode 6-172Declaration 6-172Fields
6-172Methods 6-173Related Documentation 6-173
CiscoMediaEncryptionAlgorithmType 6-173
xviCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Superinterfaces 6-173
Fields 6-173
Related Documentation 6-173
CiscoMediaEncryptionKeyInfo 6-174Declaration 6-174Fields
6-174Methods 6-174Related Documentation 6-174
CiscoMediaOpenLogicalChannelEv 6-175Superinterfaces
6-175Declaration 6-175Fields 6-175Methods 6-176Related
Documentation 6-177
CiscoMediaSecurityIndicator 6-178Declaration 6-178Fields
6-178Related Documentation 6-178
CiscoMediaTerminal 6-179Superinterfaces 6-179Declaration
6-179Fields 6-179Methods 6-180Related Documentation 6-188
CiscoMonitorInitiatorInfo 6-188Declaration 6-188Fields
6-189Methods 6-189Related Documentation 6-189
CiscoMonitorTargetInfo 6-189Declaration 6-189Fields 6-189Methods
6-190Related Documentation 6-190
CiscoObjectContainer 6-190Subinterfaces 6-190Declaration
6-190Fields 6-190Methods 6-191
xviiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Related Documentation 6-191
CiscoOutOfServiceEv 6-191Superinterfaces 6-191Subinterfaces
6-191Declaration 6-191Fields 6-192Methods 6-193Related
Documentation 6-193
CiscoPartyInfo 6-193Declaration 6-193Fields 6-193Methods
6-194Related Documentation 6-194
CiscoProvCallParkEv 6-194Superinterfaces 6-195Declaration
6-195Fields 6-195Methods 6-196Related Documentation
6-197CiscoProvEv 6-197Superinterfaces 6-197Subinterfaces
6-197Declaration 6-197Fields 6-197Methods 6-198
CiscoProvFeatureEv 6-198Superinterfaces 6-199Subinterfaces
6-199Declaration 6-199Fields 6-199Methods 6-200Related
Documentation 6-200
CiscoProvFeatureID 6-200Declaration 6-200Fields 6-201Methods
6-201Related Documentation 6-201
CiscoProvider 6-201Superinterfaces 6-201
xviiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 6-201Fields 6-201Methods 6-202Related Documentation
6-208
CiscoProviderCapabilities 6-208Superinterfaces 6-208Declaration
6-208Methods 6-209Related Documentation 6-210
CiscoProviderCapabilityChangedEv 6-210Declaration 6-210Fields
6-210Methods 6-211 Related Documentation 6-212
CiscoProviderObserver 6-212Superinterfaces 6-212Declaration
6-213Methods 6-213Related Documentation 6-213
CiscoProvTerminalCapabilityChangedEv 6-213Superinterfaces
6-213Declaration 6-213Fields 6-214Methods 6-214Related
Documentation 6-215
CiscoRecorderInfo 6-215Declaration 6-215Fields 6-215Methods
6-215Related Documentation 6-215
CiscoRestrictedEv 6-216Superinterfaces 6-216Subinterfaces
6-216Declaration 6-216Fields 6-216Methods 6-217Related
Documentation 6-217
CiscoRouteAddress 6-217Superinterfaces 6-218
xixCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 6-218Fields 6-218Methods 6-218Related Documentation
6-219
CiscoRouteEvent 6-219Superinterfaces 6-219Declaration
6-219Fields 6-219Methods 6-220Related Documentation 6-220
CiscoRouteSession 6-220Superinterfaces 6-220Declaration
6-221Fields 6-221Methods 6-222Related Documentation 6-232
CiscoRouteTerminal 6-232Superinterfaces 6-233Declaration
6-233Fields 6-233Methods 6-234Related Documentation 6-238
CiscoRouteUsedEvent 6-238Superinterfaces 6-239Declaration
6-239Fields 6-239Methods 6-239Related Documentation 6-239
CiscoRTPBitRate 6-240Declaration 6-240Fields 6-240Methods
6-240Related Documentation 6-240
CiscoRTPHandle 6-240Declaration 6-241Fields 6-241Methods
6-241Related Documentation 6-241
CiscoRTPInputKeyEv 6-241
xxCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Superinterfaces 6-241Declaration 6-242Fields 6-242Methods
6-242Related Documentation 6-243
CiscoRTPInputProperties 6-243Declaration 6-244Fields
6-244Methods 6-244Related Documentation 6-245
CiscoRTPInputStartedEv 6-245Superinterfaces 6-245Declaration
6-246Fields 6-246Methods 6-246Related Documentation 6-247
CiscoRTPInputStoppedEv 6-247Superinterfaces 6-247Declaration
6-247Fields 6-248Methods 6-248Related Documentation 6-249
CiscoRTPOutputKeyEv 6-249Superinterfaces 6-249Declaration
6-250Fields 6-250Methods 6-250Related Documentation 6-251
CiscoRTPOutputProperties 6-251Declaration 6-252Fields
6-252Methods 6-253Related Documentation 6-254
CiscoRTPOutputStartedEv 6-254Superinterfaces 6-254Declaration
6-254Fields 6-254Methods 6-255Related Documentation 6-256
xxiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
CiscoRTPOutputStoppedEv 6-256Superinterfaces 6-256Declaration
6-256Fields 6-256Methods 6-257Related Documentation 6-258
CiscoRTPOutputKeyEv 6-258Superinterfaces 6-258Declaration
6-258Fields 6-258Methods 6-259Related Documentation 6-260
CiscoRTPOutputProperties 6-260Declaration 6-260Fields
6-260Methods 6-261Related Documentation 6-262
CiscoRTPOutputStartedEv 6-262Superinterfaces 6-262Declaration
6-262Fields 6-262Methods 6-263Related Documentation 6-264
CiscoRTPOutputStoppedEv 6-264Superinterfaces 6-264Declaration
6-264Fields 6-264Methods 6-265Related Documentation 6-266
CiscoRTPPayload 6-266Declaration 6-266Fields 6-266Methods
6-267Related Documentation 6-267
CiscoSynchronousObserver 6-267Declaration 6-268Fields
6-268Methods 6-268Related Documentation 6-268
xxiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
CiscoTermActivatedEv 6-268Superinterfaces 6-269Declaration
6-269Fields 6-269Methods 6-269Related Documentation 6-270
CiscoTermButtonPressedEv 6-270Superinterfaces 6-270Declaration
6-270Fields 6-271Methods 6-272Related Documentation 6-272
CiscoTermConnMonitoringEndEv 6-272Superinterfaces
6-273Declaration 6-273Fields 6-273Methods 6-273Related
Documentation 6-274
CiscoTermConnMonitoringStartEv 6-274Superinterfaces
6-274Declaration 6-274Fields 6-274Inherited Fields 6-275Methods
6-275Related Documentation 6-275
CiscoTermConnMonitorInitiatorInfoEv 6-275Superinterfaces
6-276Declaration 6-276Fields 6-276Methods 6-276Related
Documentation 6-277
CiscoTermConnMonitorTargetInfoEv 6-277Superinterfaces
6-277Declaration 6-277Fields 6-278Methods 6-278Related
Documentation 6-278
CiscoTermConnPrivacyChangedEv 6-279Declaration 6-279
xxiiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Fields 6-279Methods 6-279Related Documentation 6-279
CiscoTermConnRecordingEndEv 6-279Superinterfaces
6-280Declaration 6-280Fields 6-280Methods 6-280Related
Documentation 6-281
CiscoTermConnRecordingStartEv 6-281Superinterfaces
6-281Declaration 6-281Fields 6-281Methods 6-281Related
Documentation 6-282
CiscoTermConnRecordingTargetInfoEv 6-282Superinterfaces
6-282Declaration 6-282Fields 6-282Methods 6-283Related
Documentation 6-283
CiscoTermConnSelectChangedEv 6-283Superinterfaces
6-284Declaration 6-284Fields 6-284Methods 6-284Related
Documentation 6-285
CiscoTermCreatedEv 6-285Superinterfaces 6-285Declaration
6-285Fields 6-285Methods 6-286Related Documentation 6-286
CiscoTermDataEv 6-286Superinterfaces 6-287Declaration
6-287Fields 6-287Methods 6-288Related Documentation 6-288
xxivCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
CiscoTermDeviceStateActiveEv 6-288Superinterfaces
6-288Declaration 6-289Fields 6-289Methods 6-289Related
Documentation 6-290
CiscoTermDeviceStateAlertingEv 6-290Superinterfaces
6-290Declaration 6-290Fields 6-290Methods 6-291Related
Documentation 6-291
CiscoTermDeviceStateHeldEv 6-291Superinterfaces 6-292Declaration
6-292Fields 6-292Methods 6-292Related Documentation 6-293
CiscoTermDeviceStateIdleEv 6-293Superinterfaces 6-293Declaration
6-293Fields 6-293Methods 6-294Related Documentation 6-294
CiscoTermDeviceStateWhisperEv 6-294Superinterfaces
6-295Declaration 6-295Fields 6-295Methods 6-295Related
Documentation 6-296
CiscoTermDNDOptionChangedEv 6-296Superinterfaces 6-296Fields
6-296Methods 6-297
CiscoTermDNDStatusChangedEv 6-298Superinterfaces
6-298Declaration 6-298Fields 6-298Methods 6-299
xxvCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Related Documentation 6-299
CiscoTermEv 6-300Superinterfaces 6-300Subinterfaces
6-300Declaration 6-300Fields 6-300Related Documentation 6-301
CiscoTermEvFilter 6-301Declaration 6-301Fields 6-302Methods
6-302Related Documentation 6-304
CiscoTerminal 6-304Superinterfaces 6-305Subinterfaces
6-305Declaration 6-305Fields 6-305Methods 6-307Related
Documentation 6-313
CiscoTerminalConnection 6-313Superinterfaces 6-314Declaration
6-314Fields 6-314Methods 6-314Related Documentation 6-317
CiscoTerminalObserver 6-317Superinterfaces 6-317Declaration
6-318Fields 6-318Methods 6-318Related Documentation 6-318
CiscoTerminalProtocol 6-318Superinterfaces 6-318Fields
6-319Related Documentation 6-319
CiscoTermInServiceEv 6-319Superinterfaces 6-319Declaration
6-319Fields 6-320
xxviCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Methods 6-321Related Documentation 6-321
CiscoTermOutOfServiceEv 6-322Superinterfaces 6-322Declaration
6-322Fields 6-322Methods 6-323Related Documentation 6-323
CiscoTermRegistrationFailedEv 6-324Superinterfaces
6-324Declaration 6-324Fields 6-324Methods 6-325Related
Documentation 6-326
CiscoTermRemovedEv 6-326Superinterfaces 6-326Declaration
6-326Fields 6-326Methods 6-327Related Documentation 6-327
CiscoTermRestrictedEv 6-328Superinterfaces 6-328Declaration
6-328Fields 6-328Methods 6-329Related Documentation 6-329
CiscoTermSnapshotCompletedEv 6-329Superinterfaces
6-330Declaration 6-330Fields 6-330Methods 6-330Related
Documentation 6-331
CiscoTermSnapshotEv 6-331Superinterfaces 6-331Declaration
6-331Fields 6-332Methods 6-332Related Documentation 6-333
CiscoTone 6-333
xxviiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Superinterfaces 6-333Fields 6-333
CiscoToneChangedEv 6-333Superinterfaces 6-334Declaration
6-334Fields 6-334Methods 6-336Related Documentation 6-337
CiscoTransferEndEv 6-337Superinterfaces 6-337Declaration
6-337Fields 6-337Methods 6-339Related Documentation 6-340
CiscoTransferStartEv 6-340Superinterfaces 6-340Declaration
6-340Fields 6-341Methods 6-343Related Documentation 6-343
CiscoUrlInfo 6-344Declaration 6-344Fields 6-344Methods
6-344Related Documentation 6-345
ComponentUpdater 6-345Declaration 6-345Methods 6-345Related
Documentation 6-346
C H A P T E R 7 Cisco Unified JTAPI Alarms and Services 7-1
Alarm Class Hierarchy 7-1
AlarmManager 7-1Declaration 7-2Constructors 7-3Methods 7-3
AlarmWriter 7-4Declaration 7-4All Known Implementing Classes
7-4
xxviiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Member Summary 7-4Methods 7-4
DefaultAlarm 7-5Declaration 7-5All Implemented Interfaces
7-5Member Summary 7-6Constructors 7-6Methods 7-6
DefaultAlarmWriter 7-7Declaration 7-7All Implemented Interfaces
7-8Member Summary 7-8Constructors 7-8Methods 7-9
ParameterList 7-10Declaration 7-11Member Summary
7-11Constructors 7-12Methods 7-12
Alarm Interface Hierarchy 7-13
Alarm 7-13Declaration 7-13All Known Implementing Classes
7-13Member Summary 7-14Fields 7-15Methods 7-16
AlarmWriter 7-17Declaration 7-17All Known Implementing Classes
7-17Member Summary 7-17
Services Tracing Class Hierarchy 7-19
BaseTraceWriter 7-19Declaration 7-19All Implemented Interfaces
7-19Direct Known Subclasses 7-19Member Summary 7-19Constructors
7-20Methods 7-21
ConsoleTraceWriter 7-23
xxixCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 7-23All Implemented Interfaces 7-23Member Summary
7-23Constructors 7-24Methods 7-24
LogFileTraceWriter 7-25Declaration 7-26All Implemented
Interfaces 7-26Member Summary 7-26Fields 7-27Constructors
7-28Methods 7-29
OutputStreamTraceWriter 7-30Declaration 7-30All Implemented
Interfaces 7-31Constructors 7-31Methods 7-32
SyslogTraceWriter 7-32Declaration 7-32All Implemented Interfaces
7-33Member Summary 7-33Constructors 7-33Methods 7-34
TraceManagerFactory 7-34Declaration 7-34Member Summary
7-35Methods 7-35
Services Tracing Interface Hierarchy 7-36
Trace 7-36Declaration 7-36All Known Subinterfaces 7-36Member
Summary 7-37Fields 7-38Methods 7-40
ConditionalTrace 7-42Declaration 7-42All Superinterfaces
7-42Member Summary 7-42
UnconditionalTrace 7-43
xxxCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Declaration 7-43All Superinterfaces 7-43Member Summary 7-43
TraceManager 7-43Declaration 7-44Member Summary 7-44Methods
7-45
TraceModule 7-47Declaration 7-47All Known Subinterfaces
7-47Member Summary 7-48Methods 7-48
TraceWriter 7-48Declaration 7-48All Known Subinterfaces 7-48All
Known Implementing Classes 7-48Member Summary 7-49Methods 7-49
TraceWriterManager 7-50Declaration 7-50All Superinterfaces
7-51Member Summary 7-51Methods 7-51
Tracing Implementation Class Hierarchy 7-52
TraceImpl 7-52Declaration 7-52All Implemented Interfaces
7-52Methods 7-52Inherited Methods 7-54
ConditionalTraceImpl 7-55Declaration 7-55All Implemented
Interfaces 7-55Methods 7-55Inherited Methods 7-56
UnconditionalTraceImpl 7-56Declaration 7-56All Implemented
Interfaces 7-56Methods 7-56Inherited Methods 7-56
xxxiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
TraceManagerImpl 7-57Declaration 7-57All Implemented Interfaces
7-57Constructors 7-57Methods 7-57Deprecated 7-60Inherited Methods
7-60
TraceWriterManagerImpl 7-60Declaration 7-60All Implemented
Interfaces 7-61Constructors 7-61Methods 7-61
C H A P T E R 8 Cisco Unified JTAPI Examples 8-1
MakeCall.java 8-1
Actor.java 8-3
Originator.java 8-7
Receiver.java 8-10
StopSignal.java 8-11
Trace.java 8-11
TraceWindow.java 8-12
Running makecall 8-14
A P P E N D I X A Message Sequence Charts A-1
Shared Line Support A-2AddressInService/AddressOutofService
Events A-3Incoming Call to Shared Address A-4Outgoing Call from
Shared Address A-5Shared Address Calling Itself A-6
Transfer and Direct Transfer A-6DirectTransfer/Arbitrary
Transfer Scenario A-7Direct Transfer/Arbitrary TransferPage 2
A-8Consult Transfer A-8
Conference and Join A-8Join/Arbitrary Conference A-9Consult
Conference A-10Join Across Lines with Enhancements A-11
Barge and Privacy A-15
xxxiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Barge A-16CBarge A-17Privacy A-18
CallSelect and UnSelect A-18
Dynamic CTIPort Registration Per Call A-19
Media Termination at Route Point A-19
Redirect Set OriginalCalledID A-21
Single Step Transfer A-22
Modifying Calling Number A-24AutoAccept for CTIPort and
RoutePoint A-28
Forced Authorization and Customer Matter Codes A-28
Super Provider Message Flow A-33SuperProvider and Change
Notification Enhancements Use Cases A-34
QSIG Path Replacement A-35
Device State Server A-37
Partition Support A-37Using getPartition() API A-37Using
getAddress (String number, String partition) A-38Park DN
A-40Partition Change A-41JTAPI Partition Support A-42
Hairpin Support A-44
QoS Support A-45JTAPI QoS A-46
TLS Security A-46
SRTP Key Material A-48
Device and Line Restriction A-49
SIP Support A-52
SIP REPLACE A-52SIP REFER A-58SIP 3XX Redirection A-66
Unicode Support A-70
Backward Compatibility Enhancements A-71
Half Duplex Media A-79
Recording and Monitoring A-80
Intercom A-102
Do Not Disturb A-110
xxxiiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
DNDR A-114
Secure Conferencing A-118
JTAPI Cisco Unified IP 7931G Phone Interaction A-122Locale
Infrastructure Development Scenarios A-142Calling Party
Normalization A-143Click to Conference A-150Call Pickup
A-162selectRoute() with Calling Search Space and Feature Priority
A-174Extension Mobility Login Username A-175Calling Party IP
Address A-177CiscoJtapiProperties A-178IPv6 Support A-178Direct
Transfer Across Lines Use Cases A-201Connected Conference or Join
Across Lines Use Cases New Phones Behavior A-207Enhanced MWI Use
Cases A-208Join Across Lines Enhancements A-209Swap or Cancel and
Transfer or Conference Behavior Change A-214Drop Any Party Use
Cases A-226Park Monitoring Support A-255Logical Partitioning
Feature Use Cases A-285ComponentUpdater Enhancement Use cases
A-288IPv6 Support A-288Support for Cisco Unified IP Phone 6900
Series A-289
A P P E N D I X B Cisco Unified JTAPI Classes and Interfaces
B-1
Cisco Unified JTAPI Version 1.2 Classes and Interfaces B-1Core
Package B-2Call Center Package B-4Call Center Capabilities Package
B-6Call Center Events Package B-7Call Control Package B-8Call
Control Capabilities Package B-11Call Control Events Package
B-12Capabilities Package B-13Events Package B-14Media Package
B-15Media Capabilities Package B-16Media Events Package
B-16Unsupported Packages B-17
xxxivCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
Cisco Unified JTAPI Extension Classes and Interfaces B-17Cisco
Unified JTAPI Extension Classes B-17Cisco Unified JTAPI Extension
Interfaces B-18
Cisco Trace Logging Classes and Interfaces B-20Cisco Trace
Logging Classes B-20Cisco Trace Logging Interfaces B-21
A P P E N D I X C Troubleshooting Cisco Unified JTAPI C-1
CTI Error Codes C-1
CiscoEventIDs C-10Provider Events C-10Terminal Events
C-10Address Events C-11Call Events C-11RTP Events C-12TermConn
Events C-12
Reason Codes C-12
Cause Codes C-13
Additional Troubleshooting Information C-17Viewing JTAPI Debug
Output C-17Log Files For JTAPI Client Installer C-18Troubleshooting
Tips for ISMP Installer C-18Unable to Create Provider Directory
Login Timeout C-19
A P P E N D I X D Cisco Unified JTAPI Operations-by-Release
D-1
A P P E N D I X E CTI Supported Devices E-1
A P P E N D I X F Constant Field Values F-1
com.cisco.* F-1CiscoAddrActivatedEv
F-1CiscoAddrActivatedOnTerminalEv F-1CiscoAddrAddedToTerminalEv
F-1CiscoAddrAutoAcceptStatusChangedEv F-2CiscoAddrCreatedEv
F-2CiscoAddress F-2CiscoAddrInServiceEv
F-3CiscoAddrIntercomInfoChangedEv F-3
xxxvCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
CiscoAddrIntercomInfoRestorationFailedEv
F-3CiscoAddrOutOfServiceEv F-3CiscoAddrRecordingConfigChangedEv
F-3CiscoAddrRemovedEv F-3CiscoAddrRemovedFromTerminalEv
F-4CiscoAddrRestrictedEv F-4CiscoAddrRestrictedOnTerminalEv
F-4CiscoCall F-4CiscoCallChangedEv
F-5CiscoCallCtlTermConnHeldReversionEv F-5CiscoCallEv
F-5CiscoCallSecurityStatusChangedEv F-9CiscoConferenceChainAddedEv
F-9CiscoConferenceChainRemovedEv F-10CiscoConferenceEndEv
F-10CiscoConferenceStartEv F-10CiscoConnection
F-10CiscoConsultCallActiveEv F-11CiscoFeatureReason
F-11CiscoG711MediaCapability F-12CiscoG723MediaCapability
F-12CiscoG729MediaCapability F-12CiscoGSMMediaCapability
F-12CiscoJtapiException F-13CiscoLocales
F-19CiscoMediaConnectionMode F-20CiscoMediaEncryptionAlgorithmType
F-20CiscoMediaOpenLogicalChannelEv F-20CiscoMediaSecurityIndicator
F-21CiscoOutOfServiceEv F-21CiscoPartyInfo F-21CiscoProvCallParkEv
F-22CiscoProvFeatureID F-22CiscoProviderCapabilityChangedEv
F-22CiscoProvTerminalCapabilityChangedEv F-22CiscoRestrictedEv
F-23CiscoRouteSession F-23CiscoRouteTerminal F-24CiscoRTPBitRate
F-24CiscoRTPInputKeyEv F-24
xxxviCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
CiscoRTPInputStartedEv F-24CiscoRTPInputStoppedEv
F-24CiscoRTPOutputKeyEv F-24CiscoRTPOutputStartedEv
F-25CiscoRTPOutputStoppedEv F-25CiscoRTPPayload
F-25CiscoTermActivatedEv F-26CiscoTermButtonPressedEv
F-26CiscoTermConnMonitoringEndEv F-26CiscoTermConnMonitoringStartEv
F-26CiscoTermConnMonitorInitiatorInfoEv
F-27CiscoTermConnMonitorTargetInfoEv
F-27CiscoTermConnPrivacyChangedEv F-27CiscoTermConnRecordingEndEv
F-27CiscoTermConnRecordingStartEv
F-27CiscoTermConnRecordingTargetInfoEv
F-27CiscoTermConnSelectChangedEv F-28CiscoTermCreatedEv
F-28CiscoTermDataEv F-28CiscoTermDeviceStateActiveEv
F-28CiscoTermDeviceStateAlertingEv F-28CiscoTermDeviceStateHeldEv
F-28CiscoTermDeviceStateIdleEv F-29CiscoTermDeviceStateWhisperEv
F-29CiscoTermDNDOptionChangedEv F-29CiscoTermDNDStatusChangedEv
F-29CiscoTerminal F-29CiscoTerminalConnection
F-30CiscoTerminalProtocol F-30CiscoTermInServiceEv
F-30CiscoTermOutOfServiceEv F-30CiscoTermRegistrationFailedEv
F-31CiscoTermRemovedEv F-31CiscoTermRestrictedEv
F-31CiscoTermSnapshotCompletedEv F-31CiscoTermSnapshotEv
F-31CiscoTone F-32CiscoToneChangedEv F-32CiscoTransferEndEv
F-32CiscoTransferStartEv F-32
xxxviiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Contents
CiscoUrlInfo F-32CiscoWideBandMediaCapability F-33Alarm
F-33LogFileTraceWriter F-33Trace F-34
A P P E N D I X G Deprecated API G-1
Deprecated Interfaces G-1
Deprecated Fields G-1
Deprecated Methods G-2
I N D E X
xxxviiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Preface
This chapter describes the objectives, intended audience, and
organization of this document and describes the conventions that
convey instructions and other information. It contains the
following sections:
Purpose, page xxxix
Audience, page xxxix
Organization, page xl
Related Documentation, page xli
Developer Support, page xli
Conventions, page xlii
Obtaining Documentation and Submitting a Service Request, page
xliii
Cisco Product Security Overview, page xliii
OpenSSL Notice, page xliii
PurposeThis document describes the Cisco Unified Communications
Manager (formerly Cisco Unified CallManager) Java Telephony
Application Programming Interface (JTAPI). Cisco Unified JTAPI
enables programming interfaces to support different
implementations. This document outlines basic Cisco Unified JTAPI
concepts including extensions, classes and interfaces.
To implement JTAPI for Cisco Unified Communications Manager,
Cisco conforms to the JTAPI Specification v1.2 while providing
extensions that enhance JTAPI with the advanced features of Cisco
Unified Communications Manager.
As new versions of Cisco Unified Communications Manager and the
Cisco Unified JTAPI implementation are released, Cisco maintains
stable and reliable API extensions, and as new Cisco Unified
Communication Manager features become available, additional
extensions are provided.
AudienceThis document is for developers who write applications
that extend the functionality of the APIs that are described in
this document.
xxxixCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Preface
This document assumes that you have knowledge of the Java
language and the Sun JTAPI v 1.2 specification.You must also have
knowledge or experience in the following areas:
Extensible Markup Language (XML)
Hypertext Markup Language (HTML)
Hypertext Transport Protocol (HTTP)
Socket programming
TCP/IP Protocol
Web Service Definition Language (WSDL) 1.1
Secure Sockets Layer (SSL)
In addition, as a user of the Cisco Unified Communications
Manager APIs, you must have a firm understanding of XML Schema. For
more information about XML Schema, refer to
http://www.w3.org/TR/xmlschema-0/.
You must have an understanding of Cisco Unified Communications
Manager and its applications. See the Related Documentation section
on page xli for Cisco Unified Communications Manager documents and
other related technologies.
OrganizationThe following table provides an outline of the
chapters in this document.
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, New and Changed Information This chapter describes
the new and changed features in Cisco Unified Communications
Manager releases that are supported by Cisco Unified JTAPI.
Chapter 3, Features Supported by Cisco Unified JTAPI
This chapter describes additional features that are supported by
Cisco Unified JTAPI.
Chapter 4, Cisco Unified JTAPI Installation
This chapter describes the Cisco Unified JTAPI installation
process.
Chapter 5, Hierarchy for All Cisco Unified JTAPI Packages
This chapter provides the Hierarchy for All Cisco Unified JTAPI
Packages.
Chapter 6, Cisco Unified JTAPI Extensions This chapter describes
the extensions (interfaces and classes) that are available for
implementation in a Cisco Unified Communications Manager.
Chapter 7, Cisco Unified JTAPI Alarms and Services
This chapter describes the alarms and services that are
available for implementation in a Cisco Unified Communications
Manager.
Chapter 8, Cisco Unified JTAPI Examples This chapter provides
the examples of source code for makecall, the Cisco Unified JTAPI
program that is used to test the JTAPI installation.
Appendix A, Message Sequence Charts This appendix contains
message flow diagrams.
xlCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
http://www.w3.org/XML/http://www.w3.org/Protocols/rfc2616/rfc2616.htmlhttp://www.w3.org/TR/wsdlhttp://www.w3.org/TR/xmlschema-0/
-
Preface
Related DocumentationThis section lists documents and URLs that
provide information on Cisco Unified Communications Manager, Cisco
Unified IP Phones, and the technologies that are required to
develop applications.
Cisco Unified Communications Manager Release 7.1(2)A suite of
documents that relate to the installation and configuration of
Cisco Unified Communications Manager. Refer to the Cisco Unified
Communications Manager Documentation Guide for Release 7.1(2) for a
list of documents on installing and configuring Cisco Unified
Communications Manager 7.1(2), including:
Cisco Unified Communications Manager Administration Guide,
Release 7.1(2).
Cisco Unified Communications Manager System Guide, Release
7.1(2).
Cisco Unified Communications Manager Features and Services
Guide, Release 7.1(2).
Cisco Unified IP Phones and ServicesA suite of documents that
relate to the installation and configuration of Cisco Unified IP
Phones.
Cisco Distributed DirectorA suite of documents that relate to
the installation and configuration of Cisco
DistributedDirector.
Related Information
To obtain the latest version of the complete Sun Microsystems
JTAPI specification files, go directly to
http://java.sun.com/products/jtapi.
Developer SupportThe Developer Support Program provides
formalized support for Cisco Systems interfaces to enable
developers, customers, and partners in the Cisco Service Provider
solutions Ecosystem and Cisco AVVID Partner programs to accelerate
their delivery of compatible solutions.
The Developer Support Engineers are an extension of the product
technology engineering teams. They have direct access to the
resources necessary to provide expert support in a timely
manner.
For additional information on this program, refer to the
Developer Support Program web site at
http://developer.cisco.com.
Appendix B, Cisco Unified JTAPI Classes and Interfaces
This appendix contains a listing of all the classes and
interfaces that are available in Cisco Unified JTAPI.
Appendix C, Troubleshooting Cisco Unified JTAPI
This appendix contains CTI Error Codes, CiscoEvent IDs, and
other troubleshooting information.
Appendix D, Cisco Unified JTAPI Operations-by-Release
This appendix contains a list of supported, unsupported,
changed, and under consideration or review by Cisco Unified
Communications Manager release.
Appendix E, CTI Supported Devices This appendix contains a list
of CTI supported devices.
Appendix F, Constant Field Values This appendix lists the static
final fields and their values.
Appendix G, Deprecated API This appendix lists lists the APIs,
fields, and methods that have been deprecated.
Chapter Description
xliCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
http://developer.cisco.comhttp://java.sun.com/products/jtapi
-
Preface
Developers using the Cisco Unified Communications Manager
Release 5.0(1) Extension Mobility API Developer Guide are
encouraged to join the Cisco Developer Support Program. This
program provides a consistent level of support while leveraging
Cisco interfaces in development projects.
Note Cisco Technical Assistance Center (TAC) support does not
include Extension Mobility API developer support and is limited to
Cisco AVVID installation/configuration and Cisco-developed
applications. For more information about the Developer Support
Program, please contact Cisco at [email protected].
ConventionsThis document uses the following conventions:
Notes use the following conventions:
Note Means reader take note. Notes contain helpful suggestions
or references to material not covered in the publication.
Timesavers use 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 screen font.
boldface
screen fontInformation you must enter is in boldface screen
font.
italic screen font
Arguments for which you supply values are in italic screen
font.
This pointer highlights an important line of text in an
example.
^ The symbol represents the key labeled Controlfor 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.
xliiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Preface
Timesaver Means the described action saves time. You can save
time by performing the action described in the paragraph.
Tips use the following conventions:
Tip Means the following are useful tips.
Obtaining Documentation and Submitting a Service Request For
information on obtaining documentation, submitting a service
request, and gathering additional information, see the monthly
What's New in Cisco Product Documentation, which also lists all new
and revised Cisco technical documentation, at:
http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html
Subscribe to the What's New in Cisco Product Documentation as a
Really Simple Syndication (RSS) feed and set content to be
delivered directly to your desktop using a reader application. The
RSS feeds are a free service and Cisco currently supports RSS
Version 2.0.
Cisco Product Security Overview This product contains
cryptographic features and is subject to United States and local
country laws governing import, export, transfer and use. Delivery
of Cisco cryptographic products does not imply third-party
authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product
you agree to comply with applicable laws and regulations. If you
are unable to comply with U.S. and local laws, return this product
immediately.
A summary of U.S. laws governing Cisco cryptographic products
may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html.
If you require further assistance please contact us by sending
email to [email protected].
OpenSSL NoticeThe following link provides information about the
OpenSSL notice:
http://www.cisco.com/en/US/products/hw/phones/ps379/products_licensing_information_listing.html
xliiiCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.htmlhttp://www.cisco.com/wwl/export/crypto/tool/[email protected]://www.cisco.com/en/US/products/hw/phones/ps379/products_licensing_information_listing.html
-
Preface
xlivCisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Cisco Unified JTAPI Developers Guide for CiscOL-18531-01
C H A P T E R 1
Overview
This chapter describes the major concepts with which you need to
be familiar before creating Java Telephony Application Programming
Interface (JTAPI) applications for Cisco Unified Communications
Manager systems. It contains the following sections:
JTAPI Overview, page 1-1
Cisco Unified JTAPI Concepts, page 1-4
Threaded Callbacks, page 1-11
Alarm Services, page 1-12
Software Requirements, page 1-13
For information about Cisco Unified Communications Manager
features, see Chapter 3, Features Supported by Cisco Unified JTAPI.
Also see Appendix E, CTI Supported Devices and Appendix D, Cisco
Unified JTAPI Operations-by-Release for more information and CTI
devices and supported features.
JTAPI OverviewCisco Unified JTAPI serves as a programming
interface standard developed by Sun Microsystems for use with
Java-based computertelephony applications. Cisco JTAPI implements
the Sun JTAPI 1.2 specification with additional Cisco extensions.
You use Cisco JTAPI to develop applications that:
Control and observe Cisco Unified Communications Manager
phones.
Route calls by using ComputerTelephony Integration (CTI) ports
and route points (virtual devices).
Basic telephony APIs that are supported comprises conference,
transfer, connect, answer, and redirect APIs.
A package of JTAPI interfaces, located in the javax.telephony.*
hierarchy, defines a programming model by which Java applications
interact with telephony resources. For more information about
interfaces, see Appendix B, Cisco Unified JTAPI Classes and
Interfaces.
This section describes the following subjects:
Cisco Unified JTAPI and Contact Centers, page 1-2
Cisco Unified JTAPI and Enterprises, page 1-2
Cisco Unified JTAPI Applications, page 1-3
Jtprefs Application, page 1-3
1-1o Unified Communications Manager Release 7.1(2)
-
Chapter 1 OverviewJTAPI Overview
Cisco Unified JTAPI and Contact CentersCisco Unified JTAPI gets
used in a contact center to monitor device status and to issue
routing instructions to send calls to the right place at the right
time, to start and stop recording instructions while retrieving
call statistics for analysis; and to screen-pop calls into CRM
applications, automated scripting, and remote call control.
Cisco Unified JTAPI and EnterprisesCisco Unified JTAPI, used in
an enterprise environment, combines user availability, location,
and preferences for a uniquely tailored environment for
presence-based routing. For example, in a financial environment,
market data, business logic, and call control combine in a
browser-based application to enable brokers and analysts to respond
to rapid changes in the global financial markets.
In a heathcare environment, call control, doctor/patient lookup,
and emergency response team paging combine in a browser-based
console. Further, in a hospitality environment, caller data gets
linked with POS systems to automate room or restaurant
reservations, dispatch taxis, and schedule wakeup calls.
Figure 1-1 shows a typical Cisco Unified Communications Manager
and Cisco Unified JTAPI in an enterprise configuration.
Figure 1-1 Cisco Unified Communications Manager and Cisco
Unified JTAPI
IP
IP
IPIP
IP
IP
CUAEVM
serverUser connected
to voicemail
Emergency caller
PSAPoperator
CER
JTAPI is installed here
JTAPI is installed here
JTAPI is installed here
Agent phone
UCC Express
Attendentconsole
Agent desktop
UCC-Enterprise
CUCMcluster
Call controlpath
SCCP Link
1923
43
1-2Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewJTAPI Overview
Cisco Unified JTAPI ApplicationsA Cisco Unified JTAPI
application can flow as follows:
Obtain JTAPIPeer object instance from JTAPIPeerFactory.
Obtain a Provider by using the getProvider() API on
JTAPIPeer.
Obtain from the Provider, the Terminal and Address for use in
your application.
Determine capabilities of relevant objects.
Add observers for the objects that application wants to
monitor/control.
Begin application flow (for example, begin calls).
The following example shows a basic JTAPI application.
public void getProvider () {try {
JtapiPeer peer = JtapiPeerFactory.getJtapiPeer ( null
);System.out.println ("Got peer "+peer);Provider provider =
peer.getProvider(cti-server;login=username;passwd=pass");System.out.println
("Got provider "+provider);MyProviderObserver providerObserver =
new MyProviderObserver
();provider.addObserver(providerObserver);while (outOfService )
{
Thread.sleep(500);}System.out.println ("Provider is now in
service");Address[] addresses =
provider.getAddresses();System.out.println ("Found "+
addresses.length +" addresses");for(int i=0; i<
addresses.length; i++){
System.out.println(addresses[i]);}provider.shutdown();
} catch (Exception e){}
}
Jtprefs ApplicationThe jtapi.ini file includes parameters that
are required for configuring Cisco Unified JTAPI. Cisco Unified
JTAPI looks for this file in a Java classpath. The parameters get
modified by using the Jtprefs application that Cisco Unified JTAPI
installs. The Jtprefs application sets only the parameters that it
requires. This proves beneficial because a single point of
application administration exists, independent of jtapi.ini.
The jtapi.ini file contains default values, but client
applications can modify values without having to specifically
modify the jtapi.ini file. Different instances of client
applications, however, can impose different settings for these
parameters. The com.cisco.jtapi.extensions package defines the
CiscoJtapiProperties interface.
Applications obtain a CiscoJtapiProperties object from the
CiscoJtapiPeer and make changes to the parameters by using the
accessor and mutator methods. These properties must get set and
applied to all providers that are derived from a CiscoJtapiPeer
prior to the first getProvider () call on that peer.
Applications that run in non GUI based platform, in which
jtprefs.ini cannot be invoked, can write a jtapi.ini file and place
it along with jtapi.jar.
1-3Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
See the following topics for more information:
Fields in the jtapi.ini File, page 4-19.
Sample jtapi.ini file with default values, page 4-24
Cisco Unified JTAPI ConceptsThis section describes the following
concepts:
CiscoObjectContainer Interface, page 1-4
JtapiPeer and Provider, page 1-4
Address and Terminal Relationships, page 1-6
Connections, page 1-7
Terminal Connections, page 1-8
Terminal and Address Restrictions, page 1-8
CiscoConnectionID, page 1-11
CiscoObjectContainer InterfaceThe CiscoObjectContainer interface
allows applications to associate an application-defined object to
objects that implement the interface. In Cisco Unified JTAPI, the
following interfaces extend the CiscoObjectContainer interface:
CiscoJTAPIPeer
CiscoProvider
CiscoCall
CiscoAddress
CiscoTerminal
CiscoConnection
CiscoTerminalConnection
CiscoConnectionID
CiscoCallID
JtapiPeer and ProviderThe 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 contains the entire collection
of call model objects, Addresses, Terminals, and Calls, which are
controllable at any time by an application.
The JTAPI Preferences (JTPREFS) application administers
JtapiPeer.getServices(), which returns server names.
The Provider entails two basic processes: initialization and
shutdown.
1-4Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
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 Unified Communications
Manager server
Login of the user who is administered in the directory
Password of the user that is specified
(Optional) Application information (This parameter may comprise
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 that are
concatenated in a string as follows:
JtapiPeer.getProvider(CTIManagerHostname;login=user;passwd=userpassword;appinfo=Cisco
Softphone)
Initialization
The JtapiPeer.getProvider() method returns a Provider object as
soon as the TCP link, the initial handshake with the Cisco Unified
Communications Manager, and the device list enumeration are
complete. The provider now exists in the OUT_OF_SERVICE state.
Cisco Unified 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.
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.
As a part of the QoS baselining effort in JTAPI,
ProviderOpenCompletedEv provides the DSCP value for Applications to
JTAPI. JTAPI sets this DSCP value for its connection with CTI, and
all JTAPI messages to CTI will have this DSCP value as long as the
Provider object exists.
Shutdown
When an application calls provider.shutdown(), JTAPI loses
communications permanently with the Cisco Unified Communications
Manager, 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.
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 Unified Communications Manager
Administration Guide to administer the user control list.
1-5Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
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.
Address and Terminal RelationshipsThe Cisco Unified
Communications system architecture includes three fundamental types
of endpoints:
Phones
Virtual devices (media termination points and route points)
Gateways
Of these endpoints, only phones and media termination points get
used by using the Cisco Unified JTAPI implementation.
Cisco Unified Communications Manager allows users to configure
phones to have one or more lines, dialable numbers, which multiple
phones may share simultaneously, or lines can be configured for
exclusive use by only one phone at a time. Each line on a phone 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 phones. Figure 1-2 shows two
configurations: Peter and Mary share one phone line, 5001, while
Paul has his own phone line, 5002.
1-6Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
Figure 1-2 Phone Diagram
A unique name identifies all types of Cisco Unified
Communications Manager endpoints. The phone Media Access Control
(MAC) address (such as, SEP0010EB1014) identifies it, and the
system administrator can assign any name to a media termination
point, so long as its name is unique.
For each endpoint that a provider controls, the Cisco Unified
JTAPI implementation uses the administrator-assigned 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-3 Address and Terminal Relationship
If two or more endpoints share a line (DN), the corresponding
address object relates to more than one terminal object.
Unobserved Addresses and Terminals
Cisco Unified JTAPI perceives calls only when a CallObserver
attaches to the terminals and 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.
Connections
Connections retain their references to calls and addresses
forever. So, you can always use a connection reference that is
obtained from a call event to obtain the connection call
(getCall()) and address (getAddress()).
5000
5001
"Peter"
5001
"Mary"
5002
"Paul"
3332
4
Addresses
Terminals
5000 5001 5002
"Peter" "Mary" "Paul" 3322
6
1-7Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
Terminal Connections
Terminal connections always retain their references to terminals
and connections. So, you can always use a terminal connection
reference that is obtained from a call event to obtain the terminal
connection terminal (getTerminal()) and connection
(getConnection()).
Terminal and Address Restrictions
Terminal and address restrictions prohibit applications from
controlling and monitoring a certain set of terminals and addresses
when the administrator configures them as restricted in Cisco
Unified Communications Manager Administration.
The administrator can configure a particular line on a device
(address on a particular terminal) as restricted. If a terminal is
added into the restricted list in Cisco Unified Communications
Manager Administration, all addresses on that terminal also get
marked as restricted in JTAPI. If an application comes up after the
configuration completes, it can perceive whether a particular
terminal or address is restricted from checking the interface
CiscoTerminal.isRestricted() and
CiscoAddress.isRestricted(Terminal). For shared lines, applications
can query the interface CiscoAddress.getRestrictedAddrTerminals(),
which indicates whether an address is restricted on any
terminals.
If a line (address on a terminal) is added into the restricted
list after an application comes up, the applications will perceive
CiscoAddrRestrictedEv. If the address has any observers,
applications will recognize CiscoAddrOutOfService. When a line is
removed from the restricted list, applications will perceive
CiscoAddrActivatedEv. If an address has any observers, applications
see CiscoAddrInServiceEv. If an application tries to add observers
on an address after it is restricted, a PlatformException gets
thrown. However, if any observers are added before the address is
restricted, they will remain as is, but applications cannot get any
events on these observers unless the address is removed from the
restricted list. Applications can also choose to remove observers
from an address.
If a device (terminal) is added to the restricted list after an
application comes up, the application will see
CiscoTermRestrictedEv. If the terminal has any observers, the
application will see CiscoTermOutOfService. If a terminal is added
to the restricted list, JTAPI also restricts all addresses that
belong to that terminal and applications will perceive
CiscoAddrRestrictedEv. If a terminal is removed from the restricted
list, applications will perceive CiscoTermActivatedEv and
CiscoAddrActivatedEv for the corresponding addresses. If an
application tries to add observers on a terminal after it is added
to the restricted list, a PlatformException is thrown. However, if
any observers are added before the terminal is restricted, they
will remain as is, but applications cannot get any events on these
observers unless the terminal is removed from the restricted
list
If a shared line is added to the restricted list after an
application comes up, the application will perceive
CiscoAddrRestrictedOnTerminalEv. If any address observers exist on
the address, the application will recognize CiscoAddrOutOfServiceEv
for that terminal. If all shared lines are added to the restricted
list, when the last one is added, applications will perceive
CiscoAddrRestrictedEv. If a shared line is removed from the
restricted list after the application comes up, applications will
perceive CiscoAddrActivatedOnTerminalEv. If any observers exist on
the address, the application will perceive CiscoAddrInServiceEv for
that terminal. If all shared lines in the control list are removed
from the restricted list, applications will recognize
CiscoAddrActivatedEv when the last one is removed, and all
addresses on terminals will receive InService events.
If all shared lines in the control list are marked as
restricted, and an application tries to add observers, a platform
exception gets thrown. If a few shared lines are in the restricted
list, while others are not, when an application adds an observer on
the address only nonrestricted lines will go in service.
If any active calls are present when an address or terminal is
added to the restricted list and reset, applications will recognize
connection and TerminalConnections get disconnected.
1-8Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
If no addresses or terminals are added to the restricted list,
this feature remains backward compatible with earlier versions of
JTAPI: no new events get delivered to applications.
The following sections describe the interface changes for
address and terminal restrictions.
CiscoTerminal
CiscoAddress
public interface CiscoRestrictedEv extends CiscoProvEv { public
static final int ID =
com.cisco.jtapi.CiscoEventID.CiscoRestrictedEv;
/** * The following define the cause codes for restricted events
*/
public final static int CAUSE_USER_RESTRICTED = 1;
public final static int CAUSE_UNSUPPORTED_PROTOCOL = 2;
}
This represents the base class for restricted events and defines
the cause codes for all restricted events. CAUSE_USER_RESTRICTED
indicates the terminal or address is marked as restricted.
CAUSE_UNSUPPORTED_PROTOCOL indicates that the device in the control
list is using a protocol that Cisco Unified JTAPI does not support.
Existing Cisco Unified IP 7960 and 7940 phones that are running SIP
fall in this category.
CiscoAddrRestrictedEv
Public interface CiscoAddrRestrictedEv extends
CiscoRestrictedEv. Applications will recognize this event when a
line or an associated device is designated as restricted from Cisco
Unified Communications Manager Administration. For restricted
lines, the address will go out of service and will not come back in
service until it is activated again. If an address is restricted,
addCallObserver and addObserver will throw an exception. For shared
lines, if a few shared lines are restricted, and others are not, no
exception
boolean isRestricted()
Indicates whether a terminal is restricted. If the terminal is
restricted, all associated addresses on this terminal also get
restricted. Returns true if the terminal is restricted; returns
false if it is not restricted.
javax.telephony. Terminal[]
getRestrictedAddrTerminals()
Returns an array of terminals on which this address is
restricted. If none are restricted, this method returns null.
In shared lines, a few lines on terminals may get restricted.
This method returns all the terminals on which this particular
address is restricted. Applications cannot perceive any call events
for restricted lines. If a restricted line is involved in a call
with any other control device, an external connection gets created
for the restricted line.
boolean isRestricted(javax.telephony.Terminal terminal)
Returns true if any address on this terminal is restricted.
Returns false if no addresses on this terminal are restricted.
1-9Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewCisco Unified JTAPI Concepts
gets thrown, but restricted shared lines will not receive any
events. If all shared lines are restricted, an exception gets
thrown when observers are added. If an address is restricted after
observers are added, applications will perceive
CiscoAddrOutOfServiceEv, and when the address is activated, the
address will go in service.
CiscoAddrActivatedEv
Public interface CiscoAddrActivatedEv extends CiscoProvEv.
Applications will perceive this event whenever a line or an
associated device is in the control list and is removed from the
restricted list in the Cisco Unified Communications Manager
Administration. If any observers exist on the address, applications
will perceive CiscoAddrInServiceEv. If no observers exist,
applications can try to add observers, and the address will go in
service.
CiscoAddrRestrictedOnTerminalEv
Public interface CiscoAddrRestrictedOnTerminalEv extends
CiscoRestrictedEv. If a user has a shared address in the control
list, and if one of the lines is added into the restricted list,
this event will get sent. Interface getTerminal() returns the
terminal on which the address is restricted. Interface getAddress()
returns the address that is restricted.
CiscoAddrActivatedOnTerminal
Public interface CiscoAddrActivatedOnTerminalEv extends
CiscoProvEv. When a shared line or a device that has a shared line
is removed from the restricted list, this event will get sent. The
interface getTerminal() returns the terminal that is being added to
the address. The interface getAddress() returns the address on
which the new terminal is added.
CiscoTermRestrictedEv
Public interface CiscoTermRestrictedEv extends
CiscoRestrictedEv. Applications will perceive this event when a
device is added into restricted list from Cisco Unified
Communications Manager Administration after the application
launches. Applications cannot perceive events for restricted
terminals or addresses on those terminals. If a terminal is
restricted when it is in InService state, applications will get
this event, and terminal and corresponding addresses will move to
the out-of-service state.
CiscoTermActivatedEv
Public interface CiscoTermActivatedEv extends
CiscoRestrictedEv.
javax.telephony.Address getAddress()
javax.telephony.Terminal getTerminal()
javax.telephony.Address getAddress()
javax.telephony.Terminal getTerminal()
javax.telephony.Terminal getTerminal()
Returns the terminal that is activated and is removed from the
restricted list.
1-10Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewThreaded Callbacks
CiscoOutOfServiceEv
CiscoCallEv
CiscoConnectionIDThe CiscoConnectionID object represents a
unique object that is associated with each connection in Cisco
Unified JTAPI. Applications may use the object itself or the
integer representation of the object.
Threaded CallbacksThe Cisco Unified 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 that are imposed by the JTAPI 1.2
specification, which cautions applications against using JTAPI
methods from within observer callbacks.
CiscoSynchronousObserver InterfaceThe Cisco Unified JTAPI
implementation allows applications to invoke blocking JTAPI
methods, such as Call.connect() and TerminalConnection.answer(),
from within observer callbacks. This means that applications do not
get subjected to the restrictions that the JTAPI 1.2 specification
imposes, which cautions against using JTAPI methods from within
observer callbacks. Applications can selectively disable the
queuing logic of the Cisco Unified 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 can selectively disable the queuing
logic of the Cisco Unified 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.
static int CAUSE_DEVICE_RESTRICTED
Indicates whether an event is sent because a device is
restricted.
static int CAUSE_LINE_RESTRICTED
Indicates whether an event is sent because a line is
restricted.
static int CAUSE_DEVICE_RESTRICTED
Indicates whether an event is sent because a device is
restricted.
static int CAUSE_LINE_RESTRICTED
Indicates whether an event is sent because a line is
restricted.
1-11Cisco Unified JTAPI Developers Guide for Cisco Unified
Communications Manager Release 7.1(2)
OL-18531-01
-
Chapter 1 OverviewAlarm Services
Note Objects that implement the CiscoSynchronousObserver
interface must not invoke blocking JTAPI methods from within their
event callbacks. The unpredictable consequences of doing so may
include deadlocking the JTAPI implementation. However, objects may
safely use the access or methods of any JTAPI object, for instance
Call.getConnections() or Connection.getState().
Querying Dynamic ObjectsBeware of querying dynamic objects such
as call objects. By the time you get an event, the object (such as,
call) may exist 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.
CiscoConsultCall
For the CiscoConsultCall interface, a reference to a consulting
terminal connection gets retained forever. For example, when a
CiscoConsultCallActive event is processed,
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 become valid
when callChangedEvent() is called. However, getConnections() may or
may not return the connections on these calls.
Alarm ServicesPart of the general serviceability framework for
Cisco Unified Communications 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