Cisco TAPI Developer Guide for Cisco CallManager 3.3(3)
Preface
Downloads: This chapterpdf (PDF - 263.0KB) | Feedback

Preface

Table Of Contents

Preface

Introduction

Purpose

Audience

New and Changed Information

CiscoTSP 3.3 Enhancements

Reporting TSP Initialization Problems or Errors to the Application

Changes From CiscoTSP 3.2 to CiscoTSP 3.3

User Deletion From Directory

Opening Two Lines on One CTI Port Device

CiscoTSP 3.2 Enhancements

Changes From CiscoTSP 3.1 to CiscoTSP 3.2

CiscoTSP 3.1 Enhancements

Changes From CiscoTSP 3.0 to CiscoTSP 3.1

Line In Service or Out of Service

LINE_CALLINFO

New or Changed CiscoTSP 3.1 Entities

Organization

Related Documentation

Required Software

Supported Windows Platforms

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 Telephony Application Programmer's Interface (TAPI) 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

Supported Windows Platforms

Conventions

Obtaining Documentation

Obtaining Technical Assistance

Obtaining Additional Publications and Information

Introduction

Telephony Application Programmer's Interface (TAPI) comprises the set of classes and principles of operation that constitute a telephony application programming interface. TAPI implementations provide the interface between computer telephony applications and telephony services. The Cisco CallManager includes a TAPI Service Provider (Cisco TSP). The Cisco TAPI Service Provider allows developers to create customized IP telephony applications for Cisco users; for example, voice mail with other TAPI compliant systems, automatic call distribution (ACD), and caller ID screen pops. Cisco TSP enables the Cisco IP Telephony system to understand commands from the user-level application such as Cisco SoftPhone via the operating system.

The Cisco TAPI implementation uses the Microsoft TAPI v2.1 specification and supplies extension functions to support Cisco IP Telephony Solutions. To enable a Cisco TAPI-based solution, you must have the following:

TAPI support/service running on the operating system

A TAPI-based software application

A Cisco IP Telephony phone system


Note Using Cisco TAPI 2.1 TSP via the TAPI 3.x compatibility layer is not supported.


Purpose

This document describes the Cisco TAPI implementation by detailing the functions that comprise the implementation software and illustrating how to use these functions to create applications that support the Cisco IP Telephony hardware, software, and processes. Use this document with the Cisco CallManager manuals to develop applications.

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

As new versions of Cisco CallManager and the Cisco TSP are released, variances in the API should be very minor, and should tend in the direction of compliance. Cisco stays 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

Audience

Cisco intends this document to be for use by telephony software engineers who are developing Cisco telephony applications that require TAPI. This document assumes that the engineer is familiar with both the C or C++ languages and the Microsoft TAPI specification.

New and Changed Information

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

CiscoTSP 3.3 Enhancements

The following CiscoTSP 3.3 enhancements for Cisco CallManager 3.3 exist:

Support for linePark and lineUnpark

Support for monitoring CallPark Directory Numbers using lineOpen

Support for Cisco IP Phones 7902, 7912, and 7935

Reporting TSP Initialization Problems or Errors to the Application

CiscoTSP now reports the initialization error code through the registry key that provide applications to better diagnose the initialization problems. The newly added registry key is HKEY_LOCAL_MACHINE\SOFTWARE\Cisco Systems, Inc.\Cisco TSP\Cisco TSP001\TSPInitializationErrorCode.


Note Each TSP instance (in case of multiple TSP installation) has its own TSPInitializationErrorCode in the respective registry key HKEY_LOCAL_MACHINE\SOFTWARE\cisco systems, Inc.\Cisco TSP\Cisco TSPXXX.


The following error codes get exposed to the user. The definitions are located in CiscoLineDevspecificmsg.h.

#define TSP_WILL_RECONNECT 0x80000000

This high bit gets set when TSP performs reconnection to configured CTIManagers. Usually when TSP initialization with CTI fails due to temporary failure reasons, such as CTI not initialized or request timeouts, TSP reconnects to CTI. In those situations, TSP returns 0 devices for the initial TSPI_ProviderEnumDevices request and enumerates the devices when connection to CTI is reestablished. After enumeration, TSP informs the devices to TAPI applications thru LINE_CREATE / PHONE_CREATE messages.

#define TSP_SUCCESS 0x00000000

#define TSPERR_INTERNAL 0x00000001

This error indicates some Internal TSP error occurred. Collect the appropriate TSP traces and send it to TSP developer support to further diagnose the issue.

#define TSPERR_CONNECT_TO_CTI_FAILED 0x00000002

