WSACancelAsyncRequest (Compact 2013)
3/26/2014
This function cancels an incomplete asynchronous operation.
Syntax
int WSACancelAsyncRequest(_in_ HANDLEhAsyncTaskHandle);
Parameters
- hAsyncTaskHandle
[in] Handle that specifies the asynchronous operation to be canceled.
Return Value
The value returned by WSACancelAsyncRequest is 0 (zero) if the operation was successfully canceled. Otherwise, the value SOCKET_ERROR is returned. You can retrieve a specific error number by calling WSAGetLastError.
Exceptions
The following error codes can occur if the function does not succeed.
Error Code |
Meaning |
|---|---|
WSANOTINITIALISED |
A successful WSAStartup call must occur before using this function. |
WSAENETDOWN |
The network subsystem has failed. |
WSAEINVAL |
The specified asynchronous task handle was invalid. |
WSAEINPROGRESS |
A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function. |
WSAEALREADY |
The asynchronous routine being canceled has already finished. |
Remarks
Note that there is a case where the application cannot usefully distinguish between the error codes WSAEINVAL and WSAEALREADY when no asynchronous operation is in progress with the indicated handle (there is a trivial exception: 0 (zero) is always an invalid asynchronous task handle). The Windows Sockets specification does not prescribe how a conformant Windows Sockets provider will distinguish between the two cases. For maximum portability, a Windows Sockets application can treat the two errors as equivalent.
The WSACancelAsyncRequest function is used to cancel an asynchronous operation that was initiated by a function such as WSAAsyncGetHostByName. The operation to be canceled is identified by the hAsyncTaskHandle parameter, which is set to the asynchronous task handle as returned by the initiating function. An attempt to cancel an existing asynchronous operation can fail with an error code of WSAEALREADY for two reasons. First, the original operation has already finished and the application has dealt with the resulting message. Second, the original operation has already finished but the resulting message is still waiting in the application window queue.
See Also
Reference
Windows-Specific Extension Functions
WSAStartup
WSAAsyncGetHostByName