Table Of Contents

Preface

Introduction

Purpose

Audience

New and Changed Information

Cisco CallManager Release 3.3

Cisco CallManager Release 3.2

Cisco CallManager Release 3.1

Organization

Related Documentation

Required Software

Conventions

Obtaining Documentation

Cisco.com

Documentation CD-ROM

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Cisco.com

Developer Support

Technical Assistance Center

Cisco TAC Website

Cisco TAC Escalation Center

Obtaining Additional Publications and Information

Preface

---

This chapter introduces Cisco JTAPI implementation, describes the purpose of this document, and outlines the required software. The chapter includes the following topics:

•Introduction

•Purpose

•Audience

•New and Changed Information

•Organization

•Related Documentation

•Required Software

•Conventions

•Obtaining Documentation

•Obtaining Technical Assistance

•Obtaining Additional Publications and Information

Introduction

Java Telephony Application Programming Interface (JTAPI) acts as a portable, object-oriented API for computer telephony integrated call control. The package of JTAPI interfaces located in the javax.telephony.* hierarchy, defines a programming model by which Java applications interact with telephony resources such as PBXs and telephones. The Cisco JTAPI implementation supports Java application access to Cisco Architecture for Voice, Video and Integrated Data (AVVID) communication systems according to the JTAPI v 1.2 specification. Furthermore, Cisco JTAPI exposes Cisco-specific events and methods for certain telephony resources such as calls and connections.

Purpose

One of the primary goals of a standard Application Programming Interface (API) such as JTAPI is to provide an unchanging programming interface under which varied implementations may stand. Cisco's goal in implementing JTAPI for the Cisco CallManager platform is to conform as closely as possible to the JTAPI specification while providing extensions that enhance JTAPI and expose the advanced features of Cisco CallManager to applications.

As new versions of Cisco CallManager and the Cisco JTAPI implementation are released, variances in the API should be very minor and should tend in the direction of compliance. Cisco remains committed to maintaining its API extensions with the same stability and reliability, though additional extensions may be provided as new Cisco CallManager features become available.

This document outlines some basic JTAPI concepts including transfer and conference extensions. It also describes the support of extensions to the Sun JTAPI v 1.2 specification.

Audience

This document applies for telephony software developers who are developing Cisco IP Telephony applications that require JTAPI. This document assumes that the programmer is familiar with both the Java language and the Sun JTAPI v 1.2 specification.

New and Changed Information

This section describes any new features and or changes for Cisco JTAPI pertinent to the specified release of Cisco CallManager.

Cisco CallManager Release 3.3

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 3.3:

•CallParkRequest, CallParkResponse, and Parked DN Monitoring—Defines new extensions to allow applications to park a call or unpark a call.

•XSI Object Pass Through—Allows application to pass an XML object through a Cisco JTAPI or CTI interface to an IP phone.

•VG248 and ATA 186 Analog Phone Gateways—Supports control of analog phones that are connected to these gateways.

•Cisco JTAPI Installation Internationalization—Supports multiple languages for the Cisco JTAPI installation and the user preference user interface. Refer to the Cisco CallManager 3.3 JTAPI Installation Guide for more information.

•Enable or Disable Ringer—Supports application control of ringer settings for each address on a device.

•Clear Calls Interface—Provides a clearCallConnections interface that allows applications to remove phantom calls without removing the call observer.

•Display Name Interface—Extends the CiscoCall interface to provide methods to get name displays of the calling party and the called party in a call. Applications can use getCurrentCallingPartyDisplayName() to get the display name of the calling party.

•SetMessageWaiting Interface—Provides a method for applications to set the message waiting lamp or indicator for an address.

•Quite Clear—Provides QuiteClear at the other end when two parties are on a call and one address goes OutOfService because of a network outage, the Cisco CallManager goes down, application controlling CTIPort goes down, or CTIManager goes down.

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

