WSPCancelBlockingCall

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

int WSPCancelBlockingCall (
  LPINT lpErrno  
);
 

Parameters

lpErrno

[out] A pointer to the error code.

Remarks

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

1. A Windows Sockets SPI client is processing a message which has been received while a service provider is implementing pseudo blocking. In this case, WSAIsBlocking will be true.
2. 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 which require an extended time to complete.

In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. (In (1), 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 (2), 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 WSPConnect to the same peer.

Canceling an 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 that the Windows Sockets SPI client can depend on being 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. 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.

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.

Comments

Note 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

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Unsupported.
  Header: Declared in ws2spi.h.