Applies to: desktop apps only
Retrieves the results of an overlapped operation on the specified file, named pipe, or communications device. To specify a timeout interval or wait on an alertable thread, use GetOverlappedResultEx.
Syntax
BOOL WINAPI GetOverlappedResult( __in HANDLE hFile, __in LPOVERLAPPED lpOverlapped, __out LPDWORD lpNumberOfBytesTransferred, __in BOOL bWait );
Parameters
- hFile [in]
-
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.
- lpOverlapped [in]
-
A pointer to an OVERLAPPED structure that was specified when the overlapped operation was started.
- lpNumberOfBytesTransferred [out]
-
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.
- bWait [in]
-
If this parameter is TRUE, and the Internal member of the lpOverlapped structure is STATUS_PENDING, the function does not return until the operation has been completed. If this parameter is FALSE and the operation is still pending, the function returns FALSE and the GetLastError function returns ERROR_IO_INCOMPLETE.
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.
Remarks
The results reported by the GetOverlappedResult 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.
If the bWait parameter is TRUE, GetOverlappedResult determines whether the pending operation has been completed by waiting for the event object to be in the signaled state.
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.
Examples
For an example that uses GetOverlappedResult, see Testing for the End of a File.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- CancelIo
- ConnectNamedPipe
- CreateEvent
- DeviceIoControl
- GetLastError
- GetOverlappedResultEx
- OVERLAPPED
- Overlapped Input and Output
- ReadFile
- Synchronization Functions
- TransactNamedPipe
- WaitCommEvent
- WriteFile
Send comments about this topic to Microsoft
Build date: 3/7/2012
What we are seeing however with using a real 16550 serial port that when ReadFile returns success which means the GetOverlappedResult call isn't needed, the number of bytes read is sometimes set to zero despite the correct requested bytes were actually read to the buffer. It seems the safest course of action is to simply not rely on the number of bytes read value if the operation occurred without error from either ReadFile or GetOverlappedResult.
When this happens the expected bytes are present in the buffer from the ReadFile operation which is expected since a success result from GetOverlappedResult with bWait set to true should only be possible if the entire read operation finished. The only workaround for this is to simply assume all bytes were transferred when GetOverlappedResult return success.
This issue could be problematic in cases where bWait is false and transfer progress is being tracked.
If ReadFile returns TRUE, then lpNumberOfBytesRead from ReadFile is the value to use. If ReadFile returns FALSE, GetLastError returns ERROR_IO_PENDING, and GetOverlappedResult returns TRUE, then lpNumberOfBytesTransferred from GetOverlappedResult is the value to use.
The value returned in lpNumberOfBytesWritten is indeterminate. Use the GetOverlappedResult function to get the actual number of bytes read.Note: An overlapped ReadFile can also complete immediately (return value TRUE).
The above GetOverlappedResult documentation states:
The results reported by the GetOverlappedResult 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.My problem:
- If ReadFile is invoked with an OVERLAPPED structure, the value for "returned number of bytes" is invalid.
- But if ReadFile completes immediately, the GetOverlappedResult function result is not defined, too. (There was no pending operation.)
(Also we observed that using an USB pipe, GetOverlappedResult never blocks, even if the last parameter is set to TRUE, and even if the event is explicitly cleared with ResetEvent immediately before calling GetOverlappedResult. Why?)