创建和使用驱动程序创建的文件对象

警告

UMDF 2 是 UMDF 的最新版本,取代了 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 不会向 UMDF 1 添加任何新功能,并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 Windows 驱动程序必须使用 UMDF 2。

存档的 UMDF 1 示例可在 Windows 11 版本 22H2 - 2022 年 5 月驱动程序示例更新中找到。

有关详细信息,请参阅使用 UMDF 入门

如果驱动程序需要创建独立于应用程序的 I/O 请求并将其发送到堆栈中的下一个驱动程序 (默认 I/O 目标) ,则驱动程序必须创建并关闭其自己的文件对象。

创建文件对象

驱动程序必须调用 IWDFDevice::CreateWdfFile 方法来创建供驱动程序使用的文件对象。 当驱动程序调用 IWDFDevice::CreateWdfFile 时,框架会将创建请求发送到堆栈中的下一个驱动程序。 堆栈中的下一个驱动程序可能处于内核模式或用户模式。

此创建文件请求处理在 Windows 驱动程序模型 (WDM) 中有所不同。 在 WDM 中,对 ZwCreateFile 函数的调用会导致创建 IRP 转到内核模式堆栈的顶部。 下图显示了 UMDF 与 WDM 中的创建文件请求处理:

umdf 与 wdm 中的 create-file 请求处理。

通过调用 IWDFDevice::CreateWdfFile,驱动程序可以在整个堆栈启动之前创建文件对象,然后在设备启动期间发送 I/O 请求。

堆栈中的下一个驱动程序必须确定它是否可以处理 create-file 请求,或者它是否必须向堆栈向下转发请求。

调用 IWDFDevice::CreateWdfFile 后,驱动程序无法取消创建操作。

使用 File 对象

若要将异步读取请求发送到其下面的下一个驱动程序,驱动程序可以使用以下模式。

  1. 调用 IWDFDevice::CreateWdfFile 来创建文件对象。
  2. 调用 IWDFDevice::GetDefaultIoTarget 以检索表示较低级别驱动程序的接口。
  3. 调用 IWDFDevice::CreateRequest 来创建未格式化 的 IWDFIoRequest 对象。
  4. 调用 IWDFIoRequest::SetCompletionCallback 为框架在 I/O 请求完成时调用的 OnCompletion 方法注册 IRequestCallbackRequestCompletion 接口。
  5. 调用 IWDFIoTarget::FormatRequestForRead,提供指向 pFile 参数中的 IWDFDriverCreatedFile 接口的指针。
  6. 调用 IWDFIoRequest::Send 发送请求。

关闭文件对象

调用 IWDFDevice::CreateWdfFile 的驱动程序稍后必须调用 IWDFDriverCreatedFile::Close

通常,驱动程序从其 IPnpCallbackHardware::OnReleaseHardwareIPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup 回调方法调用 IWDFDriverCreatedFile::Close。

当驱动程序调用 IWDFDriverCreatedFile::Close 时,框架将调用下一个驱动程序的 IFileCallbackCleanup::OnCleanupFile 方法。 在此方法中,下一个驱动程序必须取消或完成与文件对象关联的所有挂起的 I/O 请求。 然后,框架会取消由调用 IWDFDevice::CreateWdfFile 的驱动程序创建的任何 I/O 请求。 框架不会取消堆栈中较低级驱动程序可能与文件对象关联的任何 I/O 请求。 司机有责任取消任何此类请求。 文件对象仅在完成与它关联的所有 I/O 请求后关闭。

接下来,框架调用下一个驱动程序的 IFileCallbackClose::OnCloseFile 方法。 此时,框架保证下一个驱动程序不会收到此文件对象的其他 I/O 请求。

框架调用 OnCloseFile 后,它会销毁表示文件对象的 IWDFFile 接口。

如果驱动程序创建的文件对象保留在驱动程序的设备删除方法 (例如 IPnpCallbackHardware::OnReleaseHardwareIPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup) 返回之后,框架将生成驱动程序停止。 有关解决此问题的信息,请参阅 确定为什么 UMDF 在设备删除时指示未完成的文件