OVERLAPPED structure and GetOverlappedResult function

When asynchronous I/O calls, we use the overlapped structure and functionsGetOverlappedResult。 had been toGetOverlappedResultMore confused, the two days of reading and code to know that the main function of the functions is simply a simple analysis of the results returned by overlapped.

Here is the structure definition for overlapped:
typedef struct _OVERLAPPED {
DWORD Internal;
DWORD Internalhigh;
DWORD Offset;
DWORD Offsethigh;
HANDLE hevent;
} OVERLAPPED;
The internal and internalhigh in this structure are two return values. The person who wrote the driver knows that the two values correspond to the IO_STATUS_BLOCK structure of the IRP:
typedef struct _IO_STATUS_BLOCK {
Union {
NTSTATUS Status;
PVOID Pointer;
};
ULONG_PTR Information;
} Io_status_block, *pio_status_block;

Where internal is the value of status, Internalhigh is the value of information. The word "Internal" indicates that the two value was used internally by Ms.
And how does the ordinary caller know what it means?
1. When the call returns (with ReadFile example):
If internal=0 indicates that the return status_success is returned, ReadFile returns True, which is the successful return, and the Internalhigh value is saved in lpnumberofbytestransferred.
If internal!=0 indicates an error or pending, then ReadFile returns False, and the GetLastError value is the internal value.

2. When returning error_io_pending in 1:
It's going to take a while.GetOverlappedResultThe
If internal=0 indicates return status_success, thenGetOverlappedResultReturns True, which is a successful return; the value of Internalhigh is saved in lpnumberofbytestransferred.
If internal!=0 indicates that an error occurred, thenGetOverlappedResultReturns FALSE, GetLastError value is the internal value.


Attached Source:
Windows_2000_source_code\win2k\private\windows\base\client\error.c

BOOL
WINAPI
GetOverlappedResult(
HANDLE hfile,
lpoverlapped lpoverlapped,
Lpdword lpnumberofbytestransferred,
BOOL bwait
)

/*++

Routine Description:

TheGetOverlappedResultfunction returns the last of the result
Operation that used lpoverlapped and returned error_io_pending.

Arguments:

Hfile-supplies The open handle to the file, the overlapped
Structure Lpoverlapped was supplied to ReadFile, WriteFile,
Connectnamedpipe, Waitnamedpipe or Transactnamedpipe.

Lpoverlapped-points to a OVERLAPPED structure previously supplied to
ReadFile, WriteFile, Connectnamedpipe, Waitnamedpipe or
Transactnamedpipe.
This address is the value of the argument that was passed when the ReadFile was called, and must be remembered correctly.

Lpnumberofbytestransferred-returns the number of bytes transferred
By the operation.

Bwait-a Boolean value affects the behavior when the operation
is still in progress. If TRUE and the operation is still in progress,
GetOverlappedResult'll wait for the operation to complete before
Returning. If FALSE and the operation is incomplete,
GetOverlappedResultwould return FALSE. The extended
Error information available from the GetLastError function would be
Set to Error_io_incomplete.
If the current or error_io_pending, then determine whether the need to wait indefinitely.

Return Value:

TRUE--The operation was successful, the pipe are in the
Connected state.

FALSE--the operation failed. Extended error status is available using
GetLastError.

--*/

[HTML]View PlainCopyprint?

2. {
4. DWORD Waitreturn;
8. //
10. Did caller specify a event to the original operation or is the
12. Default (file handle) used?
14. //
18. if (lpoverlapped->Internal = = (DWORD) status_pending) {
20. if (bwait) {
22. //
24. It's still pending, and waiting, waiting indefinitely.
26. Many people will call WaitForSingleObject themselves and then call GetOverlappedResult, which actually looks
28. There is not much need.
30. //
32. Waitreturn = WaitForSingleObject (
34. (lpoverlapped->hevent! = NULL)?
36. lpoverlapped->hevent:hfile,
38. INFINITE
40. );
42. }
44. else {
46. Waitreturn = wait_timeout;
48. }
52. if ( Waitreturn = = wait_timeout) {
54. !bwait and event in not signalled state
56. SetLastError (Error_io_incomplete);
58. return FALSE;
60. }
64. if (Waitreturn! = 0) {
66. return FALSE; WaitForSingleObject calls Basesetlasterror
68. }
70. }
74. *lpnumberofbytestransferred = (DWORD) lpoverlapped->InternalHigh;
78. if (Nt_success ((NTSTATUS) lpoverlapped->internal)) {
80. return TRUE;
82. }
84. else {
86. Basesetlastnterror ((NTSTATUS) lpoverlapped->internal);
88. return FALSE;
90. }
92. }

Added: (2009-10-8)

"Windows core Programming" (version 5th), p293.

---------------

Internal member: The error code that this member uses to hold the processed I/O request.

Internalhigh Member: This member is used to hold the number of bytes transferred when an asynchronous I/O request is completed.

At the time the overlapped structure was designed, Microsoft decided not to disclose the internal and Internalhigh members (literally). Over time, Microsoft recognizes that the information that these members contain is useful to developers, and therefore exposes them. However, Microsoft has not changed the names of these members because the operating system's source code frequently uses them, and Microsoft does not want to modify the source for this purpose.

-------

Because Microsoft exposes these members, we do not necessarily see the need for GetOverlappedResult . ：）

OVERLAPPED structure and GetOverlappedResult functions