Edit

Share via

WSACancelAsyncRequest function (winsock2.h)

  • Article

The WSACancelAsyncRequest function cancels an incomplete asynchronous operation.

Syntax

int WSAAPI WSACancelAsyncRequest(
  [in] HANDLE hAsyncTaskHandle
);

Parameters

[in] hAsyncTaskHandle

Handle that specifies the asynchronous operation to be canceled.

Return value

The value returned by WSACancelAsyncRequest is zero if the operation was successfully canceled. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.

Error code Meaning
WSANOTINITIALISED
 A successful WSAStartup call must occur before using this function.
WSAENETDOWN
 The network subsystem has failed.
WSAEINVAL
 Indicates that 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 completed.
 
Note  It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is no asynchronous operation in progress with the indicated handle. (Trivial exception: zero is always an invalid asynchronous task handle.) The Windows Sockets specification does not prescribe how a conformant Windows Sockets provider should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the two errors as equivalent.
 

Remarks

The WSACancelAsyncRequest function is used to cancel an asynchronous operation that was initiated by one of the WSAAsyncGetXByY functions such as WSAAsyncGetHostByName. The operation to be canceled is identified by the hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating WSAAsyncGetXByY function.

An attempt to cancel an existing asynchronous WSAAsyncGetXByY operation can fail with an error code of WSAEALREADY for two reasons. First, the original operation has already completed and the application has dealt with the resultant message. Second, the original operation has already completed but the resultant message is still waiting in the application window queue.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winsock2.h (include Winsock2.h)
Library Ws2_32.lib
DLL Ws2_32.dll

See also

WSAAsyncGetHostByAddr

WSAAsyncGetHostByName

WSAAsyncGetProtoByName

WSAAsyncGetProtoByNumber

WSAAsyncGetServByName

WSAAsyncGetServByPort

Winsock Functions

Winsock Reference