WSPCloseSocket function

Article
06/19/2017

The WSPCloseSocket function closes a socket.

Syntax

int WSPCloseSocket(
  _In_  SOCKET s,
  _Out_ LPINT  lpErrno
);

Parameters

s [in]
Descriptor that identifies a socket.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Return code	Description
WSAENETDOWN	Network subsystem failed.
WSAENOTSOCK	Descriptor is not a socket.

Note that a SAN service provider does not support the following error codes for WSPCloseSocket:

Return code	Description
WSAEINPROGRESS	The Windows Sockets switch never issues cancel blocking calls to a SAN service provider.
WSAEWOULDBLOCK	The Windows Sockets switch handles graceful disconnect.

Remarks

The Windows Sockets switch calls a SAN service provider's WSPCloseSocket function to release a socket. After the WSPCloseSocket completes, the SAN service provider should fail further references to the closed socket with the error WSAENOTSOCK.

If the WSPCloseSocket function releases the last reference to an underlying socket, the SAN service provider discards the associated naming information and queued data. The SAN service provider cancels any pending calls or asynchronous operations for the socket.

To cancel a pending call

A SAN service provider calls the WPUCompleteOverlappedRequest function to complete the overlapped operation that is related to that pending call.
In this call, the SAN service provider passes a pointer to a WSAOVERLAPPED structure for the overlapped operation. It also passes the WSA_OPERATION_ABORTED error code to specify that the overlapped operation was canceled because the socket was closed.
Before the SAN service provider completes overlapped operations, it should release any memory associated with those overlapped operations.

For more information about WPUCompleteOverlappedRequest, see the Microsoft Windows SDK documentation.

During socket closure, the SAN service provider does not signal event objects on that socket to post notification messages. For example, the SAN service provider does not post notification messages that indicate the arrival of an incoming connection (FD_ACCEPT) or the completion of a connection operation (FD_CONNECT).

The Windows Sockets switch fully implements the semantics required by graceful disconnect and associated socket options such as SO_LINGER, SO_DONTLINGER, and nonblocking close. The switch calls the SAN service provider's WSPCloseSocket function only for a hard close on the socket (that is, to close the socket's connection and cancel all outstanding requests on the socket). Any subsequent WSPRecv call from the remote peer of the connection fails with WSAECONNRESET.

For more information about the procedure that a SAN service provider performs to close a socket, see Closing a SAN Socket.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.0.
Header	Ws2spi.h (include Ws2spi.h)

Share via