Reference8:TAPI Service Provider

From innovaphone-wiki

Jump to: navigation, search
There are other versions of this article: Reference | Reference7 | Reference8 (this version)

The innovaphone PBX V8.0 based TAPI Service Provider (TSP) is an enhanced version of the previous TSP version that takes advantage of the new SOAP features provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The previous TSP still must be used for V7 PBX systems.

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

Contents

Applies To

This information applies to

  • innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
  • innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

More Information

Enhancements

Support for V8 firmware devices 
Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. Number property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, mobility devices are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
Support for presence based lines 
These are TAPI lines shown which reflect the users presence state. Presence state open is mapped to a TAPI device status in service. Presence activity on-the-phone is mapped to a virtual call in state connected.
NB: V8 PBX Firmware did set presence activity on-the-phone for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The presence line feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

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 a deprecated 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!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

No special PBX licenses are required to use the innovaphone TSP.

Download

The V8 TSP will be available on the apps section of the V8 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

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

Image: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 (tsp8.tsp and tsp8UI.dll) in to this directory. All other files however will be copied to the innovaphone AG\innovaphone® PBX V8 TAPI Service Provider 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 (tsp8UI.dll) will be installed to the windows Windows on Windows64 System Folder (SysWOW64).

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 versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), 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.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's 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 tsp8.tsp and tsp8UI.dll from the system32 folder as well as - on x64 systems - from the SysWOW64 folder.

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

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

Rolling out First Party TSPs to multiple PCs

Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's Telephony service providers overview and Manage Telephony Servers documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the software deployment schemes Microsoft Server provide. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the Password in a REG_SZ value named admin1-free and the Account into a REG_SZ value named admin2-free. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

Image:TAPI Service Provider-tsp8-nocrypt.png

Keep in mind that having credentials in clear in the registry presents a security risk!

This feature is available in build 8079 and later.

Upgrade from Build 8164 or earlier

From build 8165, the TAPI configuration has been moved to a different registry location. This has been done because latest windows versions (namely, Windows 10) do not allow the TSP to access registry information in the location used so far (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider). To work around this issue, it is now stored in HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider.

The TSP configuration dialogue however runs with user privileges (as opposed to the TSP which runs with limited service privileges). It can therefore read the old configuration information and copy it to the new location. From build 8165, the configuration dialogue will thus copy any old configuration information to the new location when it is opened. When you upgrade an existing installation and open the configuration dialogue, you will see no change. However, when the configuration is saved, it is then present in the new location.

To upgrade an installation from build 8164 or earlier (that is TAPI 'V8 TAPI Service Provider (32 and 64bit) - hotfix14 available in the V8 applications hotfix20 package or earlier), proceed as follows:

  • stop the telephony service (e.g. net stop tapisrv)
  • install the new TSP
  • open the TSP configuration dialogue
  • verify the configuration data
  • save the configuration
  • (re) start your TAPI application

If you fail to migrate the configuration as described, the TSP will start, but not work!

Configuration

The TSP configuration dialogue looks like this:

Image: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 Viewing 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.

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

Image: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.

Image: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 Estos ProCall product 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:


Image: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.

Image: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 object used as TAPI User must exist in each PBX with same properties (including name and the password). You may want to use _TAPI_ as Name/Long Name. This object must be active member in a group (which you may want to call tapi). A password must be set. The object must have at least Viewing only rights
  • the slave PBX-objects (or in older firmware versions the slave PBX Node-objects) must be visible to the TSP (that is, must be non-active member of the group the TAPI User object is an active member of, e.g. tapi) so that the slaves are made known to the TSP.


In a replicated scenario, you would create a TAPI user as recommended above and leave the PBX and Node properties empty . This user should then be used as both PBX Account and TAPI User Username in the TAPI configuration dialog.

Further relevant settings:

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\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1]
  • open its subkey Devicen where n is the provider id of the installed innovaphone TSP (for builds before 8164 only)
  • 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)
%C The objects Long Name (cn) followed by the Name of the Device the line represents in braces [name] if it differs from the Long Name
%d The objects Display Name (dn)
%D The objects Display Name (dn) followed by the Name of the Device the line represents in braces [name] if it differs from the Display Name
%h The objects Name (h323 alias)
%H The objects Name (h323 alias) followed by the Name of the Device the line represents in braces [name] if it differs from the Name
%t The Name of the Device the line represents
%T The Hardware Id of the Device the line represents (from build 8181)
%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).


