TUISPI_providerInstall

Implementation of the TUISPI_providerInstall function is the service provider's opportunity to install any additional "pieces" of the provider into the right directories (or at least verifying that they're there) and set up registry entries the provider needs. This function makes the TSPI_providerInstall function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

If the service provider requires any privately-defined entries in the registry for proper operation, they must be installed at this time.

Implementation is optional.

LONG TSPIAPI TUISPI_providerInstall(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,  
  HWND hwndOwner,                       
  DWORD dwPermanentProviderID           
);

Parameters

lpfnUIDLLCallback

Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.

hwndOwner

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

dwPermanentProviderID

The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM. LINEERR_INVALPARAM.

Remarks

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 can be invoked more than once during installation of the service provider, until there is a call to TUISPI_providerRemove. If the service provider does not require or support multiple instances of the provider, however, it returns the LINEERR_ constant LINEERR_NOMULTIPLEINSTANCE.

The corresponding function at the TAPI level is lineAddProvider. The LINE_CREATE message informs applications that are running about dynamic reconfiguration.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later.
  Version: Requires TAPI 2.0 or later.
  Header: Declared in Tspi.h.

See Also

LINE_CREATE, PHONE_STATE, TUISPI_providerConfig, TSPI_providerInit, TUISPI_providerRemove, TSPI_providerShutdown