WdfIoTargetOpen 函式 (wdfiotarget.h)

發行項
02/29/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。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
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值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

驅動程式可以藉由提供代表物件名稱的 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;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfiotarget.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)