Edit

Framework File Object

  • 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.

The framework file object is exposed to drivers by the IWDFFile interface. It is the framework representation of the opened device. When an application opens the device through the Microsoft Win32 CreateFile function, the framework creates a file object to represent the opened device instance. Therefore, the framework file object is conceptually equivalent to the Win32 handle that is returned from the application's call to CreateFile. The framework can create multiple file objects associated with a single device. Each file object is created for each successful call to CreateFile. All I/O operations, like reads and writes, are targeted to a specific file-object instance.

Note   All requests passed to UMDF drivers are associated with file objects. However, requests that are passed to WDM and KMDF drivers are sometimes not associated with file objects.

A UMDF driver can call the IWDFIoRequest::GetFileObject method to obtain the file object associated with a request.

When your driver calls GetFileObject, the framework increments the reference count on the interface. Your driver is responsible for releasing the reference when finished with the interface pointer. To do so, either use a smart pointer that automatically decrements the reference count when the object goes out of context, or call Release on the interface when finished with it. For a code example that shows how to use a smart pointer, see GetFileObject.