WSCInstallProviderAndChains function (ws2spi.h)

Article
12/15/2022

Note

Layered Service Providers are deprecated. Starting with Windows 8 and Windows Server 2012, use Windows Filtering Platform. The WSCInstallProviderAndChains function installs the specified 32-bit transport provider as well as its specific protocol chains into the Winsock 2 system configuration database on a 32-bit computer. This function ensures that the protocol chains are ordered at the beginning of the transport provider configuration information, ensuring that a separate call to WSCWriteProviderOrder is not necessary.

Syntax

int WSCInstallProviderAndChains(
  [in]            LPGUID              lpProviderId,
  [in]            const LPWSTR        lpszProviderDllPath,
  [in]            const LPWSTR        lpszLspName,
  [in]            DWORD               dwServiceFlags,
  [in]            LPWSAPROTOCOL_INFOW lpProtocolInfoList,
  [in]            DWORD               dwNumberOfEntries,
  [out, optional] LPDWORD             lpdwCatalogEntryId,
  [out]           LPINT               lpErrno
);

Parameters

[in] lpProviderId

A pointer to a provider-specific, globally unique identifier (GUID).

[in] lpszProviderDllPath

A pointer to a Unicode string containing the load path to the provider's DLL. This string observes the usual rules for path resolution and can contain embedded environment strings (%SystemRoot%, for example). Such environment strings are expanded whenever Ws2_32.dll subsequently loads the provider DLL on behalf of an application. After any embedded environment strings are expanded, Ws2_32.dll passes the resulting string into the LoadLibrary function to load the provider into memory. For more information, see LoadLibrary.

[in] lpszLspName

A pointer to a Unicode string that contains the name of the socket provider.

[in] dwServiceFlags

The service flags for the type of "dummy" catalog entry to be created.

A dummy entry is a WSAProtocol_Info structure with the ChainLen member set to 0. The actual LSP catalog entry will reference the ID of this dummy entry in its ProtocolChain member.

The possible flags that can be set for this parameter are as follows:

Value	Meaning
XP1_IFS_HANDLES	The catalog entry is for an Installable File System (IFS) LSP, which returns IFS-specific socket handles. These handles are returned directly to the calling application. An IFS LSP cannot intercept the completion of Winsock calls, and does not have to have all Winsock functions implemented or available on it.

[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. The members of the WSAPROTOCOL_INFO structure that are examined are iProtocol, iAddressFamily, and iSocketType.

[in] dwNumberOfEntries

The number of entries in the lpProtocolInfoList array.

[out, optional] lpdwCatalogEntryId

Receives a pointer to the newly-installed "dummy" entry for the transport provider in the Winsock 2 system configuration database. This ID is used to install the catalog entries for the LSP.

[out] lpErrno

A pointer that receives an error code generated by the call if the function fails.

Return value

If
WSCInstallProviderAndChains succeeds, it returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code is returned in the lpErrno parameter.

Error code	Meaning
WSAEFAULT	One or more of the arguments is not in a valid part of the user address space.
WSAEINVAL	One or more of the arguments are invalid. This error is returned for the following conditions: the lpProviderId parameter is NULL, the lpszProviderDllPath parameter is invalid or the path length is too large (MAX_PATH was exceeded), the lpszLspName parameter is invalid or the name length is too large (WSAPROTOCOL_LEN is exceeded), the lpProtocolInfoList is set to a non-NULL and the dwNumberOfEntries parameter is zero, a duplicate provider ID or the layered service provider name already exist in the catalog, or a match cannot be found for the specified protocol, address family, and socket type.
WSAEINPROGRESS	A provider installation is already in progress.
WSAEINVALIDPROCTABLE	The provider is missing required functionality.
WSAENOBUFS	Memory cannot be allocated for buffers.
WSANO_RECOVERY	A nonrecoverable error occurred. This error is returned under several conditions including the following: the provider is already installed, the lpProtocolInfoList parameter was NULL and there was no base provider found, the maximum protocol chain length (MAX_PROTOCOL_CHAIN) was reached, the user lacks the administrative privileges required to write to the Winsock registry, or a failure occurred when creating or installing a catalog entry.
WSASYSCALLFAILURE	A system call that should never fail has failed.

Remarks

WSCInstallProviderAndChains is an enhanced version of the basic WSCInstallProvider function used to install a single transport service provider. 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.

If lpProtocolInfoList is set to NULL, this function creates protocol chains where the provider is layered over the base protocol for each unique protocol type as defined by the address family, socket type, and protocol. This eliminates the creation of any inaccessible duplicate provider entries.

If lpProtocolInfoList is set to a non-NULL value, this function creates protocol chains by obtaining the top-most entry in the configuration information that matches the address family, socket type, and protocol from each element in the provided array. Again, only the address family, socket type, and protocol are considered; all other members and duplicates are ignored.

Upon successful completion of this call, any subsequent calls to WSAEnumProtocols or WSCEnumProtocols will return the newly-created protocol chain entries. Be aware that in Windows environments, only instances of Ws_32.dll created by calling WSAStartup after the successful completion of WSCInstallProviderAndChains will include the new entries when WSAEnumProtocols and WSCEnumProtocols returns.

Note The WSAEnumProtocols function does not enumerate a layered protocol entry while WSCEnumProtocols does.

On success, WSCInstallProviderAndChains will attempt to alert all interested applications that have registered for notification of the change by calling WSAProviderConfigChange.

The WSCInstallProviderAndChains function can only be called by a user logged on as a member of the Administrators group. If WSCInstallProviderAndChains 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 provider-specific configuration must be performed by the calling application.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	ws2spi.h
Library	Ws2_32.lib
DLL	Ws2_32.dll