WSPCancelBlockingCall

The WSPCancelBlockingCall function cancels a blocking call that is currently in progress.

int WSPCancelBlockingCall (
  LPINT   lpErrno  
);

Parameters

lpErrno

[out] Pointer to the error code.

Return Values

The value returned by WSPCancelBlockingCall is zero if the operation was successfully canceled. Otherwise, the value SOCKET_ERROR is returned, and a specific error code is available in lpErrno.

Remarks

This function cancels any outstanding blocking operation for this thread. It is typically used in two situations:

• A Windows Sockets SPI client is processing a message that has been received while a service provider is implementing pseudo blocking. In this case, WSAIsBlocking will be true.
• A blocking call is in progress and the Windows Sockets service provider has called back to the Windows Sockets SPI client's blocking hook function (through the callback function retrieved from WPUQueryBlockingCallback), which in turn is invoking this function. Such a situation might arise, for instance, in implementing a Cancel option for an operation that requires an extended time to complete.

In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. (In the first instance the termination will not take place until Windows message scheduling has caused control to revert back to the pseudo blocking routine in Windows Sockets. In the second instance, the blocking call will be terminated as soon as the blocking hook function completes.)

In the case of a blocking WSPConnect operation, Windows Sockets will terminate the blocking call as soon as possible, but it cannot be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the Windows Sockets SPI client immediately tries to open a new socket (if no sockets are available), or to connect to the same peer through a WSPConnect call.

Canceling a WSPAccept or a WSPSelect call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal before the cancel is legal after the cancel, and the state of the socket is not affected in any way.

Canceling any operation other than WSPAccept and WSPSelect can leave the socket in an indeterminate state. If a Windows Sockets SPI client cancels a blocking operation on a socket, the only operation the Windows Sockets SPI client will be able to perform on the socket is a call to WSPCloseSocket, although other operations can work on some Windows Sockets service providers. If a Windows Sockets SPI client requires maximum portability, it must be careful not to depend on performing operations after a cancel operation. A Windows Sockets SPI client can reset the connection by setting the time-out on SO_LINGER to zero and calling WSPCloseSocket.

If a cancel operation compromised the integrity of a SOCK_STREAM's data stream in any way, the Windows Sockets provider will reset the connection and fail all future operations other than WSPCloseSocket with WSAECONNABORTED.

Remarks

It is acceptable for WSPCancelBlockingCall to return successfully if the blocking network operation completes prior to being canceled. In this case, the blocking operation will return successfully as if WSPCancelBlockingCall had never been called. The only way for the Windows Sockets SPI client to know with certainty that an operation was actually canceled is to check for a return code of WSAEINTR from the blocking call.

Error Codes

Requirements

  Version: Requires Windows Sockets 2.0.
  Header: Declared in Ws2spi.h.