cisco unified jtapi developers guide for cisco unified ... · cisco unified communications manager...

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



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


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


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


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


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


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


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


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


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



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.


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.


OL-18531-01


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.


OL-18531-01


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.


OL-18531-01


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


OL-18531-01


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.


OL-18531-01


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.


OL-18531-01


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



Returns the terminal that is activated and is removed from the restricted list.


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.


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

cisco unified jtapi developers guide for cisco unified ... · cisco unified communications manager...

Documents