Miscellaneous Flags

Show full E164 Numbers 
when set, the TSP will announce the full calling number from the root when indicated by the PBX in the TAPI calling party name attribute. The number will be appended to the calling name with a @.
Do not show parked Calls 
will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
Map PBX Devices to Lines 
if set, the TSP will create one TAPI line for each individual PBX device configured in a user object. See #Enhancements above. If you do not set this flag, see Support:How should TAPI line device be registered?
Map Presence Status to TAPI Lines 
if set, the TSP will create one extra TAPI line for each PBX device object. See #Enhancements above.
No special Disconnect Behaviour 
normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6. To prevent the IP-Phone to play any tones after the call is disconnected, the phone preferences option Go onhook if final call is released by remote side even if handset is lifted can be activated. This is the feature of the IP-Phone is useful in a e.g. call center at agent phones and can be configured here Reference11r1:Phone/Preferences.
To prevent an innovaphone IP-Phone from playing any tones after a call is disconnected, the phone preferences option Go onhook if final call is released by remote side even if handset is lifted can be activated. This feature is useful for agent phones in a call center for example and can be configured in Reference11r1:Phone/Preferences

Trouble Shooting

The TSP will (from build 8095) write messages of type INFO (informational messages) or WARNING (Warnings/Errors) to the windows event log. Such events are always logged to the application log and event source is the provider name (innovaphone® PBX V8 TAPI Service Provider).

Turning on Debugging

There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both retail and debug builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example dbgview which is available from Microsoft.

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value TraceLevel in the HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1] key.

The easiest way to set the TSP's debug level is with the TSP Control utility (tsptray.exe) which is installed with the TSP.

The available classes include

Bit in TraceLevel Class
0x00000001 Minimum tracing
0x00000002 TAPI api traces
0x00000020 Basic telephony object creation/destruction
0x00000040 Thread creation/destruction
0x00000080 Request creation/destruction
0x00000100 call related messages
0x00000200 Call id map
0x00000400 Warnings/Errors
0x00000800 Worker thread execution
0x00001000 Full lock/unlock notifications
0x00002000 Win32 Critical section create/destroy
0x00004000 Agent proxy support
0x00008000 constructor/destructor debug
0x00010000 development debugs
0x00100000 verbose debugging
0x00200000 SOAP trace
0x00400000 SOAP message dumps
0x01000000 ATL debug
0x02000000 line related messages
0x04000000 informational messages
0x10000000 dump call infos
0x20000000 dump PBX infos
0x80000000 output log messages to file

If TraceLevel is not set, it defaults to (hex) 04000400 in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) 92200580. The TraceLevel can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both informational messages and Warnings/Errors are always turned on (from build 8095).

A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of TraceLevel may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually Network Service) to e.g. Local System.
Crash Dumps

From build 8063 the TSP will write crash dumps to the log directory (usually something like C:\Program Files\innovaphone AG\innovaphone® PBX V8 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 TSP8build-hour#minute-day.month#seqnr.dmp.

Forcing a Crash Dump

In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a lineMakeCall with called number 0815, called-subaddress 4711 and called-name !crash! or simply calling 0815|4711^!crash! from phone.exe.

Saving Log Messages to a File

The 0x80000000 value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value DoTraceFile must be set to 1 in HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1] when the TSP starts. If this value is not present, it defaults to 1 in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the NumLogFiles value in HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1]. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it created so far. However, any TSP will only remove log files created by itself. This ensures that if the TSP or the system terminates prematurely, the log files will be kept even if a new instance is started and terminated later on. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value KeepLogFiles in HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1]:

0 default remove all log files on termination
1 keep the last n log files (depending on NumLogFiles) on termination
2 keep all log files

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers.

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.(if the copying fails, we recommend to deactivate the telephony service. But don’t forget to reset it to automatically if you are done copying)
  • if the copy does not succeed or the debug driver is not shown n the modem control panel after, it might be that a TAPI application re-starts the windows telephony before you actually to the copy. If so, you can set the Startup type of the Windows Telephony service to Disabled instead of Manual in the services control panel (services.msc). You can then Stop the services, copy the file and finally set the services mode back to Manual

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

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.


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

The PBX's SOAP interface (on top of which the TSP is built) has no primitives to initiate a directed call pick-up based on a target number. The TSP will reject such requests with Operation not available. Pickup by name (which is understood as a group name) or unspecific is supported though.

Citrix Environments

