CancelIoEx function

Marks any outstanding I/O operations for the specified file handle. The function only cancels I/O operations in the current process, regardless of which thread created the I/O operation.

Syntax

BOOL WINAPI CancelIoEx(
  _In_     HANDLE       hFile,
  _In_opt_ LPOVERLAPPED lpOverlapped
);

Parameters

hFile [in]

A handle to the file.

lpOverlapped [in, optional]

A pointer to an OVERLAPPED data structure that contains the data used for asynchronous I/O.

If this parameter is NULL, all I/O requests for the hFile parameter are canceled.

If this parameter is not NULL, only those specific I/O requests that were issued for the file with the specified lpOverlapped overlapped structure are marked as canceled, meaning that you can cancel one or more requests, while the CancelIo function cancels all outstanding requests on a file handle.

Return value

If the function succeeds, the return value is nonzero. The cancel operation for all pending I/O operations issued by the calling process for the specified file handle was successfully requested. The application must not free or reuse the OVERLAPPED structure associated with the canceled I/O operations until they have completed. The thread can use the GetOverlappedResult function to determine when the I/O operations themselves have been completed.

If the function fails, the return value is 0 (zero). To get extended error information, call the GetLastError function.

If this function cannot find a request to cancel, the return value is 0 (zero), and GetLastError returns ERROR_NOT_FOUND.

Remarks

The CancelIoEx function allows you to cancel requests in threads other than the calling thread. The CancelIo function only cancels requests in the same thread that called the CancelIo function. CancelIoEx cancels only outstanding I/O on the handle, it does not change the state of the handle; this means that you cannot rely on the state of the handle because you cannot know whether the operation was completed successfully or canceled.

If there are any pending I/O operations in progress for the specified file handle, the CancelIoEx function marks them for cancellation. Most types of operations can be canceled immediately; other operations can continue toward completion before they are actually canceled and the caller is notified. The CancelIoEx function does not wait for all canceled operations to complete.

If the file handle is associated with a completion port, an I/O completion packet is not queued to the port if a synchronous operation is successfully canceled. For asynchronous operations still pending, the cancel operation will queue an I/O completion packet.

The operation being canceled is completed with one of three statuses; you must check the completion status to determine the completion state. The three statuses are:

• The operation completed normally. This can occur even if the operation was canceled, because the cancel request might not have been submitted in time to cancel the operation.
• The operation was canceled. The GetLastError function returns ERROR_OPERATION_ABORTED.
• The operation failed with another error. The GetLastError function returns the relevant error code.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Requirements

See also

CancelIo

CancelSynchronousIo

Canceling Pending I/O Operations

File Management Functions

Synchronous and Asynchronous I/O