GetOverlappedResult
The GetOverlappedResult
function returns the results of an overlapped operation on the specified file,
named pipe, or communications device.
Windows
95: This function works only on
serial devices or on files opened by using the DeviceIoControl function.
BOOL GetOverlappedResult(
|
HANDLE hFile, |
// handle of file,
pipe, or communications device |
|
LPOVERLAPPED lpOverlapped, |
// address of
overlapped structure |
|
LPDWORD lpNumberOfBytesTransferred, |
// address of
actual bytes count |
|
BOOL bWait |
// wait flag |
|
); |
|
Parameters
hFile
Identifies
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
Points to an OVERLAPPED structure that was
specified when the overlapped operation was started.
lpNumberOfBytesTransferred
Points to a
32-bit 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
Specifies
whether the function should wait for the pending overlapped operation to be
completed. If TRUE, the function does not return until the operation has been
completed. If FALSE and the operation is still pending, the function returns
FALSE and the GetLastError function returns ERROR_IO_INCOMPLETE.
Return Values
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.
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 GetOverlappedResult. 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 GetOverlappedResult with the bWait
parameter set to TRUE causes the function to be blocked indefinitely.
See Also