Reference7:Unified Win32 and x64 TAPI Service Provider

From innovaphone wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

The PBX supports a TAPI interface (also known as TSP TAPI Service Provider). The firmware version 7 version of this TSP has been ported to the x64 platform and the newer Microsoft operating systems such as Windows Vista and Windows Server 2008. This new TSP package contains both Win32 and x64 versions of the driver and replaces the older V7 TSP package .

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

Unified Win32 and x64 TAPI Service Provider - zipcontent.png

  • 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

Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png

  • 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. Debug contains the driver's debug version, 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 then 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 directory 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

Crash Dumps

From build 7534 the TSP will write crash dumps to the log directory (usually something like C:\Program Files\innovaphone AG\innovaphone® PBX V7-64-x64 TSP\Logs) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like TSP7-64build-hour#minute-day.month#seqnr.dmp.

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

Upgrading from the old Win32-only Version

If you upgrade from the older Win32-only version of the TSP, you must first remove the old TSP from telephone and modem control panel and uninstall the old product from the Software (or Programs and Functions) control panel.

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 dialogue looks like this:

Unified Win32 and x64 TAPI Service Provider - Config UI.png

  • 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 while you add the TSP via the telephone and modem control panel, the TSP will not be added

TAPI talks to the PBX using SOAP which in turn uses HTTP for communication. Both secure (https) and non-secure (http) communication is supported. In any case, HTTP basic authentication is used. To be able to connect to the PBX, the TSP needs to know proper credentials to use during HTTP authentication. These are referred to as PBX Account and PBX Password. Also, a suitable TAPI User must be selected.

Controlling the Line Devices handled by TAPI

TAPI connects to your PBX as a PBX user referred to as TAPI User. It will see all PBX objects that are members of groups in which the TAPI User is an active member. If the TAPI User is not an active member in any group, TAPI will see the TAPI User object only. This may be useful in a 1st party TAPI scenario. PBX objects are represented as TAPI lines.

The PBX object you use as TAPI User needs to have at least Groups/Call Forwards Only PBX user rights. Its Long Name property is used as TAPI User Username, its Name property as PBX Account and the password as PBX Password. This is why the PBX object used as TAPI User must have a password configured.

1st Party Configuration

In a 1st party scenario, the TSP will only work on a single PBX object. This will typically be a user's phone and thus the user itself will be used as the TAPI User.

Unified Win32 and x64 TAPI Service Provider - FirstParty.png

In such a configuration the TSP is typically installed on the users PC and the CTI software is accessing TAPI directly (such as e.g. Microsoft Outlook does).

The TSP configuration dialogue will check for the number of lines seen. If it is only one, then it will issue a warning message:

Unified Win32 and x64 TAPI Service Provider - OnlyOne.png

This is because 3rd party configurations are much more common and this situation often indicates a configuration problem. In a first party configuration, you can safely ignore this message.

3rd Party Configuration

In a 3rd party configuration, the TSP will work with multiple PBX objects.

Unified Win32 and x64 TAPI Service Provider - ThirdParty.png

Typically, you will share a single TSP instance on a server system for use by several users on their desktop PCs. This is done by virtue of a TAPI Server. There are various TAPI server products available on the market, including but not limit to the [IXI Call product] marketed by innovaphone and the remote TAPI server included in Microsoft Windows server operating systems.

In this scenario, it is recommended to create a pseudo PBX user object for use as the TAPI User. This pseudo user is often called _TAPI_. You would create a dedicated group to control the list of PBX objects the TSP creates a line device for. This group is often called tapi.

Selective Call Forwards

Many CTI applications support distinct call forwards for internal and/or external calls. The TSP will translate such requests to a call forward on the PBX which has the Only or Only not property set to the number of the trunk line. For this to work, it needs to know this number. To know the number, the trunk line PBX object must be seen by the TSP (see above). If this is not the case, the TSP configuration dialogue will issue a warning:


Unified Win32 and x64 TAPI Service Provider - NoTrunk.png

In a vanilla first party scenario, this is obviously not the case. If you don't care, you can safely ignore this issue. Attempts to set such call forward will be rejected then as operation unavailable.

Multi Site Configuration

In a system with multiple PBXs, the TSP needs to connect to each of the individual PBXs.

Unified Win32 and x64 TAPI Service Provider - MultiSite.png

In this case, you would specify your master PBX as PBX Master. There is no need to configure the complete PBX tree to the TSP as it is determined dynamically on runtime by analysing the PBX/Node objects in the master PBX and their registration status. If a registered PBX is found, this PBX is added to the list of active PBXs and a new connection is established. The PBX tree is built and maintained dynamically. A reconfiguration or restart of the TSP is not required on changes thus. For this to work

  • the PBX/Node objects must be visible to the TSP.
  • the PBX object used as TAPI User must exist in each PBX with same properties (including the password)

In a replicated scenario, you would create a TAPI user as recommended above and leave the PBX and Node properties empty . You can disable slave detection by checking Do not monitor slaves property in the TSP configuration dialogue.

TAPI maintains an address property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the Number property of the node the respective PBX object is configured in, plus the Number property of the object itself. So if an object has Number 42 and lives in node 801, then its correspondence line device will have address 80142. By checking the Use pure node extensions property in the TSP configuration dialogue, you change the algorithm so that only the objects own Number is used (42 in our example).

Standby Configurations

In a system with standby PBX for the master PBX, you need to specify the PBX Standby IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

Working with multiple, unrelated 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. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

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

  • open the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7-64 TAPI Service Provider
  • open its subkey Devicen where n is the provider id of the installed innovaphone TSP
  • 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 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. As with multi site configurations, all PBXs need to be accessible using the same TAPI User.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

Setting the Line Device Name

The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects Long Name followed by the name of the PBX the user ought to register with in parentheses. So if the users Long Name is Foo Bar and the registration PBX is branch1, the line device will be called Foo Bar (branch1). You can specify a different pattern by changing the TAPI Line Names property of the TSP configuration dialogue. The following replacement characters are available:

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)

The default pattern is %c (%x).


References

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

Limitations

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

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 depending on the setting of the Use pure node extensions property). 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 is not tested with 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. See the TAPI trouble shooting article for details
  • 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\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7-64 TAPI Service Provider\lineGUIDs) that maps the PBX's line GUID to a fixed integer value (known as permanent line id in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
  • Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove TSP7-64.tsp and TSP7-64UI.dll from both %windir%\system32 and %windir%\sysWOW64

Tweaks

There are a few configuration options which should be used rarely. They can be enabled by setting appropriate registry values. These values may need to be created in the registry first.

Values in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7-64 TAPI Service Provider:

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 or more of the existing processors. Set to 0xff by default.
LineTimeOut
REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show Line unnamed line entries in their line list. If this is a problem, set it to a larger value (e.g. 120).
IgnoreDevStatus
Reg_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

Values in a key underneath HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7-64 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. This option thus is deprecated.

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:How should TAPI line device be registered?