Reference7:TAPI Service Provider: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
VisualWikitext
New page: 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 ...
 
mNo edit summary
 
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The TAPI driver described in this article is obsolete!
Please refer to the [[Reference7:Unified Win32 and x64 TAPI Service Provider |current one]].
The PBX supports a TAPI interface (also known as TSP ''Tapi Service Provider'').
The PBX supports a TAPI interface (also known as TSP ''Tapi Service Provider'').
From firmware version 7 on, there is an enhanced implementation of the service provider available.   
From firmware version 7 on, there is an enhanced implementation of the service provider available.   
Line 7: Line 10:
This information applies to
This information applies to
* PBX, V7
* PBX, V7
* PBX, V8
Build 08-7030000 and later.
Build 08-7030000 and later.


Line 13: Line 17:
=== Enhancements ===
=== 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.
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 V7 implementation supports master PBX with unlimited numbers of slaves attached.
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===
===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.
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 [[Support:TAPI doesnt install under Windows Vista|the related wiki article for details]]. There is no support for 64bit operating systems.
For 32bit Vista, the standard setup will fail.  See [[Support:TAPI doesnt install under Windows Vista|the related wiki article for details]].
 
 
There is a [[Support:TAPI_x64_Platform_available_(beta_1)|Beta Version of TSP for x64]] (64-bit platform) available.


=== Download ===  
=== Download ===  
The V7 TSP can be found on the ''apps'' section of the [http://download.innovaphone.com/ice/7.00/ V7 download page].
The V7 TSP will be available on the ''apps'' section of the [http://download.innovaphone.com/ice/7.00/ V7 download page].


===Installation===
===Installation===
Line 41: Line 49:




[[Image:TAPI_Service_Provider_01.png]]
[[Image: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.   
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.   
Due to a problem with the Microsoft installer, do not install the TSP for Everyone.  Otherwise it may not de-install correctly.


During the installation, the TAPI configuration dialog will be launched (see below).
During the installation, the TAPI configuration dialog will be launched (see below).
Line 55: Line 61:
software is installed then, the TSP will be installed again into the
software is installed then, the TSP will be installed again into the
TAPI system.  Unfortunately, this will result in a new provider ID which
TAPI system.  Unfortunately, this will result in a new provider ID which
in turn will most likely require you to re-configure most of the TAPI
in turn may require you to re-configure some of the TAPI
applications using the TSP.
applications using the TSP.


Line 61: Line 67:
The TSP configuration dialog looks like this:
The TSP configuration dialog looks like this:


[[Image:TAPI_Service_Provider_02.png]]
[[Image:TAPI Service Provider Setup2.png]]




{| border=1
{| border=1
|-
|-
| Gateway || The IP address or host name of the IP21, IP400 or IP3000 the PBX is installed on
| PBX - Master || The IP address or host name of the device the PBX is installed on
|-
| Account || The gateways admin account name ( For 3rd party installations, you need to provide the gateways admin account and password here so that the TSP can control all users. However, for 1st party configurations, you may provide valid PBX user credentials instead)
|-
|-
| Password || The accounts password
| 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
|-
|-
| Use non-standard port || Tick this if your gateways http Server runs on a non-standard http port.
| PBX - Account || The PBX account name
|-
|-
| Status || During a Verify, checkmarks will be set here
| PBX - Password || The accounts password
|-
|-
| PBX Access || Provide the Name of the PBX user the TSP shall work on behalf of
| PBX - Use non-standard port || Tick this if your gateways http Server runs on a non-standard http port.
|-
|-
| TAPI Line Names || The TSP will create a TAPI line device for each PBX user it sees.  You can specify a template for the
| PBX - Use HTTPS || Tick this if you want to encrypt the PBX - TSP communication (recommended)
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)
|-
|-
| Control
| TAPI User - Username || Provide the Name of the PBX user the TSP shall work on behalf of
| Determines the kind of access the TSP will grant to the line devices.
{| border=1
|+
| Mode || Access
|-
|-
| Control selected user, monitor all users
| 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)
| Will show the busy state of all visible lines and allow full control over the users line. Typical 1rd party configuration.
|-
|-
| Control and monitor all users
| 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).
| Will allow full control over all visible lines. Typical 3rd party configuration.  Requires admin credentials.
|-
|-
| Monitor all users
| 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.
| Will show the busy state of all visible lines. This gives a read-only configuration where no users may be controlled.
|}
|}
|}


Line 104: Line 99:
| Meta || Replacement
| Meta || Replacement
|+
|+
| %c || The user name
| %c || The objects ''Long name'' (cn)
|+
|+
| %d || The users display name
| %d || The objects display name (dn)
|+
|+
| %h || h323 alias
| %h || The objects ''Name'' (h323 alias)
|+
|+
| %e || e164
| %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)
| %n || host name (of master pbx)
Line 122: Line 121:
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
| %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 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
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
behalf of the PC’s user, you will typically use the users PBX name as
''Username''.  Also, you will probably turn on the ''Control selected
''Username''.  In this case,  you may use
user, monitor all users'' control mode.  In this case,  you may use
the users PBX  name as ''Account'' and provide the users PBX password.
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
Note that in this case, the user must have a password defined in the
Line 137: Line 137:
PBX user account which is an active member of a group in which all PBX
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
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
create an otherwise unused PBX user '''_TAPI_''' for this.   
 