•DeleteCall Interface—Provides applications with the ability to delete a call that was created using the createCall interface. This method accepts a call and throws an InvalidStateException if a provider is not in service or if the call is not in the IDLE state. DeleteCall moves the call to the INVALID state.

•GetGCID—Provides an interface on the CiscoCallID to get the nodeID and the GCID of the call, which exposes the GCID information that is available in the internal call object.

•GetCallID in RTP Events—Provides an interface on RTP events to access any call information, so applications can link RTP events with the calls.

Cisco CallManager Release 3.2

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 3.2:

•Call Park—Cisco JTAPI supports user interactions with Call Park and reports appropriate events to the applications.

•Super Provider—Supports static control of devices and the ability to query for devices.

•Separation of CTI client code—Supports checking for provider properties in an object that implements the CtiClientProperties, so application layers, other than Cisco JTAPI, cannot utilize the functions in the client code to talk to the CTI Manager.

•Reconnect Logic—Connects Cisco JTAPI applications to the secondary CTIManager after waiting for a random time, so all Cisco JTAPI applications do not connect to the secondary CTIManager at the same time.

Cisco CallManager Release 3.1

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 3.1:

•CTIManager component—Allows a JTAPI application to control devices on another Cisco CallManager in a cluster. It supports multiple Cisco CallManagers and CTI managers during failover and recovery and supports automatic device recovery during a failover.

•Directory Change Notification—Allows asynchronous directory change notification.

•Transfer and Conference Enhancement—Allows enhancements to Transferring & Conferencing.

•Call Forward Setting—Allows Cisco JTAPI implementation for supporting Call Forwarding.

•CiscoJtapiExceptions—Allows CiscoJtapiException handling modifications.

•Redirect—Allows a Cisco JTAPI Redirect request.

•Alarm Services—Allows Cisco JTAPI support for Alarm Services.

•Application Control of JTAPI Parameters—Allows control of the parameters within jtapi.ini.

•Dynamic Trace Enabling Using Jtprefs—Allows dynamic enabling of traces from the Jtprefs application.

Organization

The following table provides an outline of this document organization.

Chapter	Description
Chapter 1, "Overview"	This chapter introduces the major concepts with which you need to be familiar before creating JTAPI applications for Cisco IP Telephony Solutions.
Chapter 2, "Cisco JTAPI Implementation"	This chapter describes the interfaces and classes that are available.
Chapter 3, "JTAPI Examples"	This chapter provides the source code for makecall, which is the Cisco JTAPI program that is used to test the JTAPI installation.
Appendix A, "Cisco JTAPI Classes and Interfaces"	This appendix contains a listing of all the classes and interfaces that are available in the Cisco JTAPI implementation for Cisco CallManager.
Appendix B, "CTI Error Codes"	This appendix lists and describes CTI error codes.

Related Documentation

The companion document Cisco JTAPI Developer Reference (JTAPI v 1.2 Specification) contains the Sun JTAPI specification for the supported interfaces and classes and their respective methods. This document set includes the specification downloaded from the Sun JTAPI web site, as a convenience to Cisco JTAPI programmers. The writing style in that book conforms to the Sun specification; it does not conform to the Cisco writing style.

To obtain the very latest version of the JTAPI specification files, go directly to the web site at:

•The Sun Microsystems Inc. JTAPI v 1.2 specification
http://java.sun.com/products/jtapi/jtapi-1.2/packages.html

Required Software

The following table lists software requirements for the following applications: JTAPI applications, JTPREFS, and sample code.

.

Application	Required Software	Examples
JTAPI applications	Any JDK 1.1 compliant java environment	•Microsoft Internet Explorer 4.01 or later •Sun JDK 1.1, 1.2, or 1.3
JTPREFS	Microsoft Internet Explorer 4.01 or later
Sample code	Microsoft Internet Explorer 4.01 or later

Conventions

This document uses the following conventions:

