TSPI_providerInstall (Compact 2013)

3/26/2014

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_providerRemove function. 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	tspi.h
Library	CellTSP.dll

See Also

Reference

TSPI Service Provider Functions
TSPI_providerInit
TSPI_providerRemove