Driver-Created Versus Application-Created File Objects

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.

When an application opens a handle to a device, the framework calls your driver's IQueueCallbackCreate::OnCreateFile method and supplies a pointer to the IWDFFile interface for the file object that is associated with the device. Any I/O requests that the application sends to the opened handle are associated with the created file object. When such requests arrive, the framework calls the appropriate method from one of the driver-supplied UMDF Queue Object Interfaces. The driver can then call IWDFIoRequest::GetFileObject to determine the file object associated with the request. The driver can call AssignContext on the file object to associate context that is specific to the I/O session.

The following table shows calls the application makes and the resulting notifications that the driver receives.

Application initiates	Driver receives
A call to the Microsoft Win32 CreateFile function.	A call to its IQueueCallbackCreate::OnCreateFile method.
A call to the Win32 ReadFileEx, WriteFileEx, or DeviceIoControl function.	A call to its IQueueCallbackRead::OnRead, IQueueCallbackWrite::OnWrite, or IQueueCallbackDeviceIoControl::OnDeviceIoControl method.
A call to the Win32 CloseHandle function for the last open handle to the file object.	A call to its IFileCallbackCleanup::OnCleanupFile method. The driver cancels or completes all I/O requests that are associated with the file object. After the driver returns from the cleanup notification, UMDF cancels any pending I/O requests. After cleanup completes and UMDF cancels pending I/O requests, the driver receives a call to its IFileCallbackClose::OnCloseFile method.

A system component may issue a create request on behalf of a Universal Windows app. If the driver needs to determine the process ID of the app that issued the create request, it can call the IWDFFile3::GetInitiatorProcessId method.

Driver-created file objects

If your driver needs to create and send an I/O request independent of the application to the next driver in the stack (the default I/O target), the driver must call IWDFDevice::CreateWdfFile to retrieve a pointer to a IWDFDriverCreatedFile interface. In this case, the next driver receives the same notifications that your driver receives when the application generates the request.

The following table shows calls your driver makes and the resulting notifications to the next driver in the stack.

Driver initiates	Next driver in the stack receives
A call to the IWDFDevice::CreateWdfFile method. The file object that UMDF creates represents an I/O session between the device and the next device in the stack.	A call to its IQueueCallbackCreate::OnCreateFile method.
A call to the IWDFDevice::CreateRequest method. A call to format the request (for example, a call to the IWDFIoTarget::FormatRequestForIoctl method). A call to the IWDFIoRequest::Send method.	A call to its IQueueCallbackRead::OnRead, IQueueCallbackWrite::OnWrite, or IQueueCallbackDeviceIoControl::OnDeviceIoControl method.
A call to the IWDFDriverCreatedFile::Close method.	A call to its IFileCallbackCleanup::OnCleanupFile method. The driver cancels or completes all I/O requests that are associated with the file object. After the driver returns from the cleanup notification, UMDF cancels any pending I/O requests. After cleanup completes and UMDF cancels pending I/O requests, the driver receives a call to its IFileCallbackClose::OnCloseFile method.

For the next device in the stack, no difference exists between the file object that is created by an application and the file object that is created by a higher-layer device.