This error indicates socket connection to CTIManager failed, either the service is not up and running on the server or configured CTIManager IPAddress is invalid or unreachable.

#define TSPERR_INIT_AUTHENTICATION_REQUEST_TIMEOUT 0x00000003

This error indicates username, password, and authentication request for CTI access timedout. TSP reconnects in this situation.

#define TSPERR_INIT_CTI_NOT_INITIALIZED 0x00000004

This error indicates CTI is not yet completely initialized so that TSP can reconnect within ReconnectInterval.

#define TSPERR_INIT_CTI_RESPONSE_TIMEOUT 0x00000005

This error indicates the request for initialization (providerOpen) timedout. User needs to configure or verify the settings for ProviderOpenCompletedTimeout, Synchronous message timeout, and CTI service parameter for Synchronous message timeout so that CTI gets more time to initialize the devices/lines and TSP can wait for some more time to get the successful response.

#define TSPERR_INIT_AUTHENTICATION_TEMPORARY_FAILED 0x00000006

This error indicates authentication failed temporarily. TSP reconnects to CTI within ReconnectInterval and can have a successful connection later.

#define TSPERR_INIT_AUTHENTICATION_FAILED 0x00000007

This error indicates authentication failure. User needs to verify the Username or Password. This is a permanent failure. If multiple CTIManagers are configured, TSP attempts to connect to the remaining CTIManagers.

#define TSPERR_INIT_CTI_USE_NOT_ALLOWED_FOR_USER 0x00000008

This error indicates CTI use for this user is not enabled thru CCMAdmin. This is a perament failure. If multiple CTIManagers are configured, TSP attempts to connect to remaining CTIManagers.

#define TSPERR_INIT_ILLEGAL_MESSAGE 0x00000009

This error indicates invalid message format (internal protocol error). TSP does not reconnect.

#define TSPERR_INIT_INCOMPATIBLE_PROTOCOL_VERSION 0x0000000a

This error indicates internal protocol error - as the QBE version mismatch. The TSP QBE protocol version does not match with the CTI protocol version, hence the initialization can not proceed. TSP does not reconnect.

#define TSPERR_UNKNOWN 0x00000010

This error indicates some internal unknown error. Do not report because this is the default case. Case is only when a new error is introduced in CTI-TSP QBE protocol and is not already mapped to new TSP error. Collect the appropriate TSP traces and send it to TSP developer support to further diagnose the issue.

Changes From CiscoTSP 3.2 to CiscoTSP 3.3

This section describes two important changes in CiscoTSP version 3.3:

A change in the way CiscoTSP behaves when the TSP user is deleted from the Cisco CallManager Directory

Changes that allow opening two lines on the same CTI port device

User Deletion From Directory

In previous releases, when the TSP user is removed from the Cisco CallManager directory, the TSP would place all the lines and phones OUTOFSERVICE/SUSPENDED indefinitely until the lines and phones are closed.

In CiscoTSP 3.3, when the TSP user is removed, the TSP now closes all the lines and phones and sends LINE_CLOSE/PHONE_CLOSE messages. After doing this, the TSP removes all the lines and phones and sends LINE_REMOVE/PHONE_REMOVE messages.

Opening Two Lines on One CTI Port Device

In previous releases, the CiscoTSP opened only one line at a time on CTI port devices that are configured with multiple lines.

In CiscoTSP 3.3, the TSP allows the simultaneous opening of all lines on the same CTI port device as long as the media parameters are matching for each lineOpen.

Media termination occurs two ways on CTI port devices:

Cisco Wave Drivers—The Cisco Wave Drivers set up the media parameters.

Media Termination Controlled by the Application—The application provides the media parameters.

CiscoTSP 3.3 allows applications to open all lines on the same CTI port device at the same time as long as all the lines are using the Cisco Wave Drivers or as long as all the lines are using custom media termination with the same media termination settings for each line.

CiscoTSP 3.2 Enhancements

The following CiscoTSP enhancements apply for 3.2:

Support for multiple languages in the CiscoTSP installation program and in the CiscoTSP configuration dialogs

Support for ATA186 devices

Changes From CiscoTSP 3.1 to CiscoTSP 3.2

Cisco TSP enhancements for 3.1 include CTI Manager and support for fault tolerance and using Cisco CallManager Extension Mobility.

CiscoTSP 3.1 Enhancements

The following Cisco TSP enhancements apply for 3.1:

CTI Manager and support for fault tolerance

Support for Cisco CallManager Extension Mobility

Support for Multiple CiscoTSP

Support for swap hold and setup transfer with the lineDevSpecific function

Support for lineForward

Support to Reset the Original Called Party upon Redirect with the lineDevSpecific function