Convention	Description
boldface font	Commands and keywords are in boldface.
italic font	Arguments for which you supply values are in italics.
[   ]	Elements in square brackets are optional.
{ x | y | z }	Alternative keywords are grouped in braces and separated by vertical bars.
[ x | y | z ]	Optional alternative keywords are grouped in brackets and separated by vertical bars.
string	A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.
screen font	Terminal sessions and information the system displays are in screen font.
boldface screen font	Information 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 Control—for example, the key combination ^D in a screen display means hold down the Control key while you press the D key.
<   >	Nonprinting characters, such as passwords are in angle brackets.

Notes use the following conventions:

---

Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the publication.

---

Obtaining Documentation

Cisco provides several ways to obtain documentation, technical assistance, and other technical resources. These sections explain how to obtain technical information from Cisco Systems.

Cisco.com

You can access the most current Cisco documentation on the World Wide Web at this URL:

http://www.cisco.com/univercd/home/home.htm

You can access the Cisco website at this URL:

http://www.cisco.com

International Cisco websites can be accessed from this URL:

http://www.cisco.com/public/countries_languages.shtml

Documentation CD-ROM

Cisco documentation and additional literature are available in a Cisco Documentation CD-ROM package, which may have shipped with your product. The Documentation CD-ROM is updated regularly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual or quarterly subscription.

Registered Cisco.com users can order a single Documentation CD-ROM (product number DOC-CONDOCCD=) through the Cisco Ordering tool:

http://www.cisco.com/en/US/partner/ordering/ordering_place_order_ordering_tool_launch.html

All users can order monthly or quarterly subscriptions through the online Subscription Store:

http://www.cisco.com/go/subscription

Ordering Documentation

You can find instructions for ordering documentation at this URL:

http://www.cisco.com/univercd/cc/td/doc/es_inpck/pdi.htm

You can order Cisco documentation in these ways:

•Registered Cisco.com users (Cisco direct customers) can order Cisco product documentation from the Networking Products MarketPlace:

http://www.cisco.com/en/US/partner/ordering/index.shtml

•Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco Systems Corporate Headquarters (California, U.S.A.) at 408 526-7208 or, elsewhere in North America, by calling 800 553-NETS (6387).

Documentation Feedback

You can submit comments electronically on Cisco.com. On the Cisco Documentation home page, click Feedback at the top of the page.

You can e-mail your comments to bug-doc@cisco.com.

You can submit comments by using the response card (if present) behind the front cover of your document or by writing to the following address:

Cisco Systems
Attn: Customer Document Ordering
170 West Tasman Drive
San Jose, CA 95134-9883

We appreciate your comments.

Obtaining Technical Assistance

Cisco provides Cisco.com, which includes the Cisco Technical Assistance Center (TAC) website, as a starting point for all technical assistance. Customers and partners can obtain online documentation, troubleshooting tips, and sample configurations from the Cisco TAC website. Cisco.com registered users have complete access to the technical support resources on the Cisco TAC website, including TAC tools and utilities.

Cisco.com

Cisco.com offers a suite of interactive, networked services that let you access Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.

Cisco.com provides a broad range of features and services to help you with these tasks:

•Streamline business processes and improve productivity

•Resolve technical issues with online support

•Download and test software packages

•Order Cisco learning materials and merchandise

•Register for online skill assessment, training, and certification programs

To obtain customized information and service, you can self-register on Cisco.com at this URL:

http://tools.cisco.com/RPF/register/register.do

Developer Support

The 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
www.cisco.com/go/developer support/.

Developers using the Cisco JTAPI Developer Guide for Cisco CallManager 3.3.(3) are encouraged to join the Cisco Developer Support Program. This new program provides a consistent level of support while leveraging Cisco interfaces in development projects.

---

Note Cisco Technical Assistance Center (TAC) support does not include Cisco JTAPI 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 developer-support@cisco.com.

---

Technical Assistance Center

The Cisco TAC is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two types of support are available: the Cisco TAC website and the Cisco TAC Escalation Center. The type of support that you choose depends on the priority of the problem and the conditions stated in service contracts, when applicable.

