INFO: How Drivers Notify User-Mode Apps of Asynchronous Events

Last reviewed: February 17, 1998
Article ID: Q117308

The information in this article applies to:
  • Microsoft Win32 Device Development Kit (DDK) for Windows NT, versions 3.1, 3.5, 3.51

SUMMARY

In Windows NT, a kernel-mode driver cannot call back into a user-mode application. This is by design. For a driver to notify the application for an asynchronous event, the application needs to keep an I/O request pending with the driver at all times so that the driver can complete the request each time the event occurs. This article outlines a typical scheme that an application and a driver can use to accomplish asynchronous notification.

MORE INFORMATION

The Application

The application can have a dedicated input thread. The thread goes into a loop that sends an I/O request and waits for response. If the driver has been opened and a handle, hDevice, is obtained, the loop can look like the following:

   while (!ApplicationExiting) {
   
      returnval = DeviceIoControl (hDevice, dwIoControlCode,
                            lpvInBuffer, cbInBuffer, lpvOutBuffer,
                            cbOutBuffer, lpcbBytesReturned, lpoOverlapped);
           if (!returnval && (GetLastError() == ERROR_IO_PENDING)) {
            WaitForSingleObject (hEvent, INFINITE) // hEvent is located in
   overlapped structure as well
         ... // Code to do action
         ResetEvent (hEvent)
      }
      { ... // Code to handle other situations }
   }

The BOOL type, ApplicationExiting(), represents the condition for which the loop should stop checking for events. The main thread of the application can set this BOOL to TRUE when it is time to quit. The I/O control code, dwIoControlCode(), is defined by the driver.

The above DeviceIoControl call must be made asynchronously in order for the other application threads to be able to continue to send requests to the driver while this request is pending. The event that was initialized and placed in the overlapped structure of the DeviceIoControl call can be used to make this thread synchronous with the completion of the request. Once that event has been satisfied, this thread can notify the other application threads that the event has signaled. If the overlapped structure is not specified, all other threads will be blocked while this request is processed in the driver. The other threads will not be released until the synchronous DeviceIoControl has been completed.

The user-mode thread can also use ReadFile() or ReadFileEx() instead of DeviceIoControl() if the driver uses a read request to send in an asynchronous event notification.

The Driver

The driver should not complete the I/O request until an event has occurred. When the driver receives the I/O request, if an event has occurred and is waiting to be sent to the application, the driver can complete the request in the dispatch routine. If no event is waiting to be reported, the driver should perform the following steps:

  1. Mark the Irp pending, using IoMarkIrpPending().

  2. Set up a cancel routine for the Irp, using IoSetCancelRoutine().

  3. Put the Irp in a storing place (a queue for example).

  4. Return STATUS_PENDING from the dispatch routine.

Later, when an event has occurred, the driver can complete the pending request from its deferred procedure call (DPC) routine. Before the Irp can be completed, the driver should set the cancel routine address to NULL using IoSetCancelRoutine.
Version           : WINNT: 3.1,3.5,3.51;
Platform          : winnt
Issue type        : kbinfo


================================================================================


THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: February 17, 1998
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.