LPWSPCLEANUP callback function (ws2spi.h)

Article
10/13/2021

The LPWSPCleanup function terminates use of the Windows Sockets service provider.

Syntax

LPWSPCLEANUP Lpwspcleanup;

int Lpwspcleanup(
  [out] LPINT lpErrno
)
{...}

Parameters

[out] lpErrno

Pointer to the error code.

Return value

The return value is zero if the operation has been successfully initiated. Otherwise, the value SOCKET_ERROR is returned, and a specific error number is available in lpErrno.

Error Code	Meaning
WSANOTINITIALISED	A successful WSPStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	Provider identifier given to the name-space provider is not managed by the name-space provider.

Remarks

The Windows Sockets 2 SPI client is required to perform a successful WSPStartup call before it can use Winsock service providers. When it has completed the use of Winsock service providers, the SPI client will call LPWSPCleanup to deregister itself from a Winsock service provider and allow the service provider to free any resources allocated on behalf of the Windows Sockets 2 client. It is permissible for SPI clients to make more than one WSPStartup call. For each WSPStartup call, a corresponding LPWSPCleanup call will also be issued. Only the final LPWSPCleanup for the service provider does the actual cleanup; the preceding calls simply decrement an internal reference count in the Winsock service provider.

When the internal reference count reaches zero and actual cleanup operations commence, any pending blocking or asynchronous calls issued by any thread in this process are canceled without posting any notification messages or signaling any event objects. Any pending overlapped send and receive operations (LPWSPSend, LPWSPSendTo, LPWSPRecv, LPWSPRecvFrom with an overlapped socket) issued by any thread in this process are also canceled without setting the event object or invoking the completion routine, if specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. Any sockets open when LPWSPCleanup is called are reset and automatically deallocated as if LPWSPCloseSocket was called; sockets that have been closed with LPWSPCloseSocket but still have pending data to be sent are not affected, but the pending data is still sent.

This function should not return until the service provider DLL is prepared to be unloaded from memory. In particular, any data remaining to be transmitted must either already have been sent or be queued for transmission by portions of the transport stack that will not be unloaded from memory along with the service provider's DLL.

A Winsock service provider must be prepared to deal with a process that terminates without invoking LPWSPCleanup (for example, as a result of an error). A Winsock service provider must ensure that LPWSPCleanup leaves things in a state in which the Ws2_32.dll can immediately invoke WSPStartup to reestablish Winsock usage.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	ws2spi.h