DOCERR: DeviceIoControl Requires OVERLAPPED Struct w/ Async. (126282)

This article was previously published under Q126282

The documentation for DeviceIoControl is incomplete. It should warn you that unexpected behavior may occur when both the following are true:

• A DeviceIoControl request is followed by another DeviceIoControl request on the same handle.
• There was no OVERLAPPED structure passed into DeviceIoControl after the handle to the device or file was opened with FILE_FLAG_OVERLAPPED.

The following is a list of some of the unexpected behavior that may occur:

• Requests complete before expected.
• There's undefined data in the returned buffers.
• Unknown error codes are returned.
• IRPs are held in a driver while the DeviceIoControl call has already returned.

When a handle is requested to a driver or file with FILE_FLAG_OVERLAPPED specified, the executive prepares itself for all requests on that handle to be asynchronous. Usually, when the request is sent down with an OVERLAPPED structure, an event is placed in that OVERLAPPED structure. This event is then stored in the FILE_OBJECT in kernel mode to use later to signal the user-mode application when that IRP has been completed. If an event is not specified, the value will be 0 in the FILE_OBJECT, when a second request is sent down before the first request completes (and completes), the IO manager will not have separate signals for the completion of the requests. Therefore, the request will appear to be completed, while in reality the IRP has not been completed by the underlying driver.

Please see the current documentation of GetOverlappedResult for more information on the behavior of the executive when no OVERLAPPED structure is specified when the handle to the driver or file was opened with FILE_FLAG_OVERLAPPED.