Reference7:TAPI Service Provider

From innovaphone wiki
Jump to navigation Jump to search
There are also other versions of this article available: Reference | Reference7 (this version) | Reference8
The TAPI driver described in this article is obsolete!
Please refer to the current one.

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

  • PBX, V7
  • PBX, V8

Build 08-7030000 and later.

More Information

Enhancements

Previous TAPI service provider versions where restriced to a single PBX. That is, call- and user information was retrieved from one single PBX. Users registered in different PBXs (slaves) were not supported. The V7 implementation supports master PBX with unlimited numbers of slaves attached, as well as standby PBXs.

The TSP uses HTTP/SOAP as a means of communication to the PBX(s). There used to be no support for HTTP/Digest Authentication resulting in an exposure of the clear password on the net. The V7 implementation supports HTTPS, which protects the password (as well as the entire communication).

System Requirements

The TSP will install on any Windows 32bit platform. The standard setup program provided will install the retail version. A debug version is available in the tapi/debug folder. For 32bit Vista, the standard setup will fail. See the related wiki article for details.


There is a Beta Version of TSP for x64 (64-bit platform) available.

Download

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

Installation

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.

Microsoft’s Remote TAPI Server is currently not supported.

When the setup is done, your TSP is up and running, there is no need to go to the control panel. Also, it is recommended to use the setup instead of the control panel to de-install the TSP.


TAPI Service Provider Setup1.png

While the folder where the TSP is installed to is of your choice, you should not install it into the windows system32 folder as other service provider do.

During the installation, the TAPI configuration dialog will be launched (see below).


Upgrade

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. Unfortunately, this will result in a new provider ID which in turn may require you to re-configure some of the TAPI applications using the TSP.

Configuration

The TSP configuration dialog looks like this:

TAPI Service Provider Setup2.png


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?