Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function installs any additional "pieces" of the provider into the right directories (or at least verifying that they are there), sets up the provider's registry entries for its lines and phones, and creates any other entries necessary for the service provider. It is called from the Telephony Control Panel utility (supplied with Windows Telephony in versions 1.4 and earlier) when the Add button is pressed.

Syntax 

LONG TSPIAPI TSPI_providerInstall(
  HWND 
hwndOwner, 
  DWORD 
dwPermanentProviderID 
);

Parameters

hwndOwner

Handle of the parent window in which the function can create any dialog box windows that are required during installation.

dwPermanentProviderID

Service provider's permanent provider identifier.

Return Value

Returns zero if the function succeeds or an error number if an error occurs. The following table shows the return values for this method.

Value Description

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INIFILECORRUPT

The INI file is corrupted.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INVALPARAM

The parameter is invalid.

Remarks

This function completes the installation of other pieces required by the service provider after its entries in the [Providers] section in the registry have been made. If the service provider requires any additional privately-defined entries in the registry for proper operation, they must also be installed.

This function must leave the system in a consistent state. It should run to completion, not allowing the user to abort the installation when it is partly completed. If installation fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete installation is possible, before the installation begins.

This function is called only once, during installation of the service provider, until there is a call to the TSPI_providerRemovefunction. It must be called before any other TSPI-defined function.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function (with external sequence requirements met as described here) when the "add" command is invoked.

There is no corresponding function at the TAPI level. At that level, applications expect to have service providers already installed. Running applications are informed about dynamic reconfiguration through the LINEDEVSTATE_REINIT or PHONESTATE_REINIT value in the LINE_LINEDEVSTATE or PHONE_STATE message.

Requirements

Header tapicomn.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also