Reference7:Unified Win32 and x64 TAPI Service Provider

The PBX supports a TAPI interface (also known as TSP Tapi Service Provider). From firmware version 7 on, there is an enhanced implementation of the service provider available.

This article describes how to install and use it as well how to configure the PBX in order for the TSP to work properly.

Applies To

This information applies to

• Unified Win32 and x64 innovaphone PBX V7.0 based TAPI Service Provider, Build 7512 and later
• innovaphone PBX, Build 08-7030000 and later

More Information

Overview

The unified TAPI Win32 and x64 TAPI Service Provider (TSP) is supposed to be functionally identical to the previous Win32-only TAPI Service Provider . However, it has been ported to the x64 Windows platforms. Also, the installer has been modified to comply with enhanced security requirements set forth in more recent Windows versions such as Vista, Server 2008 and Windows7.

The previous Win32-only TSP is deprecated. You should use this TAPI Service Provider whenever possible (see below).

System Requirements

The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use the previous TSP version . For systems running PBX firmware version 6 or earlier, you must use the even older version 5 based TSP . Note that there is no x64 version of the version 5 TSP!

Download

The V7 TSP will be available on the apps section of the V7 download page.

Installation

Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (setup64-release.msi) and the Win32 installer (setup32-release.msi.

The release setup packages provided will install the retail version. This is recommend for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based application is to be run. If for example, Outlook is to be used, then each client PC running Outlook may have the TSP installed. Although this is typical for a 1st party configuration, all clients may have full 3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a 3rd party TAPI server product (such as the IXI-Call Server available as a separate product) may be used to provide the network clients with a TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,

• select and download the setup32-release.msi install packages on 32bit platforms or the setup64-release.msi install package on 64bit platforms.
• double-click the install package to launch the installer
• accept the license agreement
• select the target folder
• complete the installer

When the installer has copied all files to the target machine, you need to add the TSP to the machine's TAPI system

• open the Telephone and Modem control panel
• Switch to the rightmost tab (Extras)
• Click on the Add... button
• Select the innovaphone TAPI provider driver
• Fill out the configuration dialogue
• Install the provider by clicking OK

File Organization

Windows forces all TAPI service provider files to reside in Windows' System Folder. This is the system32 folder in your windows install directory (usually C:\windows\system32, even if you are running an x64 platform! The installer will thus copy these files (tsp7-64.tsp and tsp7-64UI.dll) in to this directory. All other files however will be copied to the innovaphone AG\innovaphone® PBX V7-64-Win32 TSP or innovaphone AG\innovaphone® PBX V7-64-x642 TSP (depending on your platform) folder underneath your systems Program Files Folder.

The subdirectories Debug and Logs are created. code>Debug contains the driver's debug version, code>Logs will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (tsp7-64UI.dll) will be installed to the windows Windows on Windows64 System Folder (SysWOW64).

Installing the Debug Version

To install the debug version, you first install the retail version as outlined above. You them copy the debug driver files from the Debug directory to your windows system directory system32. You may want to use the shortcut to the Debug folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows

• close Telephony and Modem Control Panel if you have it open
• shut down windows telephony service. This can be done from the Windows Service Control Panel or by invoking net stop tapisrv from a command prompt
• copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as Windows File Explorer for (explorer.exe) for this. Windows will silently redirect any 32bit application to the SysWOW64 when accessing system32

When you open Telephony and Modem Control Panel again, you should notice that the TSP driver name has changed to the debug version.

When a debug driver is used, log files will be written to the Logs directory. Please note that such log files can grow considerably over time and can thus easily consume all available space on your boot drive. This may even result in an inability to boot the system!

To avoid this, you can

• delete older log files regularly (they are re-created on an hourly basis)
• turn on compression on the Logs folder which saves a fair amount of disk space

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers. You will want to re-install the retail drivers again when you have finished debugging the system

Switching back to the Retail Version

To go back from the debug to the release version, proceed as follows:

• close Telephony and Modem Control Panel if you have it open
• shut down windows telephony service. This can be done from the Windows Service Control Panel or by invoking net stop tapisrv from a command prompt
• delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as Windows File Explorer for (explorer.exe) for this. Windows will silently redirect any 32bit application to the SysWOW64 when accessing system32
• repair the installation using windows Programs Control Panel or by invoking the original .msi again

There is no need to remove the driver from the Telephone and Modem Control Panel, as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

Upgrading to a newer Version

When you attempt to upgrade the TSP from a previous version, the Windows installer will first remove any previous installation. When the new software is installed then, the TSP will be installed again into the TAPI system.

There is no need to remove the driver from the Telephone and Modem Control Panel, as this would make you loose your driver configuration.

Uninstalling the TSP

To uninstall the TSP proceed as follows

• Remove the TAPI driver from the TAPI system using Telephony and Modem Control Panel
• close Telephony and Modem Control Panel
• shut down windows telephony service. This can be done from the Windows Service Control Panel or by invoking net stop tapisrv from a command prompt
• remove the installation using windows Programs Control Panel or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the Windows System Directory. To clean up remove tsp7-64.tsp and tsp7-64UI.dll from the system32 folder as well as - on x64 systems - from the SysWOW64 folder.

Also, if you did run the debug driver, any remaining debug files in the Logs folder are left over and need to be removed manually.

Configuration

The TSP configuration dialog looks like this:

PBX - Master	The IP address or host name of the device the PBX is installed on
PBX - Standby	The IP address or host name of the device the PBX's standby is installed on. If there is no standby, leave this field empty. Do not enter any slave PBX here
PBX - Account	The PBX account name
PBX - Password	The accounts password
PBX - Use non-standard port	Tick this if your gateways http Server runs on a non-standard http port.
PBX - Use HTTPS	Tick this if you want to encrypt the PBX - TSP communication (recommended)
TAPI User - Username	Provide the Name of the PBX user the TSP shall work on behalf of
TAPI Line Names	The TSP will create a TAPI line device for each PBX user it sees. You can specify a template for the TAPI device name generated for each line. You can either choose one of the 3 pre-defined templates or create your own template (tick Use specified template and type your template into the template edit field)
Use pure node extensions	Tick this if the TSP shall report the pure intra-node extension as line address. Normally, the TSP would report the extension prefixed with the objects node number (and all node prefixes up to the root node).
Do not monitor slaves	Tick this if you don't want the TSP to monitor slave PBXs. This re-instates the V5 service provider behavior, except that standby PXS will be tracked anyway.

The TAPI device name will be generated by substituting the following meta strings in the template

Meta	Replacement
%c	The objects Long name (cn)
%d	The objects display name (dn)
%h	The objects Name (h323 alias)
%e	The objects extension (e164)
%E	The objects extension (e164) prefixed with the objects node number
%N	The line address as reported to TAPI
%n	host name (of master pbx)
%p	:port-number (of master pbx's http access, empty if 80)
%P	raw port number of master pbx
%u	url-like user name (user@host)
%U	user url as per draft-levin-iptel-h323-url-scheme-04 (h323:://user@host:port)
%X	the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
%x	the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users PBX attribute changes)

In a 1st party configuration, where the TSP is installed on a PC on behalf of the PC’s user, you will typically use the users PBX name as Username. In this case, you may use the users PBX name as Account and provide the users PBX password. Note that in this case, the user must have a password defined in the PBX. In this scenario, configure the TSP to work with the PBX the user is known on. If it is a fully replicated scenario, you can use the master PBX. Otherwise use the PBX the user is defined on.

In a 3rd party configuration, where the TSP is installed on a server acting on behalf of all network users, you will probably use a special PBX user account which is an active member of a group in which all PBX users which shall be seen by TAPI are members. You may for example create an otherwise unused PBX user _TAPI_ for this.

You may use the users Name as Account and its Long Name as Username. This users PBX password will be used as Password. Note that if you use a PBX user account as recommended, the user needs to have at least Group/Call Forwards rights.

In any case, the TSP will connect to the configured (master) PBX as well as to all slaves and/or standbys seen by TAPI using the configured credentials (PBX - Account and PBX - Password). The configured account needs to be present thus in all these PBXs. In a fully replicated scenario, this is best done by leaving the PBX field of that user in the PBX user configuration empty. This will result in a replication of all the user data (including the password) to all PBXs.

To make sure TAPI sees all slaves, you need to include their node objects into the group monitored by TAPI (that is, the group _TAPI_ user is an active member of).

Please note that there currently is a limitation to 2000 users being in all active groups of a particular user. Thus, you cannot configure more than 2000 users to be handled by TAPI on a single PBX. This is a PBX limitation (and applies for all PBX groups).

The VERIFY button will verify the configuration. Note that the Username drop down list will only be populated after a successful verify.

The OK button will save the configuration.

The CANCEL button will quit the configuration without saving any changes. If it is the initial configuration during the installation, the TSP will not be added and the software will not be installed.

When the configuration is OK you can configure the line to use in the TAPI application you intend to use.

Here is a screenshot of the respective Outlook configuration:

TBD

Working with multiple, unrelated PBXs

In a vanilla multi-node system, the TSP needs to know the masters and the (optional) stand-bys IP address only. The slaves are detected and connected automatically. This is done by analysis of the registration status of node objects in all PBXs.

When working with multiple, unrelated PBXs (that is, PBXs that do not form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status though. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit.

To find and edit the right registry entries, proceed as follows:

• open the key HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V7 TSP
• take note of the installedProvider entry (you will need the decimal value)
• open the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7 TAPI Service Provider
• open its subkey Devicen where n is the decimal value of installedProvider
• Open the FQDN key and add all extra PBXs
• For those PBXs that have a standby PBX, add a value to the StandbyFQDN key (please note: these are parallel lists. So if master and standby need to have the same respective index in the FQDN and StandbyFQDN value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values.

User Configuration

There is no special requirement regarding the PBX user configuration for the use of TAPI. Be aware though that a user that is not active in any group, will see only itself and thus only the TAPI line device which represents himself. To see the status of more PBX users, put the user as an active member into one or more groups.

The TSP is a PBX SOAP API based application. As such, the scope of what the TAPI sees in terms of users follows the rules imposed by the PBX. The TSP will issue exactly one Initialize call for the user configured as PBX ACCESS USERNAME. It will then issue a UserInitialize for each user. This is done on each PBX (master and slave/standbys).

Selective Call Forwards

The TSP supports the lineForward TAPI method and it supports some of the LINEFORWARDMODE_ constants. The EXTERNAL or INTERNAL modes (such as e.g. LINEFORWARDMODE_UNCONDEXTERNAL, are implemented by implicitly an Only or Only Not tag to the PBX forward settings . In order to successfully use one of those, the TSP thus needs to know the number of the trunk line object. The trunk line thus needs to be a member of the TAPI group.

In your TAPI application, these modes will be called something like call forward external or call forward internal. respectively.

References

The test applications provided with this setup comes from Julmar Technology Inc.

Limitations

The current implementation will track slave PBXs coming and going and updating call and user status accordingly. Also, standby PBXs will be tracked correctly (that is, the TSP will switch over between the PBX and its standby as required).

TAPI has a flat line model. That is, all line numbers (aka extensions) are considered to live in a single name space. As a result, lines with identical numbers cannot be distinguished in TAPI (although they can exist). All extensions in all nodes of a PBX numbering tree are represented as TAPI lines. When the TSP works with a PXB that implements a hierarchical numbering tree, then some lines may receive identical numbers (their node-local extension which may overlap between nodes). When a TAPI application uses these numbers to initiate calls to such lines, the call will work or not work depending on the calling lines position in the numbering tree (that is, lines within the same node as the called line will be fine, others may fail).

Known Problems

• The TSP doesn’t seem to run under Microsoft’s Remote Tapi Server. While some installation have reported this to work fine, others have encountered problems. This scenario is not supported by innovaphone.

• The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect.

• The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS.

• TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V7 TSP\lineGUIDs) that maps the PBX's line GUID to a fixed integer value (known as permanent line id in TAPI speak). When a user previously seen by TAPI is removed from the PBX or moved out of the TAPI driver's scope, or the PBX that reported the user is off line, it will show up in TAPI as a defunct line (old-name). To get rid of these lines, remove their corresponding registry entry.

Tweaks

There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

Keys under HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V7 TSP

DoTraceFile

REG_DWORD. A debug TSP will write log files by default. Setting DoTraceFile to 0 will disable this. No effect in standard build.

ProcessorMask

REG_DWORD. If set, the TSP will use SetProcessAffinityMask(GetCurrentProcess(), set) to limit TSP execution to one of the existing processors. Set to 0x1 by default.

Keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7 TAPI Service Provider

These are per-instance parameters found in a sub-tree of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7 TAPI Service Provider called DeviceXX.

NoDuplicateConnectedCalls

REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as on-hold. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function.

If your are using ESTOS' Call Control Gateway: from version 2.0.1.1474 - 05.11.2008 there is a fix for this same problem available.

List of supported TSPI functions

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

Mandatory functions

• TSPI_lineClose
• TSPI_lineCloseCall
• TSPI_lineGetAddressCaps
• TSPI_lineGetAddressID
• TSPI_lineGetAddressStatus
• TSPI_lineGetCallAddressID
• TSPI_lineGetCallInfo
• TSPI_lineGetCallStatus
• TSPI_lineGetDevCaps
• TSPI_lineGetID
• TSPI_lineGetLineDevStatus
• TSPI_lineGetNumAddressIDs
• TSPI_lineOpen
• TSPI_lineSetAppSpecific
• TSPI_lineSetCallParams
• TSPI_lineSetCurrentLocation
• TSPI_lineSetDefaultMediaDetection
• TSPI_lineSetMediaMode
• TSPI_lineSetStatusMessages
• TSPI_lineGetCallIDs
• TSPI_providerConfig
• TSPI_lineNegotiateTSPIVersion
• TSPI_providerUIIdentify
• TSPI_providerEnumDevices
• TSPI_providerShutdown
• TSPI_providerRemove
• TSPI_providerInstall

Basic functions

• TSPI_lineAnswer
• TSPI_lineDrop
• TSPI_lineMakeCall

Supplementary features

• TSPI_lineBlindTransfer
• TSPI_lineCompleteTransfer
• TSPI_lineForward
• TSPI_lineHold
• TSPI_lineUnhold
• TSPI_lineSwapHold
• TSPI_linePickup
• TSPI_lineRedirect

Dynamic line creation

• TSPI_providerCreateLineDevice

Related Articles

Howto:Troubleshooting the TAPI service provider

Support:TAPI doesnt install under Windows Vista

Support:TAPI fails on multi-processor system

Support:How should TAPI line device be registered?