GetOverlappedResultEx function (ioapiset.h)

Retrieves the results of an overlapped operation on the specified file, named pipe, or communications device within the specified time-out interval. The calling thread can perform an alertable wait.

Syntax

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Parameters

[in] hFile

A handle to the file, named pipe, or communications device. This is the same handle that was specified when the overlapped operation was started by a call to the ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl, or WaitCommEvent function.

[in] lpOverlapped

A pointer to an OVERLAPPED structure that was specified when the overlapped operation was started.

[out] lpNumberOfBytesTransferred

A pointer to a variable that receives the number of bytes that were actually transferred by a read or write operation. For a TransactNamedPipe operation, this is the number of bytes that were read from the pipe. For a DeviceIoControl operation, this is the number of bytes of output data returned by the device driver. For a ConnectNamedPipe or WaitCommEvent operation, this value is undefined.

[in] dwMilliseconds

The time-out interval, in milliseconds.

If dwMilliseconds is zero and the operation is still in progress, the function returns immediately and the GetLastError function returns ERROR_IO_INCOMPLETE.

If dwMilliseconds is nonzero and the operation is still in progress, the function waits until the object is signaled, an I/O completion routine or APC is queued, or the interval elapses before returning. Use GetLastError to get extended error information.

If dwMilliseconds is INFINITE, the function returns only when the object is signaled or an I/O completion routine or APC is queued.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 and Windows Server 2008 R2: The dwMilliseconds value includes time spent in low-power states. For example, the timeout continues counting down while the computer is asleep.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 and Windows Server 2016: The dwMilliseconds value does not include time spent in low-power states. For example, the timeout does not continue counting down while the computer is asleep.

[in] bAlertable

If this parameter is TRUE and the calling thread is in the waiting state, the function returns when the system queues an I/O completion routine or APC. The calling thread then runs the routine or function. Otherwise, the function does not return, and the completion routine or APC function is not executed.

A completion routine is queued when the ReadFileEx or WriteFileEx function in which it was specified has completed. The function returns and the completion routine is called only if bAlertable is TRUE, and the calling thread is the thread that initiated the read or write operation. An APC is queued when you call QueueUserAPC.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Common error codes include the following:

• If dwMilliseconds is zero and the operation is still in progress, GetLastError returns ERROR_IO_INCOMPLETE.
• If dwMilliseconds is nonzero, and an I/O completion routine or APC is queued, GetLastError returns WAIT_IO_COMPLETION.
• If dwMilliseconds is nonzero and the specified timeout interval elapses, GetLastError returns WAIT_TIMEOUT.

Remarks

The GetOverlappedResultEx function differs from GetOverlappedResult in the following ways: The dwMilliseconds parameter can specify a timeout interval for the operation, and the bAlertable parameter can specify that the calling thread should perform an alertable wait.

The results reported by the GetOverlappedResultEx function are those of the specified handle's last overlapped operation to which the specified OVERLAPPED structure was provided, and for which the operation's results were pending. A pending operation is indicated when the function that started the operation returns FALSE, and the GetLastError function returns ERROR_IO_PENDING. When an I/O operation is pending, the function that started the operation resets the hEvent member of the OVERLAPPED structure to the nonsignaled state. Then when the pending operation has been completed, the system sets the event object to the signaled state.

Specify a manual-reset event object in the OVERLAPPED structure. If an auto-reset event object is used, the event handle must not be specified in any other wait operation in the interval between starting the overlapped operation and the call to GetOverlappedResultEx. For example, the event object is sometimes specified in one of the wait functions to wait for the operation's completion. When the wait function returns, the system sets an auto-reset event's state to nonsignaled, and a subsequent call to GetOverlappedResultEx with the dwMilliseconds parameter set to INFINITE causes the function to be blocked indefinitely.

If the hEvent member of the OVERLAPPED structure is NULL, the system uses the state of the hFile handle to signal when the operation has been completed. Use of file, named pipe, or communications-device handles for this purpose is discouraged. It is safer to use an event object because of the confusion that can occur when multiple simultaneous overlapped operations are performed on the same file, named pipe, or communications device. In this situation, there is no way to know which operation caused the object's state to be signaled.

Requirements

See also

CancelIo

ConnectNamedPipe

CreateEvent

DeviceIoControl

GetLastError

GetOverlappedResult

OVERLAPPED

Overlapped Input and Output

ReadFile

Synchronization Functions

TransactNamedPipe

WaitCommEvent

WriteFile