Support for VG248 devices

Changes From CiscoTSP 3.0 to CiscoTSP 3.1

This section describes two important changes in CiscoTSP version 3.1: a change in the way CiscoTSP behaves when an application opens a line or phone and changes in the LINE_CALLINFO message.

Line In Service or Out of Service

In CiscoTSP 3.0, by default a line is in service when opened. With cluster abstraction (the CTI Manager) in CiscoTSP 3.1, after an application successfully opens a line or phone, the line or phone may be out of service. Immediately after opening the device, the application should check its status. If the device is out o service, the application should wait for an in-service message before initiating a TAPI request that results in Cisco CallManager interaction. If an application initiates such a request while the device is out of service, CiscoTSP responds with a resource unavailable message.

This change, from the behavior in CiscoTSP 3.0, will not be an issue for an application if the application checks the line or phone status immediately after the lineOpen or phoneOpen function call.

LINE_CALLINFO

A change added complete support for the fields of the LINE_CALLINFO message in CiscoTSP 3.1.

The LINE_CALLINFO parameter dwCalledID correctly reflects the OrigincalCalledParty information.

New or Changed CiscoTSP 3.1 Entities

Several Cisco TAPI device structures, functions, and messages that have been added or changed in this version enhance overall functionality. This table lists each new or modified entity and its type.

Entity
Type

LINE_ADDRESSSTATE

TAPI Line Message

LINE_REMOVE

TAPI Line Message

LINEADDRESSCAPS

TAPI Line Device Structure

LINEFORWARD

TAPI Line Device Structure

LINEFORWARDLIST

TAPI Line Device Structure

PHONE_REMOVE

TAPI Phone Message

lineForward

TAPI Line Function


Chapter
Description

Chapter 1 "Overview"

Outlines the key concepts for Cisco TAPI. Lists all functions available in the Cisco TAPI implementation for Cisco CallManager. Describes changes in and enhancements to Cisco TSP.

Chapter 2 "Cisco TAPI Implementation"

Describes the supported functions in the Cisco implementation of the standard Microsoft TAPI v2.1.

Chapter 3 "Cisco Device Specific Extensions"

Describes the functions that comprise the Cisco hardware-specific implementation classes.

Chapter 4 "Cisco TAPI Examples"

Provides examples that illustrate how to use the Cisco TAPI implementation.


Organization

Related Documentation

For more information about TAPI specifications, creating an application to use TAPI, or TAPI administration, see

Microsoft TAPI 2.1 Features:
http://www.microsoft.com/NTServer/commserv/exec/feature/tapi21.asp

Getting Started with Windows Telephony
http://www.microsoft.com/NTServer/commserv/deployment/planguides
/getstartedtele.asp

Windows Telephony API (TAPI)
http://www.microsoft.com/NTServer/commserv/exec/overview
/tapiabout.asp

Creating Next Generation Telephony Applications:
http://www.microsoft.com/NTServer/commserv/techdetails/prodarch
/tapi21wp.asp

The Microsoft Telephony Application Programming Interface (TAPI) Programmer's Reference

"For the Telephony API, Press 1; For Unimodem, Press 2; or Stay on the Line" —A paper on TAPI by Hiroo Umeno a COMM and TAPI specialist at Microsoft.

"TAPI 2.1 Microsoft TAPI Client Management"

"TAPI 2.1 Administration Tool"

Required Software

CiscoTSP requires the following software:

Cisco CallManager version 3.3(2) on the Cisco CallManager server

Microsoft Internet Explorer 4.01 or later

Supported Windows Platforms

All Windows operating systems support Cisco TAPI. Depending on the type and version of your operating system, you may need to install a service pack.

Windows 2000

Windows 2000 includes TAPI 2.1.

Windows XP

Windows XP includes TAPI 2.1.

Windows Me

Windows Me includes TAPI 2.1.

Windows NT Server 4.0 or Windows NT Workstation 4.0

Service Pack 5 (SP5) includes TAPI 2.1.

SP5 is available via download from Microsoft.

Windows 98

Windows 98 includes TAPI 2.1.

Windows 95

Microsoft provides TAPI 2.1.


Note Check %SystemRoot%\system32 for these dynamically loaded library (.dll) files
and versions:
msvcrt.dll version: 6.00.8397.0
msvcp60.dll version: 6.00.8168.0
mfc42.dll version: 6.00.8447.0


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

An unquoted 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 that 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 convention:


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 TAPI 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 TAPI 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 Products & Services page describes the networking products offered by Cisco Systems, as well as ordering and customer support services. Access the Cisco Products & Services page at this URL:

http://www.cisco.com/en/US/products/index.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

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