WSCInstallProviderAndChains64_32 function (ws2spi.h)
The WSCInstallProviderAndChains64_32 function installs the specified transport provider and its specific protocol chains into both the 32-bit and 64-bit Winsock 2 system configuration databases on a 64-bit computer. This function ensures that the protocol chains are ordered at the beginning of the transport provider configuration information, making a separate call to WSCWriteProviderOrder unnecessary.
Syntax
int WSCInstallProviderAndChains64_32(
[in] LPGUID lpProviderId,
[in] const LPWSTR lpszProviderDllPath,
[in] const LPWSTR lpszProviderDllPath32,
[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 globally unique identifier (GUID) for the provider.
[in] lpszProviderDllPath
A pointer to a Unicode string that contains the load path to the provider 64-bit 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] lpszProviderDllPath32
A pointer to a Unicode string that contains the fully qualified path to the provider 32-bit 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 subsequently loads the provider DLL on behalf of an application. After any embedded environment strings are expanded, the 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 layered service provider (LSP).
[in] dwServiceFlags
The service flags for the type of layered protocol catalog entry to be created. A layered protocol entry is a WSAProtocol_Info structure with the ChainLen member set to 0. The actual catalog entry for the LSP will reference the ID of this layered protocol entry in its ProtocolChain member.
[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
A pointer to the newly installed layered protocol entry for the transport provider in the Winsock 2 system configuration database. This was the ID used to build the protocol chain entries installed in the catalog for the LSP.
[out] lpErrno
A pointer to the error code generated by the call if the function fails.
Return value
If WSCInstallProviderAndChains64_32 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. 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. | |
|
The provider is missing required functionality. A non-IFS provider must implement all of the Winsock 2 extension functions (AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets, and LPFN_WSARECVMSG (WSARecvMsg)). |
| A provider installation is already in progress. | |
| 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 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. | |
| A system call that should never fail has failed. |
Remarks
WSCInstallProviderAndChains64_32 is an enhanced version of the basic WSCInstallProvider64_32 function used to install a single transport service provider. If a layered service provider is being installed, then WSCInstallProviderAndChains64_32 should be used. WSCInstallProviderAndChains64_32 can install a layered protocol and one or more protocol chains with a single function call. To accomplish the same work using WSCInstallProvider64_32 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.
WSCInstallProviderAndChains64_32 is the 64-bit version of WSCInstallProviderAndChains. It installs the provider into both the 32-bit and 64-bit catalogs on 64-bit platforms. This means that on 64-bit platforms, two Winsock catalogs are maintained, and that both 32-bit and 64-bit processes are able to load the LSP installed with this function.
On a 64-bit computer, all calls not specifically designed for 32-bit (for example, all functions that do not end in "32") operate on the native 64-bit catalog. Processes that execute on a 64-bit computer must use WSCInstallProviderAndChains64_32 to operate on both the 32-bit catalog as well as the 64-bit catalog, preserving compatibility. The definitions and semantics of the specific 32-bit calls are the same as their native counterparts.
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, protocol} tuple from each element in the provided array. Again, only the {address family, socket type, protocol} tuple is considered; all other members and duplicates are ignored.
Upon successful completion of this call, any subsequent calls to WSAEnumProtocols, WSCEnumProtocols, or WSCEnumProtocols32 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 WSCInstallProviderAndChains64_32 will include the new entries when WSAEnumProtocols, WSCEnumProtocols, and WSCEnumProtocols32 returns.
On success, WSCInstallProviderAndChains64_32 will attempt to alert all interested applications that have registered for notification of the change by calling WSAProviderConfigChange.
The WSCInstallProviderAndChains64_32 function can only be called by a user logged on as a member of the Administrators group. If WSCInstallProviderAndChains64_32 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.
IFS and Non-IFS Providers
An IFS provider is one that returns native operating system handles. Typically these handles are associated with kernel mode protocol drivers. For example, the base TCP/IPv4, UDP/IPv4, TCP/IPv6, and UDP/IPv6 are IFS providers as these entries correspond to a kernel mode component. IFS handles can be used in **ReadFile**, **WriteFile**, and **CancelIo** function calls. A layered service provider that is an IFS provider simply returns the socket handle created from the lower provider (which must also be an IFS provider) directly to the calling application. An IFS LSP cannot intercept completion notifications for Winsock calls.A non-IFS provider is one that creates an intermediate handle with WPUCreateSocketHandle and returns this handle to the caller. This allows a non-IFS LSP to intercept send and receive completion events before the calling applications to allow for post processing (for example, decrypting a received chunk of data). Non-IFS socket handles can be used in calls to ReadFile and WriteFile, but cannot be used with CancelIo. The only guaranteed method of canceling an operation on a non-IFS handle is by closing the socket with closesocket.
Paths for 32-bit and 64-bit Provider DLLs
lpszProviderDllPath represents the fully qualified path to the 64-bit version of the provider DLL. This parameter can contain embedded environment strings (such as %SystemRoot%).lpszProviderDllPath32 represents the fully qualified path to the 32-bit version of the provider DLL. This parameter can contain embedded environment strings (such as %SystemRoot%).
If lpszProviderDllPath32 is NULL, then lpszProviderDllPath is the path for both 32 and 64 bit providers. When a 32-bit process on a 64-bit computer is running (for example, when a Winsock application loads the 32-bit version of an LSP), it attempts to load the 32-bit provider specified in lpszProviderDllPath. If lpszProviderDllPath32 is NULL, then the lpszProviderDllPath parameter must be set to %windir%\system32<dllname>. If this is not the case, the call fails with WSAEINVAL. If the path in lpszProviderDllPath is %windir%\system32<dllname> when lpszProviderDllPath32 is NULL, the call will be redirected (using the file system redirector) to the directory returned by GetSystemWow64Directory where the 32-bit LSP must reside. For Windows XP 64-bit edition, Windows Server 2003 and Windows Vista, this directory is %windir%\syswow64.
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 |