WDF_IO_TARGET_OPEN_PARAMS 结构 (wdfiotarget.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WDF_IO_TARGET_OPEN_PARAMS 结构包含 WdfIoTargetOpen 方法使用的参数。

语法

typedef struct _WDF_IO_TARGET_OPEN_PARAMS {
  ULONG                             Size;
  WDF_IO_TARGET_OPEN_TYPE           Type;
  PFN_WDF_IO_TARGET_QUERY_REMOVE    EvtIoTargetQueryRemove;
  PFN_WDF_IO_TARGET_REMOVE_CANCELED EvtIoTargetRemoveCanceled;
  PFN_WDF_IO_TARGET_REMOVE_COMPLETE EvtIoTargetRemoveComplete;
  PDEVICE_OBJECT                    TargetDeviceObject;
  PFILE_OBJECT                      TargetFileObject;
  UNICODE_STRING                    TargetDeviceName;
  ACCESS_MASK                       DesiredAccess;
  ULONG                             ShareAccess;
  ULONG                             FileAttributes;
  ULONG                             CreateDisposition;
  ULONG                             CreateOptions;
  PVOID                             EaBuffer;
  ULONG                             EaBufferLength;
  PLONGLONG                         AllocationSize;
  ULONG                             FileInformation;
  UNICODE_STRING                    FileName;
} WDF_IO_TARGET_OPEN_PARAMS, *PWDF_IO_TARGET_OPEN_PARAMS;

成员

Size

此结构的大小（以字节为单位）。

Type

一个WDF_IO_TARGET_OPEN_TYPE类型的值，指示 WdfIoTargetOpen 将执行的打开操作的类型。

EvtIoTargetQueryRemove

指向驱动程序的 EvtIoTargetQueryRemove 事件回调函数或 NULL 的指针。

EvtIoTargetRemoveCanceled

指向驱动程序的 EvtIoTargetRemoveCanceled 事件回调函数的指针，或 NULL。

EvtIoTargetRemoveComplete

指向驱动程序的 EvtIoTargetRemoveComplete 事件回调函数或 NULL 的指针。

TargetDeviceObject

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenUseExistingDevice，则这是指向表示 I/O 目标设备的 DEVICE_OBJECT 结构的指针。如果 Type 的值不是 WdfIoTargetOpenUseExistingDevice，则忽略此成员。

TargetFileObject

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenUseExistingDevice，则这是指向 FILE_OBJECT 结构的指针。此结构包含在驱动程序发送到 I/O 目标的所有 I/O 请求中 (请参阅 WdfRequestGetFileObject) 。此成员是可选的，可以为 NULL。如果 Type 的值不是 WdfIoTargetOpenUseExistingDevice，则忽略此成员。

TargetDeviceName

如果 Type 的值为 WdfIoTargetOpenByName，则这是一个包含设备、文件或设备接口名称的UNICODE_STRING 结构。有关此名称的格式的信息，请参阅对象名称。

如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

DesiredAccess

如果 Type 的值为 WdfIoTargetOpenByName，则这是一个ACCESS_MASK 值。

如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

KMDF 可能的值包括FILE_Xxxx_ACCESS值，例如FILE_ANY_ACCESS、FILE_SPECIAL_ACCESS、FILE_READ_ACCESS或FILE_WRITE_ACCESS，以及GENERIC_READ、GENERIC_WRITE和GENERIC_ALL。

UMDF 最常用的值是GENERIC_READ和/或GENERIC_WRITE (GENERIC_READ |GENERIC_WRITE) 。请注意，ACCESS_MASK 是一个 DWORD 值。有关此成员的详细信息，请参阅 Windows SDK 中 CreateFile 的 dwDesiredAccess 参数。

ShareAccess

如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则这是 Wdm.h) 中定义的以下标志 (的按位 OR 或零。

ShareAccess 标志	含义
FILE_SHARE_READ	驱动程序不需要对设备具有独占读取访问权限。
FILE_SHARE_WRITE	驱动程序不需要对设备具有独占写入访问权限。
FILE_SHARE_DELETE	驱动程序不需要对设备具有独占删除访问权限。

UMDF 有关此成员的详细信息，请参阅 Windows SDK 中 CreateFile 函数的 dwShareMode 参数。

ShareAccess 中的值零表示驱动程序需要对设备进行独占访问。

FileAttributes

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则这是 Wdm.h 中定义的 FILE_ATTRIBUTE_Xxxx 标志的按位 OR。大多数驱动程序指定FILE_ATTRIBUTE_NORMAL。有关这些标志的详细信息，请参阅 ZwCreateFile。

UMDF 有关此成员的详细信息，请参阅 Windows SDK 中 CreateFile 函数的 dwFlagsAndAttributes 参数。

如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

CreateDisposition

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则此值指示系统在打开文件时要执行的操作。有关可能值的列表，请参阅 ZwCreateFile。

UMDF 有关此成员的详细信息，请参阅 Windows SDK 中 CreateFile 函数的 dwCreationDisposition 参数。

如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

CreateOptions

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则这是文件选项标志的按位 OR。有关可能标志的列表，请参阅 ZwCreateFile。如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

EaBuffer

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则此成员指向扩展的属性缓冲区。通常，驱动程序为此值提供 NULL 。如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

EaBufferLength

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则这是扩展属性缓冲区的长度。通常，驱动程序为此值提供零。如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

AllocationSize

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则此成员指定系统在创建新文件时最初应为该文件分配的大小（以字节为单位）。此值是可选的，可以为零。如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

FileInformation

此成员不适用于 UMDF 驱动程序。

KMDF 如果 Type 的值为 WdfIoTargetOpenByName，则当 WdfIoTargetOpen 调用返回时，此成员会收到状态信息。信息是以下值之一：FILE_CREATED、FILE_OPENED、FILE_OVERWRITTEN、FILE_SUPERSEDED、FILE_EXISTS 或 FILE_DOES_NOT_EXIST。如果 Type 的值不是 WdfIoTargetOpenByName，则忽略此成员。

FileName

此成员不适用于 KMDF 驱动程序。

UMDF 一个 UNICODE_STRING 结构，其中包含要从中创建文件对象的文件的名称。此成员是可选的，仅当 Type 的值为 WdfIoTargetOpenLocalTargetByFile 时适用。除非较低目标支持设备命名空间访问，否则大多数驱动程序在此处指定 NULL。如果提供，则字符串不得包含任何路径分隔符 (正斜杠或反斜杠) 。

注解

驱动程序应通过调用以下函数之一来初始化 WDF_IO_TARGET_OPEN_PARAMS 结构：

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE，如果驱动程序可以通过提供指向DEVICE_OBJECT结构的指针来标识目标设备。
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME，如果 I/O 目标是设备、文件或设备接口，并且驱动程序可以提供设备、文件或设备接口的名称。如果指定已存在的文件的名称，系统将替换现有文件。如果该文件不存在，系统会创建它。
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME，如果 I/O 目标是设备、文件或设备接口，并且驱动程序可以提供设备、文件或设备接口的名称。如果指定已存在的文件的名称，系统将打开现有文件。如果文件不存在，打开操作将失败。
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN，如果驱动程序的 EvtIoTargetRemoveCanceled 回调函数因设备未移除而重新打开远程 I/O 目标。
如果 UMDF 驱动程序需要将驱动程序创建的请求发送到需要关联文件对象的较低目标，WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE。