WdfIoTargetOpen 函数 (wdfiotarget.h)

项目
02/27/2024

[适用于 KMDF 和 UMDF]

WdfIoTargetOpen 方法打开远程 I/O 目标，以便驱动程序可以向其发送 I/O 请求。

语法

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

参数

[in] IoTarget

从上一次调用 WdfIoTargetCreate 获取的 I/O 目标对象的句柄。

[in] OpenParams

指向调用方分配的WDF_IO_TARGET_OPEN_PARAMS 结构的指针。

返回值

如果操作成功，WdfIoTargetOpen 将返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_INVALID_DEVICE_STATE	指定的 I/O 目标已打开。
STATUS_INSUFFICIENT_RESOURCES	可用的系统资源不足以完成操作。
STATUS_INFO_LENGTH_MISMATCH	OpenParams 指定的WDF_IO_TARGET_OPEN_PARAMS结构的大小不正确。
STATUS_NO_SUCH_DEVICE	调用方WDF_IO_TARGET_OPEN_PARAMS结构的 TargetFileObject 成员指定了无效的文件对象。
STATUS_INVALID_PARAMETER	检测到无效的参数。
STATUS_NOT_FOUND	找不到 OpenParams 参数中标识的设备名称。

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

驱动程序可以通过提供表示对象名称的 Unicode 字符串或提供指向 Windows 驱动程序模型 (WDM) DEVICE_OBJECT 结构的指针来打开远程 I/O 目标。 (基于框架的驱动程序通常没有指向其他驱动程序DEVICE_OBJECT结构的指针。)

若要在调用 WdfIoTargetOpen 之前获取设备接口名称，UMDF 驱动程序应调用 CM_Register_Notification 来注册接口到达和删除通知。然后，它可以使用在接口通知回调例程中收到的接口符号名称打开远程目标。当句柄打开时，驱动程序应继续侦听删除通知。如果目标驱动程序失败，UMDF 驱动程序必须关闭句柄。

如果接口已存在，则 UMDF 驱动程序应调用 CM_Get_Device_Interface_List，可能首先调用 CM_Get_Device_Interface_List_Size 以确定所需的缓冲区大小。

如果希望驱动程序使用其本地 I/O 目标，驱动程序必须调用 WdfDeviceGetIoTarget ，而不是 WdfIoTargetOpen。

如果调用 WdfIoTargetOpen 失败，驱动程序应调用 WdfObjectDelete 以删除 I/O 目标对象。

有关 WdfIoTargetOpen 的详细信息，请参阅初始化常规 I/O 目标。

有关 I/O 目标的详细信息，请参阅使用 I/O 目标。

示例

以下示例创建 I/O 目标对象，初始化 WDF_IO_TARGET_OPEN_PARAMS 结构，并通过指定设备的符号链接名称打开远程 I/O 目标。

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfiotarget.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)