We categorize Cisco TAC inquiries according to urgency:

•Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration. There is little or no impact to your business operations.

•Priority level 3 (P3)—Operational performance of the network is impaired, but most business operations remain functional. You and Cisco are willing to commit resources during normal business hours to restore service to satisfactory levels.

•Priority level 2 (P2)—Operation of an existing network is severely degraded, or significant aspects of your business operations are negatively impacted by inadequate performance of Cisco products. You and Cisco will commit full-time resources during normal business hours to resolve the situation.

•Priority level 1 (P1)—An existing network is "down," or there is a critical impact to your business operations. You and Cisco will commit all necessary resources around the clock to resolve the situation.

Cisco TAC Website

The Cisco TAC website provides online documents and tools to help troubleshoot and resolve technical issues with Cisco products and technologies. To access the Cisco TAC website, go to this URL:

http://www.cisco.com/tac

All customers, partners, and resellers who have a valid Cisco service contract have complete access to the technical support resources on the Cisco TAC website. Some services on the Cisco TAC website require a Cisco.com login ID and password. If you have a valid service contract but do not have a login ID or password, go to this URL to register:

http://tools.cisco.com/RPF/register/register.do

If you are a Cisco.com registered user, and you cannot resolve your technical issues by using the Cisco TAC website, you can open a case online at this URL:

http://www.cisco.com/tac/caseopen

If you have Internet access, we recommend that you open P3 and P4 cases online so that you can fully describe the situation and attach any necessary files.

Cisco TAC Escalation Center

The Cisco TAC Escalation Center addresses priority level 1 or priority level 2 issues. These classifications are assigned when severe network degradation significantly impacts business operations. When you contact the TAC Escalation Center with a P1 or P2 problem, a Cisco TAC engineer automatically opens a case.

To obtain a directory of toll-free Cisco TAC telephone numbers for your country, go to this URL:

http://www.cisco.com/warp/public/687/Directory/DirTAC.shtml

Before calling, please check with your network operations center to determine the Cisco support services to which your company is entitled: for example, SMARTnet, SMARTnet Onsite, or Network Supported Accounts (NSA). When you call the center, please have available your service agreement number and your product serial number.

Obtaining Additional Publications and Information

Information about Cisco products, technologies, and network solutions is available from various online and printed sources.

•The Cisco Product Catalog describes the networking products offered by Cisco Systems, as well as ordering and customer support services. Access the Cisco Product Catalog at this URL:

http://www.cisco.com/en/US/products/products_catalog_links_launch.html

•Cisco Press publishes a wide range of networking publications. Cisco suggests these titles for new and experienced users: Internetworking Terms and Acronyms Dictionary, Internetworking Technology Handbook, Internetworking Troubleshooting Guide, and the Internetworking Design Guide. For current Cisco Press titles and other information, go to Cisco Press online at this URL:

http://www.ciscopress.com

•Packet magazine is the Cisco quarterly publication that provides the latest networking trends, technology breakthroughs, and Cisco products and solutions to help industry professionals get the most from their networking investment. Included are networking deployment and troubleshooting tips, configuration examples, customer case studies, tutorials and training, certification information, and links to numerous in-depth online resources. You can access Packet magazine at this URL:

http://www.cisco.com/go/packet

•iQ Magazine is the Cisco bimonthly publication that delivers the latest information about Internet business strategies for executives. You can access iQ Magazine at this URL:

http://www.cisco.com/go/iqmagazine

•Internet Protocol Journal is a quarterly journal published by Cisco Systems for engineering professionals involved in designing, developing, and operating public and private internets and intranets. You can access the Internet Protocol Journal at this URL:

http://www.cisco.com/en/US/about/ac123/ac147/about_cisco_the_internet_protocol_journal.html

•Training—Cisco offers world-class networking training. Current offerings in network training are listed at this URL:

http://www.cisco.com/en/US/learning/le31/learning_recommended_training_list.html