Edit

Sending I/O Requests to a General I/O Target in UMDF

  • Article

Warning

UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2.

The archived UMDF 1 samples can be found in the Windows 11, version 22H2 - May 2022 Driver Samples Update.

For more info, see Getting Started with UMDF.

A UMDF driver can send I/O requests to general I/O targets either synchronously or asynchronously.

If a driver sends I/O requests synchronously, a driver thread sends the requests one at a time. The thread waits for each request to complete before it sends the next one. This process is simpler than sending the I/O requests asynchronously. The driver can send I/O requests synchronously if it does not send many requests and if system or device performance is not reduced while the driver waits for each I/O request.

If a driver sends I/O requests asynchronously, a driver thread sends each request as soon as the request is ready to be sent, without waiting for previously sent requests to finish. If the driver must handle many I/O requests in short periods of time, the driver probably cannot wait for each request to complete before sending the next request. Otherwise, the driver might lose data or the performance of its devices and, possibly, of the entire system might be reduced.

Before a UMDF driver can send an I/O request to an I/O target, the driver must format the request. The following table lists the methods that the driver can call to format I/O requests. The driver can use these methods to format a request that the driver received in one of its I/O queues or that the driver created.

Method Purpose

IWDFIoRequest::FormatUsingCurrentType

Formats a request that the driver received from the framework so that the driver can send the request, unmodified, to the target

IWDFIoTarget::FormatRequestForIoctl

Formats a device control request

IWDFIoTarget::FormatRequestForRead

Formats a read request

IWDFIoTarget::FormatRequestForWrite

Formats a write request

IWDFIoTarget2::FormatRequestForFlush

Formats a request to flush buffers.

IWDFIoTarget2::FormatRequestForQueryInformation

Formats a request to obtain file information.

IWDFIoTarget2::FormatRequestForSetInformation

Formats a request to set file information.

To send the I/O request to the I/O target, the driver calls the IWDFIoRequest::Send method. To send the I/O request synchronously, the driver passes the WDF_REQUEST_SEND_OPTION_SYNCHRONOUS flag to the Flags parameter. Otherwise, the driver sends the I/O request asynchronously. If the driver sends the I/O request asynchronously, the driver typically requires notification when another driver completes the request. The driver should define a IRequestCallbackRequestCompletion::OnCompletion callback function and register it by calling the IWDFIoRequest::SetCompletionCallback method. For more information, see Completing I/O Requests.

A driver that calls IWDFIoRequest::Send to send an I/O request can attempt to cancel the request later by calling the IWDFIoRequest::CancelSentRequest method. If the driver cancels an I/O request that the driver received from the framework, the driver must always complete the request by calling the IWDFIoRequest::Complete or IWDFIoRequest::CompleteWithInformation method with the CompletionStatus parameter set to STATUS_CANCELLED. If the driver created the request object, the driver calls IWDFObject::DeleteWdfObject instead of completing the request.