WSCInstallProvider function (ws2spi.h)
Syntax
int WSCInstallProvider(
[in] LPGUID lpProviderId,
[in] const WCHAR *lpszProviderDllPath,
[in] const LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out] LPINT lpErrno
);
Parameters
[in] lpProviderId
A pointer to a globally unique identifier (GUID) for the provider.
[in] lpszProviderDllPath
A pointer to a Unicode string that contains the load path to the provider DLL. This string observes the usual rules for path resolution and can contain embedded environment strings (such as %SystemRoot%). Such environment strings are expanded when the Ws2_32.dll must subsequently load the provider DLL on behalf of an application. After any embedded environment strings are expanded, the Ws2_32.dll passes the resulting string to the LoadLibrary function which loads the provider into memory. For more information, see LoadLibrary.
[in] lpProtocolInfoList
A pointer to an array of WSAProtocol_Info structures. Each structure defines a protocol, address family, and socket type supported by the provider.
[in] dwNumberOfEntries
The number of entries in the lpProtocolInfoList array.
[out] lpErrno
A pointer to the error code if the function fails.
Return value
If WSCInstallProvider succeeds, it returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code is returned in the lpErrno parameter.
| Error code | Meaning |
|---|---|
| One or more of the arguments is not in a valid part of the user address space. | |
| One or more of the arguments are invalid. | |
| Memory cannot be allocated for buffers. | |
| A nonrecoverable error occurred. This error is returned under several conditions including the following: the provider is already installed, the user lacks the administrative privileges required to write to the Winsock registry, or a failure occurred when creating or installing a catalog entry. | |
| A system call that should never fail has failed. | |
| Insufficient memory was available. This error is returned when there is insufficient memory to allocate a new catalog entry. |
Remarks
WSCInstallProvider is used to install a single transport service provider. This routine creates the necessary common Windows Sockets 2 configuration information for the specified provider. It is applicable to base protocols, layered protocols, and protocol chains. If a layered service provider is being installed, then WSCInstallProviderAndChains should be used. WSCInstallProviderAndChains can install a layered protocol and one or more protocol chains with a single function call. To accomplish the same work using WSCInstallProvider would require multiple function calls.
Winsock 2 accommodates layered protocols. A layered protocol is one that implements only higher level communications functions while relying on an underlying transport stack for the actual exchange of data with a remote endpoint. An example of a layered protocol would be a security layer that adds a protocol to the connection establishment process in order to perform authentication and to establish a mutually agreed upon encryption scheme. Such a security protocol would generally require the services of an underlying reliable transport protocol such as TCP or SPX. The term base protocol refers to a protocol such as TCP or SPX which is capable of performing data communications with a remote endpoint. The term layered protocol is used to describe a protocol that cannot stand alone. A protocol chain would then be defined as one or more layered protocols strung together and anchored by a base protocol. A base protocol has the ChainLen member of the WSAProtocol_Info structure set to BASE_PROTOCOL which is defined to be 1. A layered protocol has the ChainLen member of the WSAPROTOCOL_INFO structure set to LAYERED_PROTOCOL which is defined to be zero. A protocol chain has the ChainLen member of the WSAPROTOCOL_INFO structure set to greater than 1.
The lpProtocolInfoList parameter contains a list of protocol entries to install. Callers of WSCInstallProvider are responsible for setting up the proper protocol entries. The lpProtocolInfoList parameter must not be NULL.
Upon successful completion of this call, any subsequent calls to WSAEnumProtocols or WSCEnumProtocols will return the newly-created protocol entries. Be aware that in Windows environments, only instances of Ws_32.dll created by calling WSAStartup after the successful completion of WSCInstallProvider will include the new entries when WSAEnumProtocols and WSCEnumProtocols returns.
On success, WSCInstallProvider will attempt to alert all interested applications that have registered for notification of the change by calling WSAProviderConfigChange.
The WSCInstallProvider function can only be called by a user logged on as a member of the Administrators group. If WSCInstallProvider is called by a user that is not a member of the Administrators group, the function call will fail and WSANO_RECOVERY is returned in the lpErrno parameter. For computers running Windows Vista or Windows Server 2008, this function can also fail because of user account control (UAC). If an application that contains this function is executed by a user logged on as a member of the Administrators group other than the built-in Administrator, this call will fail unless the application has been marked in the manifest file with a requestedExecutionLevel set to requireAdministrator. If the application on Windows Vista or Windows Server 2008 lacks this manifest file, a user logged on as a member of the Administrators group other than the built-in Administrator must then be executing the application in an enhanced shell as the built-in Administrator (RunAs administrator) for this function to succeed.
Any file installation or service provider-specific configuration must be performed by the caller.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | ws2spi.h |
| Library | Ws2_32.lib |
| DLL | Ws2_32.dll |