Platform SDK: Windows Sockets

WSCWriteProviderOrder

The WSCWriteProviderOrder function is used to reorder the available transport providers. The order of the protocols determines the priority of a protocol when being enumerated or selected for us.

int WSCWriteProviderOrder (
  LPDWORD     lpwdCatalogEntryId,  
  DWORD       dwNumberOfEntries  
);

Parameters

lpwdCatalogEntryId: [in] Array of CatalogEntryId elements found in the WSAPROTOCOL_INFO structure. The order of the CatalogEntryId elements is the new priority ordering for the protocols.
dwNumberOfEntries: [in] Number of elements in the lpwdCatalogEntryId array.

Return Values

The function returns ERROR_SUCCESS (zero) if the routine is successful. Otherwise, it returns a specific error code.

Remarks

The order in which transport service providers are initially installed governs the order in which they are enumerated through WSCEnumProtocols at the service provider interface, or through WSAEnumProtocols at the application interface. More importantly, this order also governs the order in which protocols and service providers are considered when a client requests creation of a socket based on its address family, type, and protocol identifier.

Windows Sockets 2 includes an application called Sporder.exe that allows the catalog of installed protocols to be reordered interactively after protocols have already been installed. Windows Sockets 2 also includes an auxiliary DLL, Sporder.dll that exports this procedural interface for reordering protocols. This interface can be imported by linking with Sporder.lib.

Here are scenarios in which the WSCWriteProviderOrder function can fail.

The dwNumberOfEntries parameter is not equal to the number of registered service providers.
The lpwdCatalogEntryId contains an invalid catalog identifier.
The lpwdCatalogEntryId does not contain all valid catalog identifiers exactly one time.
The routine is not able to access the registry for some reason (for example, inadequate user permissions).
Another process (or thread) is currently calling the function.

Error Codes

Error code	Meaning
WSAEINVAL	Input parameters were bad, no action was taken.
ERROR_BUSY	Routine is being called by another thread or process.
(other)	Routine may return any registry error code.

Requirements

  Version: Requires Windows Sockets 2.0.
  Header: Declared in Sporder.h.
  Library: Included as a resource in Sporder.dll.