9 Cisco CallManager API Troubleshooting Guide TAPI Troubleshooting This chapter contains the following topics: • Overview, page 9 • Architecture, page 10 • Postinstallation Checklist, page 12 • Troubleshooting Tools, page 13 • Error Reporting, page 17 • Error and Status Codes, page 18 Overview TAPI Telephony Applications Programming Interface (TAPI) is part of the Microsoft Windows Open System Architecture and provides developers with the ability to create telephony applications. TAPI is: • An open industry standard • Defined with considerable and ongoing input from the worldwide telephony and computing community • Switch-fabric independent TAPI-compatible applications can run on a wide variety of PC and telephony hardware and can support a variety of network services. TAPI supports many telephony features, allowing developers to telephone-enable virtually any general- purpose application. TAPI also supports Unicode, making it easier to effect global applications. With Active Controls provided by a variety of vendors, corporate developers can put together telephony applications using tools they are already familiar with. For more information about TAPI refer to http://www.microsoft.com/ntserver/techresources/commnet/tele/tapi21.asp. TSP Telephony Service Provider (TSP) is a dynamic-link library (DLL) that provides device-specific controls for communications processing. TSP provides an abstraction layer between TAPI applications and the underlying hardware and transport protocols.
Transcript
tem
pport
eral-ith
y
rolsd the
TAPI Troubleshooting
This chapter contains the following topics:
• Overview, page 9
• Architecture, page 10
• Postinstallation Checklist, page 12
• Troubleshooting Tools, page 13
• Error Reporting, page 17
• Error and Status Codes, page 18
OverviewTAPI
Telephony Applications Programming Interface (TAPI) is part of the Microsoft Windows Open SysArchitecture and provides developers with the ability to create telephony applications.
TAPI is:
• An open industry standard
• Defined with considerable and ongoing input from the worldwide telephony and computingcommunity
• Switch-fabric independent
TAPI-compatible applications can run on a wide variety of PC and telephony hardware and can sua variety of network services.
TAPI supports many telephony features, allowing developers to telephone-enable virtually any genpurpose application. TAPI also supports Unicode, making it easier to effect global applications. WActive Controls provided by a variety of vendors, corporate developers can put together telephonapplications using tools they are already familiar with.
For more information about TAPI refer tohttp://www.microsoft.com/ntserver/techresources/commnet/tele/tapi21.asp.
TSP
Telephony Service Provider (TSP) is a dynamic-link library (DLL) that provides device-specific contfor communications processing. TSP provides an abstraction layer between TAPI applications anunderlying hardware and transport protocols.
9Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingArchitecture
sing
. In
ArchitectureTAPI applications reside in their own process space and communicate with Tapi32.dll or Tapi3.dll uTAPI. SeeFigure 1.
Note Tapi32.dll and Tapi3.dll are DLLs provided by Microsoft.
Figure 1 Telephony Application PC
Tapi32.dll and Tapi3.dll communicate with the TAPISRV process using a private RPC interface.TAPISRV is a Microsoft process. In Windows 95, 98, and NT, this process is names TAPISRV.EXEWindows 2000, this process runs under the SVCHOST.EXE process. SeeFigure 2.
Figure 2 Telephony Application PC
1030
89
TAPIApp.exe
Tapi32.dll/Tapi3.dll
Tapi
1030
90
TAPIApp.exe
TAPISRV
Tapi32.dll/Tapi3.dll
Tapi
Private RPC Interface
10Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingArchitecture
P isSee
tary
TAPISRV communicates with the TSP using a Microsoft-defined interface known as TSPI. The TSa DLL that is dynamically linked to the TAPISRV process. Each PBX vendor provides its own TSP.Figure 3.
Figure 3 Telephony Application PC
The TSP communicates with the underlying telephony hardware, such as a PBX, using a proprieinterface. The telephony hardware may be on the same PC or on a different PC. SeeFigure 4.
Figure 4 Telephony Application PC
1030
91
TAPIApp.exe
TAPISRV Tsp.tsp
Tapi32.dll/Tapi3.dll
Tapi
TSPI
Private RPC Interface
1030
92
TAPIApp.exe
TAPISRV Tsp.tsp
Tapi32.dll/Tapi3.dll
Tapi
Telephony Application PC
Hardware (PBX)Proprietary Interface
TSPI
Private RPC Interface
11Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingPostinstallation Checklist
ing ahony
per
ines.
me and
Cisco provides a TSP called CiscoTSP. CiscoTSP communicates with the Cisco CallManager usproprietary interface known as CTIQBE. CiscoTSP allows customers to create customized IP telepapplications for the Cisco CallManager. SeeFigure 5.
Figure 5 Telephony Application PC
Postinstallation ChecklistSome problems may be the result of improper installation. Use the following checklist to verify proinstallation before proceeding with the troubleshooting process:
____ Check that the CTI Manager Location is configured properly.
____ Check to see if the CTI Manager is up and running.
____ Check to see that the network connection is up between the TSP and CTI Manager mach
____ Check to see if the Cisco CallManager DC Directory Service is up and running.
____ Check that the Username and Password that is configured in the TSP matches the UsernaPassword in the Cisco CallManager Directory.
____ Make sure that the Enable CTI Application Use flag has been checked in the DirectoryAdministration on the Cisco CallManager for the TSP user.
1030
93
TAPIApp.exe
TAPISRV
CTI Manager Service
Call manager server PC
Skinnystation
protocol(TCP)
Stations
RTP "Packet Bus"
CiscoTsp.tsp
Tapi32.dll/Tapi3.dll
Tapi
Telephony Application PC
CTIOBE overTCP/IP
TSPI
Private RPC Interface
12Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingTroubleshooting Tools
r
n be
er
fromPI
r of
____ Check that devices have been properly associated with the user in the Cisco CallManageDirectory.
____ Check to see if the CTI Connection Limit has been reached.
____ For non-SoftPhone machines, ensure the Cisco Wave Drivers have been installed.
____ Use the tools in“Troubleshooting Tools” on page 13 to verify the TSP is working properly.
____ Ensure the CiscoTSP version is compatible with the version of Cisco CallManager. This caverified by checking the Cisco CallManager Compatibility Matrix. Refer to theDefaul Loadssection on the Cisco Connection Online website athttp://www.cisco.com/univercd/cc/td/doc/product/voice/c_callmg/ccmcomp.htm#MinimumVsions
Troubleshooting ToolsThis section describes available troubleshooting tools.
TAPI BrowserThe TAPI Browser does not come standard with the Window operating system. It can be obtainedthe Microsoft MSDN website. The TAPI Browser can be used to initialize TAPI. Its main use is by TAdevelopers to test their TAPI implementation and to verify that the TSP is operational. SeeFigure 6.
To do this, bring up the TAPI Browser (TB20.exe), then double-clicklineInitializeEx in the leftmostwindow. If num line devs returns the expected number of the line device, the TSP is operational.LineInitializeEx initializes all lines of every configured TSP, not just the Cisco TSP. So, the numbenum line devices is equal to all lines of every configured TSP.
Figure 6 TAPI Browser
13Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingTroubleshooting Tools
aler.cate
e
y that
TAPI Phone DialerAnother way to verify that the TSP is installed and configured properly is to use the TAPI Phone DiThe TAPI Phone Dialer is found on all of the Windows operating systems. You can do a Find to lothe file (dialer.exe).
The TAPI Phone Dialer is the same on Window 95/98/NT, but was changed in Windows 2000.
Windows 95/98/NT
For Windows 95/98/NT, start thedialer.exe program. If this is the first time Dialer has been used, thdialog box shown inFigure 7 is displayed. If not, you need to clickTools andSelect Connect Using.
Figure 7 Windows 95/98/NT TAPI Phone Dialer
In theConnect Using dialog box, select aCisco Line. If there are no Cisco Lines in the line selectionbox, this indicates a connection problem between the Cisco TSP and the Cisco CallManager. Verifall items in the“Postinstallation Checklist” on page 12are correct. For theAddressselection box, selectAddress 0. ClickOK to continue.
Now type a number to dial. SeeFigure 8. If the phone call goes through, you know the Cisco TSP isoperational.
14Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingTroubleshooting Tools
ialerSP,ses.
Figure 8 Phone Dialer II
Windows 2000
The Phone Dialer for Windows 2000 is shown inFigure 9. It works like the Phone Dialer in Windows95/98/NT, but is a little fancier because it is a TAPI 3.0 application. From theEdit menu, selectOptionsto select the line you want to control.
Note The Cisco TSP is written as a TAPI 2.1 provider; however, in Windows 2000 and higher, Phone Duses the TAPI 3.0 API layer. While TAPI 3.0 applications are not officially supported by the Cisco TTAPI 3.0 versions of Phone Dialer should still work as described below for troubleshooting purpo
Figure 9 Windows 2000 TAPI Phone Dialer
15Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingTroubleshooting Tools
ae
nd
In the Lines tab, selectPhone as thePreferred Line For Calling. SeeFigure 10. In thePhone Callsselection bod, selectCisco Line. If there are no Cisco Lines in the line selection box, this indicates connection problem between the Cisco TSP and the Cisco CallManager. Verify that all items in th“Postinstallation Checklist” on page 12 are correct. ClickOK for the settings to take effect.
Figure 10 Windows 2000 TAPI Phone Dialer II
Next, clickDial and the dialog box inFigure 11 appears. Type the phone number you want to call aclick Place Call. If the call goes through, the Cisco TSP is working properly.
Figure 11 Windows 2000 TAPI Phone Dialer III
16Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingError Reporting
Error Reporting
Tracing for the TAPI Service ProviderPerform the following steps to initiate tracing for the TAPI Service Provider:
1. Go toStart->Settings->Control Panel and selectPhone and Modem Options.
2. Go toAdvanced tab. SelectCiscoTSP0XX and clickConfigure.
3. Go toTrace tab. SelectTrace On check box (seeFigure 12) and select the following:
Note It is recommended that all trace types be enabled when troubleshooting.
a. TSP Traceto trace the TSP internal messages. SelectError to just log errors in the TSP. SelectDetailed to log internal messages for debugging purposes.
b. CTI Trace to trace the messages sent between CTI and TSP
c. TSPI Trace to trace the requests and events sent between TSP and TAPI
17Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingError and Status Codes
the
orc
ene
Figure 12 TAPI Service Provider Trace
The following definitions apply:
Error and Status CodesTAPI error codes are reported within the TSP traces, as configured in“Tracing for the TAPI ServiceProvider” on page 17. Analysis of TSP trace logs is complex and error codes should be referred toapplication developer support staff.
The following errors are normal operational warnings and can be safely ignored:
• CiscoTSP001.tsp| CSelsiusTSPLine::CallAsyncResponse() asyncResponseID=0x0000DCE1*ERROR* Did not find call id 0x02044E99
Term Definition
Directory The path for the trace log. For example, c:\Temp.
No. of Files Set this to a value greater than or equal to 1 enables rolling log files. Fexample, a value of 10 will cause up to 10 log files to be used in a cyclifashion.
Max lines/files Specifies the maximum number of trace statements that will be writtto each log file. For example, a value of 1000 will cause up to 1000 tracstatements to be written to each log file.
18Cisco CallManager API Troubleshooting Guide
TAPI TroubleshootingError and Status Codes
Pslosedll id.
lyctualbjects
number
This message is a normal message that results from an optimization in the TSP, whereby TSexecution is not blocked while waiting for a call tear-down confirmation from the CTI (this alwaysucceeds). When the CTI does later return a message indicating successful tear-down of a ccall, the internal TSP call object may have already been destroyed, resulting in a “not found” ca
• CiscoTSP001.tsp| CCtiInterface::ProcessResponse() *ERROR* Response does not map toan existing request
Another similar optimization as above. When an application closes a call, the TSP immediategenerates failure replies for any outstanding asynchronous requests on the call. When the aCTI responses for these pending requests arrive at the TSP later, their corresponding request omay have already been destroyed and this line gets logged to the trace file.
• CiscoTSP001.tsp| CCtiInterface::RemoveFromSequenceNumberMap() *ERROR* Map entry doesnot exists for sequenceNumber(0x0000DD33)
Certain clean-up sequences in the TSP can result in attempting to remove a sequence map from the internal request table more than once. This is a normal occurrence resulting frommulti-threading issues and does not indicate a problem.
