WdfIoTargetWdmGetTargetFileHandle 函式 (wdfiotarget.h)

[適用於 KMDF 和 UMDF]

WdfIoTargetWdmGetTargetFileHandle 方法會傳回與指定遠端 I/O 目標相關聯的檔案句柄。

語法

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

參數

[in] IoTarget

遠端 I/O 目標物件的句柄。 此句柄是從先前呼叫 WdfIoTargetCreate 取得。

傳回值

如果驅動程式在呼叫 WdfIoTargetOpen 時指定物件名稱， WdfIoTargetWdmGetTargetFileHandle 會傳回與指定 I/O 目標相關聯的檔句柄。 否則 WdfIoTargetWdmGetTargetFileHandle 會傳回 NULL。

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

備註

對於 KMDF，傳回的檔句柄是可在任意線程內容中有效的內核模式句柄。 如需驅動程式如何使用這個檔案句柄的資訊，請參閱 使用檔句柄。

WdfIoTargetWdmGetTargetFileHandle 方法傳回的檔案句柄有效，直到驅動程式呼叫 WdfIoTargetClose 或 WdfIoTargetCloseForQueryRemove，或直到刪除遠端 I/O 目標對象為止。 如果驅動程式為遠端 I/O 目標物件提供 EvtCleanupCallback 函式，而且如果在關閉遠端 I/O 目標之前刪除物件，則指標會有效，直到 EvtCleanupCallback 函式傳回為止。

如果驅動程式在移除 WDM 裝置對象之後嘗試存取它，驅動程式可能會導致系統當機。 toastmon 範例示範驅動程式如何提供 EvtIoTargetQueryRemove 回呼函式，以便在移除 I/O 目標時收到通知。

針對 UMDF，WdfIoTargetWdmGetTargetFileHandle 只會在目前的進程中傳回有效的 Win32 HANDLE。 舊版 UMDF 驅動程式 (第 1 版。x) 呼叫 IWDFDevice：：RetrieveDeviceName 以取得基礎核心模式裝置的名稱，然後使用 CreateFile 開啟其句柄。 然後，驅動程式可以使用 DeviceIoControl 將 I/O 直接傳送至較低的裝置 () 。 從UMDF 2.15開始，UMDF v2驅動程式可以透過檔案 (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) 開啟本機 I/O 目標，並使用 WdfIoTargetWdmGetTargetFileHandle 來擷取檔句柄。 當遠端目標關閉或刪除時，架構會開啟並關閉檔句柄。 檔案句柄在上述 WdfIoTargetWdmGetTargetFileHandle 的合約內保持有效。

警告

如果 UMDF v2 驅動程式呼叫 WdfIoTargetWdmGetTargetFileHandle ，以從使用 WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE開啟的遠端目標取得 Win32 句柄，請勿使用 DeviceIoControl 之類的 API 提交重疊/異步 I/O。 這麼做可能會損毀裝載驅動程序的進程。 如果驅動程式必須提交重疊的 I/O，它也必須設定 OVERLAPPED 結構之 hEvent 成員的低序位。 這是因為架構會在內部將句柄系結至 I/O 完成埠。 設定低序位的有效事件句柄，會讓 I/O 完成不排入佇列到完成埠。

如需 WdfIoTargetWdmGetTargetFileHandle 的詳細資訊，請參閱 取得一般 I/O 目標的相關信息。

如需 I/O 目標的詳細資訊，請參閱 使用 I/O 目標。

範例

下列程式代碼範例會取得與指定遠端 I/O 目標相關聯的檔案句柄。

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

舊版 UMDF 驅動程式 (第 1 版。x) 呼叫 IWDFDevice：：RetrieveDeviceName 以取得基礎核心模式裝置的名稱，然後使用 CreateFile 開啟其句柄。 驅動程式接著會使用 DeviceIoControl 將 I/O 直接傳送至裝置。

從UMDF 2.15開始，驅動程式會依檔案開啟本機 I/O 目標，並擷取其句柄。 架構會開啟並關閉檔句柄。 檔句柄在 WdfIoTargetWdmGetTargetFileHandle 的合約內仍有效。

NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.15
標頭	wdfiotarget.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另請參閱

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject