WSCUpdateProvider function (ws2spi.h)

Article
10/13/2021

The WSCUpdateProvider function modifies the specified transport provider in the system configuration database.

Syntax

int WSCUpdateProvider(
  [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 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] lpProtocolInfoList

A pointer to an array of WSAProtocol_Info structures. Each structure specifies or modifies 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 no error occurs, WSCUpdateProvider 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 are not in a valid part of the user address space.
WSAEINVAL	One or more of the arguments are invalid.
WSANO_RECOVERY	A nonrecoverable error occurred. This error is returned under several conditions including the following: the user lacks the administrative privileges required to write to the Winsock registry, or a failure occurred when opening or writing a catalog entry.
WSA_NOT_ENOUGH_MEMORY	Insufficient memory was available. This error is returned when there is insufficient memory to allocate a new catalog entry.

Remarks

The WSCUpdateProvider function modifies Windows Sockets 2 configuration information for the specified provider. It is applicable to base protocols, layered protocols, and protocol chains.

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 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.

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

The WSCUpdateProvider function can only be called by a user logged on as a member of the Administrators group. If WSCUpdateProvider is called by a user that is not a member of the Administrators group, the function call will fail.

For computers running on 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 XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	ws2spi.h
Library	Ws2_32.lib
DLL	Ws2_32.dll