What happens is that all Citrix sessions share the same TAPI driver. This allows all users in the Citrix sessions to select "their" line from the set of all TAPI lines. Then everything works as desired. It is important to note that theoretically one user can select the line of another user. You can use the "Microsoft Remote TAPI Server", to implement access rights for lines for separate Citrix sessions.

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 the leineeGUIDs subkey of HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1]) 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 TSP8.tsp and TSP8UI.dll from both %windir%\system32 and %windir%\sysWOW64
  • From Version 9, hotfix 1, the PBX firmware will not list objects tagged as hide from LDAP in the result of a FindUser() call. As a result, such objects will not be shown in the TAPI configuration dialogue Username drop-down. If you want to use such an object as TAPI User you can simply type in the name without selecting it from the drop down.
  • Sometimes, setting configuration with TSP Control (not the telephone control panel dialogue) does not work due to windows' User Access Control (UAC), see Howto:TAPI_TSP_Control_Windows7 for Details
  • Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see #Rolling_out_First_Party_TSPs_to_multiple_PCs for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
  • The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages about to spawn new workerthread (n requests, m threads) -- but limit l exceeded. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
  • The TSP can work with dynamic PBXs too. However, the TSP needs to determine the slave PBXs IP addresses from the master. If the slave is a dynamic PBX and it is hosted on the same device as the master and it is registered to the master using 127.0.0.1, the TSP will only learn the 127.0.0.1 as the slave's IP address. Of course, connection to the slave PBX will fail then.

TAPI Operation with 3rd party Phones or innovaphone Phones registered with SIP

Various TAPI functions rely on use of the Remote Control Facility message. This message is not supported in 3rd party phones and also not fully supported in innovaphone Phones when they are registered to the PBX using SIP. Full TAPI functionality is thus only available for innovaphone phones registered to the PBX using H.323.

Known Limitations:

  • Accepting an incoming call (lineAnswer)
  • Automatic initiation of an outgoing call in handsfree mode (instead, the calling phone first rings and starts the outgoing call upon of-hook)
  • toggle between 2 calls active on a phone (lineSwapHold)
  • initiation and termination of a 3PTY (lineCompleteTransfer with mode LINETRANSFERMODE_CONFERENCE, lineDrop on a conference call)

TAPI on Windows8 / Server 2012

Windows8 doesn't let you disable User Access Control (UAC) completely. This has the disadvantage that TSP Control (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:

  1. use the hidden Administrator account on Windows 8
  2. elevate the tsptray.exe application

To use the elevated Administrator account on Windows 8 you first need to un-hide it:

  • log in to an account with administrator rights
  • use the Windows-Key+X shortcut and select Command Prompt (Administrator) (Eingabeaufforderung (Administrator)). An elevated cmd prompt appears
  • type net user administrator /active:yes
  • the fully elevated Administrator account is now available and you can log-in to this account as usual
  • Please make sure the account has a password set - by default, it does not!!

To elevate the tsptray.exe application;

  • log in to an account with administrator rights
  • start a windows explorer
  • change directory to C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP
  • right click on tsptray.exe and open the properties (Eigenschaften) menu
  • switch to the Compatibility (Kompatibilität) tab
  • tick the Run as administrator (Program als Administrator ausführen) check mark
  • save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

HTTPS

The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This has been fixed with V8 TAPI Service Provider (32 and 64bit) - hotfix10.

.Net 3.5 missing on Server 2012

Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the NetFX3 Feature needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:<path to windows setup, e.g. d:>\sources\sxs /LimitAccess

See also

TAPI dialer fails from Outlook when Lync client was/is installed

We have received reports that 1st-party TAPI dial-out from Outlook does not work anymore when a Lync client was installed. Some users report that this phenomenon occurred only after an upgrade to Windows 8. Reportedly, this can be fixed by setting a registry key as outlined in Microsoft's knowledge-base. You may want to give this a try. However, we have not seen this issue ourselves and thus can't comment on it further.

Slow Network Performance

TAPI is pretty sensitive to slow network performance. While the TSP is multi-threaded, some internal locking must be done so that slow requests to a PBX my block other pending requests, resulting in unpleasant performance. The TSP will create Windows Event Log entries of type slow SOAP call performance if this is detected. You should inspect your event log regularly and resolve the reason for such network performance.

Long PBX request round-trips may have a number of reasons:

