WSACancelAsyncRequest()

Description

Cancel an incomplete asynchronous operation.

#include <winsock.h>

int PASCAL FAR WSACancelAsyncRequest ( HANDLE hAsyncTaskHandle );

hAsyncTaskHandle

Specifies the asynchronous operation to be canceled.

Remarks

The WSACancelAsyncRequest() function is used to cancel an asynchronous operation which 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 function. Return Value The value returned by WSACancelAsyncRequest() is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

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

Notes For Windows Sockets Suppliers

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: 0 is always an invalid asynchronous task handle.∙ The Windows Sockets specification does not prescribe how a conformant Windows Sockets implementation should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the two errors as equivalent.

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.
WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL
Indicates that the specified asynchronous task handle was invalid
WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.
WSAEALREADY
The asynchronous routine being canceled has already completed.

See Also

WSAAsyncGetHostByAddr(), WSAAsyncGetHostByName(), WSAAsyncGetProtoByNumber(), WSAAsyncGetProtoByName(), WSAAsyncGetHostByName(), WSAAsyncGetServByPort(), WSAAsyncGetServByName()

---

[Back: WSAAsyncSelect()]
[Next: WSACancelBlockingCall()]