lineAddProvider function (tapi.h)

Article
02/22/2024

The lineAddProvider function installs a new telephony service provider into the telephony system.

Syntax

LONG lineAddProvider(
  LPCSTR  lpszProviderFilename,
  HWND    hwndOwner,
  LPDWORD lpdwPermanentProviderID
);

Parameters

lpszProviderFilename

Pointer to a

null-terminated string containing the path of the service provider to be added.

hwndOwner

Handle to a window in which any dialog boxes that need to be displayed as part of the installation process (for example, by the service provider's TSPI_providerInstall function) would be attached. Can be NULL to indicate that any window created during the function should have no owner window.

lpdwPermanentProviderID

Pointer to a variable that receives the permanent provider identifier of the newly installed service provider.

Return value

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE, LINEERR_OPERATIONFAILED.

Remarks

During this function call, TAPI checks to ensure that it can access the service provider by calling its TSPI_providerInstall function; if this is unsuccessful (if the DLL or function cannot be found, or if TSPI_providerInstall returns an error), the function fails and the provider is not added to the telephony system. If this succeeds, and the Telephony system is active (one or more applications have called lineInitialize or lineInitializeEx), TAPI does not attempt to launch the newly-added service provider. Instead, in order to activate the new service provider, TAPI issues a message to restart Windows. When the activation succeeds, applications are informed of any new devices created by way of LINE_CREATE or PHONE_CREATE messages, or by a LINE_LINEDEVSTATE message requesting reinitialization (if the application does not support the CREATE messages).

This function copies no files—not the service provider DLL itself nor any supporting files; the application managing the addition of the provider must ensure that the provider is installed in a directory where it can be found by TAPI (for example, \WINDOWS, \WINDOWS\SYSTEM, or elsewhere on the path).

Requirements

Requirement	Value
Target Platform	Windows
Header	tapi.h
Library	Tapi32.lib
DLL	Tapi32.dll