slow WAN performance 
of course, if the WAN is slow or unstable, bad performance is the result
inappropriate QoS 
SOAP is using HTTP/HTTPS. In a QoS enabled network, call signalling and RTP may work fine, whereas HTTP/HTTPS is considered to be of no importance. You need to keep in mind that such QoS policy may lead to bad TAPI performance, as the SOAP traffic used by the TSP (being based on HTTP/HTTPS) may be delayed. You should assign SOAP traffic a similar priority as you do for VoIP signalling
overloaded PBX 
HTTP traffic is treated on a low priority level in the PBX. If the PBX runs near to 100% CPU load, while all RTP and VoIP signalling will work well still, HTTP traffic may get severely delayed. You should make sure your PBX runs well under 100% CPU load to get good TAPI performance. See Reference:Device Health Check for more details

TAPI on Windows 10

In Windows 10, the TSP is not allowed any longer to read/write its own registry tree. For this reason, it is not possible to store or read the configuration. As a result, the TSP will not work. To fix this, you need to modify the registry access rights so that the TSP has read/write access to HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider[1].


Note on windows registry paths[1]:

  1. 1.0 1.1 1.2 1.3 1.4 1.5 1.6 1.7 Due to a change in Windows Registry Access Rights in Windows 10, from Build 8165, the configuration is stored in
    HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider
    (a place that is suitable for Windows 10 too). Before, the configuration was stored in
    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider
    See Upgrade from Build 8164 or_earlier above for more details.

Tweaks

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

