Share via

WSACancelAsyncRequest (Compact 2013)

  • Article

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