Cisco TAPI Developer Guide for Cisco CallManager 3.3(2), TAPI version 2.1
Preface
Downloads: This chapterpdf (PDF - 246.0KB) The complete bookPDF (PDF - 2.14MB) | Feedback

Preface

Table Of Contents

Preface

Introduction

Purpose

Audience

New and Changed Information

CiscoTSP 3.3 Enhancements

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

World Wide Web

Documentation CD-ROM

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Cisco.com

Technical Assistance Center

Cisco TAC Web Site

Cisco TAC Escalation Center


Preface


This chapter introduces Cisco Telephony Application Programmer's Interface (TAPI) implementation, describes the purpose of this document, and outlines the required software. The following topics are included:

Introduction

Purpose

Audience

New and Changed Information

Organization

Related Documentation

Required Software

Conventions

Obtaining Documentation

Obtaining Technical Assistance

Introduction

Telephony Application Programmer's Interface (TAPI) is the set of classes and principles of operation that constitute a telephony application programming interface. TAPI implementations are 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, three things are essential:

TAPI support/service running on the operating system

A TAPI-based software application

A Cisco IP Telephony phone system

Purpose

This document describes the Cisco TAPI implementation, 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. This manual is meant to be used with the Cisco CallManager manuals to develop applications.

One of the primary goals of a standard Application Programming Interface (API) such as TAPI is to provide an unchanging programming interface under which varied implementations may stand. Cisco's goal in implementing TAPI for the Cisco CallManager platform is 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 is 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

This document is intended for 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 pertinent to the specified release of Cisco CallManager.

CiscoTSP 3.3 Enhancements

CiscoTSP 3.3 enhancements for Cisco CallManager 3.3 include the following:

Support for linePark and lineUnpark

Support for monitoring CallPark Directory Numbers using lineOpen

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 of 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 of the lines and phones and sends LINE_CLOSE/PHONE_CLOSE messages. After doing this, the TSP removes all of the lines and phones and sends LINE_REMOVE/PHONE_REMOVE messages.

Opening Two Lines on One CTI Port Device

In previous releases, the CiscoTSP was restricted to opening 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.

There are two ways for media termination on CTI port devices:

Cisco Wave Drivers—the media parameters are set up by the Cisco Wave Drivers.

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 of the lines are using the Cisco Wave Drivers or as long as all of the lines are using custom media termination with the same media termination settings for each line.

CiscoTSP 3.2 Enhancements

CiscoTSP enhancements for 3.2 include the following:

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

Cisco TSP enhancements for 3.1 include the following:

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-of-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 is a change from the behavior in CiscoTSP 3.0. In CiscoTSP 3.0, when a device was successfully opened, it was always in-service.

This change 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

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 have been added or changed in this version to enhance overall functionality. This table lists each new or modified entity and its type.

Table 0-1 New or changed Cisco TAPI Structures, Functions and Messages

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 the 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

The following software is required for CiscoTSP:

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

Microsoft Internet Explorer 4.01 or later

Supported Windows Platforms

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

Windows 2000

TAPI 2.1 is included with Windows 2000.

Windows XP

TAPI 2.1 is included with Windows XP.

Windows Me

TAPI 2.1 is included with Windows Me.

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

TAPI 2.1 is included with Windows 98.

Windows 95

TAPI 2.1 is provided by Microsoft.


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

These sections explain how to obtain documentation from Cisco Systems.

World Wide Web

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

http://www.cisco.com

Translated documentation is available at 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 is shipped with your product. The Documentation CD-ROM is updated monthly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual subscription.

Ordering Documentation

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/cgi-bin/order/order_root.pl

Registered Cisco.com users can order the Documentation CD-ROM through the online Subscription Store:

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

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. In the Cisco Documentation home page, click the Fax or Email option in the "Leave Feedback" section at the bottom of the page.

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

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

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

We appreciate your comments.

Obtaining Technical Assistance

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

Cisco.com

Cisco.com is the foundation of a suite of interactive, networked services that provides immediate, open access to Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.

Cisco.com is a highly integrated Internet application and a powerful, easy-to-use tool that 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

If you want to obtain customized information and service, you can self-register on Cisco.com. To access Cisco.com, go to this URL:

http://www.cisco.com

Technical Assistance Center

The Cisco Technical Assistance Center (TAC) is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two levels of support are available: the Cisco TAC Web Site and the Cisco TAC Escalation Center.

Cisco TAC inquiries are categorized according to the urgency of the issue:

Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration.

Priority level 3 (P3)—Your network performance is degraded. Network functionality is noticeably impaired, but most business operations continue.

Priority level 2 (P2)—Your production network is severely degraded, affecting significant aspects of business operations. No workaround is available.

Priority level 1 (P1)—Your production network is down, and a critical impact to business operations will occur if service is not restored quickly. No workaround is available.

The Cisco TAC resource that you choose is based on the priority of the problem and the conditions of service contracts, when applicable.

Cisco TAC Web Site

You can use the Cisco TAC Web Site to resolve P3 and P4 issues yourself, saving both cost and time. The site provides around-the-clock access to online tools, knowledge bases, and software. To access the Cisco TAC Web Site, 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 Web Site. The Cisco TAC Web Site requires 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://www.cisco.com/register/

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

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

If you have Internet access, we recommend that you open P3 and P4 cases through the Cisco TAC Web Site.

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 level of 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.