You may use
the users ''Name'' as ''Account'' and its ''Long Name'' as ''Username''.
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
In any case, the TSP will connect to the configured (master) PBX as well
as to all slaves and/or standbys.  The configured account needs to be
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
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
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
configuration empty.  This will result in a replication of all the user
data (incl.  the password) to all PBXs.
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
Please note that there currently is a limitation to 2000 users being in
Line 162: Line 168:
Here is a screenshot of the respective Outlook configuration:
Here is a screenshot of the respective Outlook configuration:


[[Image:TAPI_Service_Provider_03.png]]
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 <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V7 TSP</code>
* take note of the <code>installedProvider</code> entry (you will need the decimal value)
* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7 TAPI Service Provider</code>
* open its subkey <code>Device</code>''n'' where ''n'' is the decimal value of <code>installedProvider</code>
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists.  So if master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> 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===
===User Configuration===
Line 174: Line 196:
issue a
issue a
'''[[Reference:SOAP_API#integer_UserInitialize.28integer_session.2C_string_user.2C_bool_follow.29|UserInitialize]]'''
'''[[Reference:SOAP_API#integer_UserInitialize.28integer_session.2C_string_user.2C_bool_follow.29|UserInitialize]]'''
for each user.  This is done one each PBX (master and slave/standbys).
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. <code>LINEFORWARDMODE_UNCONDEXTERNAL</code>, are implemented by implicitly an ''Only'' or ''Only Not'' tag to the [[Reference7:Administration/PBX/Objects/Edit_CFs| 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.
 
<!-- rufumleitung, extern, intern, amtsleitung, vom amt, zum amt -->


==References==
==References==
The test applications provided with this setup comes from [[http://www.julmar.com Julmar Technology Inc]].
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].


== Limitations ==
== Limitations ==
The current implementation will track slave PBXs coming and going and
The current implementation will track slave PBXs coming and going and
updating call and user status accordingly.  Also, standby PBXs
updating call and user status accordingly.  Also, standby PBXs
configured to back up  slave PBX will be tracked correctly (that is, the
will be tracked correctly (that is, the
TSP will switch over between the PBX and its standby as required).   
TSP will switch over between the PBX and its standby as required).   
However, this is not implemented for a master standby currently.


TAPI has a flat line model.  That is, all line numbers (aka
TAPI has a flat line model.  That is, all line numbers (aka
''extensions'') are considered to live in a single name space.  As a
''extensions'') are considered to live in a single name space.  As a
result, lines with identical numbers cannot be distinguished in TAPI
result, lines with identical numbers cannot be distinguished in TAPI
(altough they can exist).  All extensions in all nodes of a PBX
(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
numbering tree are represented as TAPI lines.  When the TSP works with a
PXB that implements a hierarchical numbering tree, then some lines may
PXB that implements a hierarchical numbering tree, then some lines may
Line 199: Line 227:


==Known Problems==
==Known Problems==
The TSP doesn’t seem to run under Microsoft’s Remote Tapi Server.
* 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 <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V7 TSP\lineGUIDs</code>) 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 <code>DoTraceFile</code> to 0 will disable this.  No effect in standard build.
 
==== ProcessorMask ====
REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> 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 <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V7 TAPI Service Provider</code> called <code>Device</code>''XX''.  


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


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. The TSP currently does not support HTTPS.
If your are using [http://www.estos.de/download/software/eccg.htm 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==
==List of supported TSPI functions==
Line 246: Line 295:
* TSPI_lineBlindTransfer
* TSPI_lineBlindTransfer
* TSPI_lineCompleteTransfer
* TSPI_lineCompleteTransfer
* TSPI_lineForward
* TSPI_lineHold
* TSPI_lineHold
* TSPI_lineUnhold
* TSPI_lineUnhold

Latest revision as of 14:25, 26 October 2010

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.


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:


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?

Retrieved from "https://wiki.innovaphone.com/index.php?title=Reference7:TAPI_Service_Provider&oldid=18948"