lineAddProvider
The lineAddProvider
function installs a new Telephony Service Provider into the Telephony system.
LONG lineAddPr ovider(
|
LPCSTR lpszProviderFilename, |
|
|
HWND hwndOwner, |
|
|
LPDWORD lpdwPermanentProviderID |
|
|
); |
|
Parameters
lpszProviderFilename
A pointer to
a NULL-terminated string containing the path of the service provider to be
added.
hwndOwner
A handle to a
window to which any dialogs which 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
A pointer to
a DWORD-sized memory location into which TAPI writes the permanent provider ID
of the newly installed service provider.
Return Values
Returns zero
if the request is successful or a negative error number if an error has
occurred. Possible return values are:
LINEERR_INIFILECORRUPT,
LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_NOMULTIPLEINSTANCE,
LINEERR_INVALPOINTER, 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 is successful, and the Win32 Telephony system is active (one or
more applications have called lineInitialize121W_TU 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 will be 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; it is the responsibility
of the application managing the addition of the provider to 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), and that all
other files necessary for operation.
Although this
is a new function which older applications would not be expected to call, for
backward compatibility, they should not be prevented from doing so; the
function will work the same way for all applications.
See Also