Since Hotfix 15 the location to set the interop tweaks has been changed to HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider:

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.
ClearFwdOnSet 
REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are replaced by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).
Tapi spec is pretty clear on how this should work: The provider should "unforward everything" prior to setting the new forwarding instructions. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.
No3PTY 
REG_DWORD. See Notes_on_3PTY_Conferences below.
HiddenRecordingNumber
REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. not on hold) call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number 44, you would set this registry value to 44 (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using overlapped dialling, all call states will be shown until the called number matches the value of HiddenRecordingNumber and all subsequent call states will be suppressed. This will probably leave the call shown in dialling state. The feature should be used for destinations which are called using block dialling only thus.
SilentHold 
REG_DWORD. When a call is put on hold using lineHold, the held party will hear music on hold emitted by the PBX. The hold-initiator will hear a dialling tone (PBX firmware v11r2 and up, with older versions the initiator would hear music on hold). When SilentHold is set to a non-zero value, the initiating party will hear silence - i.e. no dialling tone (this is available from TAPI V8 hotfix 8).


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.
UseFirstLeg2 
REG_DWORD. TAPI allows only for a single leg-2 info (redirection information in case of a call forward). If a call is forwarded mutliple times, by default the last redirection is shown in TAPI. If UseFirstLeg2 is set to 1 however, the first redirection is shown.
UseNameForDeviceGuid 
REG_DWORD. The TSP will create a TAPI line for each Device of each PBX object (if MapDevices is set). The internal unique identifier includes the Hardware Id found in the Device. If this changes, the TAPI line representing the Device is considered new and a new TAPI permanent line id is allocated. This may be annoying cause when a device serial number (e.g. for a telephone) is used as Hardware Id, replacing the device creates a new TAPI line. If UseNameForDeviceGuid is set to 1, the TSP will use the Devices Name instead (which usually not changes). While this might be more convenient, be aware that you must make sure that no PBX object has duplicate Names! Otherwise, TAPI will get confused. Experimental still, available from build 8178

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.

  • TSPI_lineAnswer
  • TSPI_lineBlindTransfer
  • TSPI_lineClose
  • TSPI_lineCloseCall
  • TSPI_lineCompleteTransfer
  • TSPI_lineDevSpecific
  • TSPI_lineDevSpecificFeature
  • TSPI_lineDial
  • TSPI_lineDrop
  • TSPI_lineForward
  • TSPI_lineGenerateDigits
  • TSPI_lineGetAddressCaps
  • TSPI_lineGetAddressID
  • TSPI_lineGetAddressStatus
  • TSPI_lineGetCallAddressID
  • TSPI_lineGetCallHubTracking
  • TSPI_lineGetCallIDs
  • TSPI_lineGetCallInfo
  • TSPI_lineGetCallStatus
  • TSPI_lineGetDevCaps
  • TSPI_lineGetExtensionID
  • TSPI_lineGetID
  • TSPI_lineGetLineDevStatus
  • TSPI_lineGetNumAddressIDs
  • TSPI_lineHold
  • TSPI_lineMakeCall
  • TSPI_lineNegotiateExtVersion
  • TSPI_lineNegotiateTSPIVersion
  • TSPI_lineOpen
  • TSPI_linePark
  • TSPI_linePickup
  • TSPI_lineRedirect
  • TSPI_lineSelectExtVersion
  • TSPI_lineSendUserUserInfo
  • TSPI_lineSetAppSpecific
  • TSPI_lineSetCallData
  • TSPI_lineSetCallHubTracking
  • TSPI_lineSetCallParams
  • TSPI_lineSetCurrentLocation
  • TSPI_lineSetDefaultMediaDetection
  • TSPI_lineSetMediaMode
  • TSPI_lineSetStatusMessages
  • TSPI_lineSetupTransfer
  • TSPI_lineSwapHold
  • TSPI_lineUnhold
  • TSPI_lineUnpark


  • TSPI_providerConfig
  • TSPI_providerCreateLineDevice
  • TSPI_providerEnumDevices
  • TSPI_providerGenericDialogData
  • TSPI_providerInit
  • TSPI_providerInstall
  • TSPI_providerRemove
  • TSPI_providerShutdown
  • TSPI_providerUIIdentify
Notes on Consultation Calls

This TSP supports the lineSetupTransfer function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, TSPI_lineMakeCall can be used where lineSetupTransfer would be otherwise. The notion of a special consultation call is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for lineSetupTransfer. This ability is indicated by the LINEADDRCAPFLAGS_TRANSFERMAKE and LINEADDRCAPFLAGS_CONFERENCEMAKE flags. The transfer is then requested by using TSPI_lineCompleteTransfer.

Notes on 3PTY Conferences

The TSP supports the management of 3PTY conferences. These can be initiated by using TSPI_lineCompleteTransfer with LINETRANSFERMODE_CONFERENCE instead of LINETRANSFERMODE_TRANSFER. This is indicated by the flags LINEADDRCAPFLAGS_CONFERENCEHELD and LINEADDRCAPFLAGS_CONFERENCEMAKE. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to TSPI_lineCompleteTransfer will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag No3PTY (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is TSPI_lineDrop. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting LINEADDRCAPFLAGS_CONFDROP.

A lineDrop() on one of the 2 real calls involved will of course cancel this call and thus remove the 3PTY.

Notes on Intrusion Calls

A special case of 3PTY is an intrusion call initiated by a partner function key. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless not set LINEADDRCAPFLAGS_CONFDROP on such conferences (as TAPI does not know that this is an intrusion call).

Notes on Recording Calls

A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless not set LINEADDRCAPFLAGS_CONFDROP on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless No3PTY is set). This might be confusing to applications and/or users. See the HiddenRecordingNumber tweak above for a method to hide such calls.

Notes on parked Calls

The PBX can park calls from and to any existing PBX object, e.g. by virtue of specific feature keys. They are parked to/from a numeric park position. In SOAP however, calls are parked to an object by providing the objects UserInitialize() handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the CallInfo record. To unpark, UserPickup can be used providing the parked calls call handle as call argument.

The TAPI specification is unclear on how the address information required to lineUnpark() a call can be obtained by an application (except that it is returned from linePark() if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason LINECALLREASON_PARKED. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to lineUnpark() to unpark a call. If the appication does not support this mode of operation but supports lineUnpark() and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

Notes on sending User to User Information

The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is not supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:

  • data is not transparent. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
  • data is not sent within the call, but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
  • message calls are not indicated by the SOAP CallInfo records. As a result, messages (that is, user to user information) cannot be received with TAPI and lineReleaseUserUserInfo is not supported
Notes on sending proprietary innovaphone Remote Control Facilities

The SOAP UserRc function allows to send various facility messages to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI lineBlindTransfer function. If the called party name provided as destination for the lineBlindTransfer (in lpszDestAddress) has the magic value USERRC, then the called subaddress is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the called party name and the called subaddress into lpszDestAddress see Microsoft's Canonical Address specification. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to |16^USERRC (empty address, subaddress 16 (that is, change to handset mode), called name USERRC) will switch the phone having the call to be transferred into handset mode (and |18^USERRC will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (lineBlindTransfer is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with lineMakeCall (that is, in SOAP's UserCall function). For example, setting up a call to 123|21^USERRC will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's lineCompleteCall function with LINECALLCOMPLMODE_INTRUDE though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see notes on intrusion calls above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

Related Articles

Personal tools