Fungsi WdfIoTargetWdmGetTargetFileHandle (wdfiotarget.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfIoTargetWdmGetTargetFileHandle mengembalikan handel ke file yang terkait dengan target I/O jarak jauh tertentu.

Sintaks

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Parameter

[in] IoTarget

Handel ke objek target I/O jarak jauh. Handel ini diperoleh dari panggilan sebelumnya ke WdfIoTargetCreate.

Nilai kembali

Jika driver menentukan nama objek saat disebut WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle mengembalikan handel file yang terkait dengan target I/O yang ditentukan. Jika tidak , WdfIoTargetWdmGetTargetFileHandle mengembalikan NULL.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Untuk KMDF, handel file yang dikembalikan adalah handel mode kernel yang valid dalam konteks utas arbitrer. Untuk informasi tentang bagaimana driver dapat menggunakan handel file ini, lihat Menggunakan Handel File.

Handel file yang dikembalikan metode WdfIoTargetWdmGetTargetFileHandle valid hingga driver memanggil WdfIoTargetClose atau WdfIoTargetCloseForQueryRemove, atau sampai objek target I/O jarak jauh dihapus. Jika driver menyediakan fungsi EvtCleanupCallback untuk objek target I/O jarak jauh, dan jika objek dihapus sebelum target I/O jarak jauh ditutup, penunjuk valid hingga fungsi EvtCleanupCallback kembali.

Jika driver mencoba mengakses objek perangkat WDM setelah dihapus, driver dapat menyebabkan sistem mengalami crash. Sampel toastmon menunjukkan bagaimana driver dapat menyediakan fungsi panggilan balik EvtIoTargetQueryRemove sehingga diberi tahu jika target I/O dihapus.

Untuk UMDF, WdfIoTargetWdmGetTargetFileHandle mengembalikan HANDLE Win32 yang hanya valid dalam proses saat ini. Driver UMDF warisan (versi 1.x) memanggil IWDFDevice::RetrieveDeviceName untuk mendapatkan nama perangkat mode kernel yang mendasar dan kemudian membuka handel untuk itu dengan CreateFile. Driver kemudian dapat mengirim I/O langsung ke perangkat yang lebih rendah menggunakan DeviceIoControl. Mulai dari UMDF 2.15, driver UMDF v2 dapat membuka target I/O lokal berdasarkan file (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) dan mengambil handel file menggunakan WdfIoTargetWdmGetTargetFileHandle. Kerangka kerja terbuka dan menutup handel file saat target jarak jauh ditutup atau dihapus. Handel file tetap valid dalam kontrak WdfIoTargetWdmGetTargetFileHandle yang dijelaskan di atas.

Peringatan

Jika driver UMDF v2 memanggil WdfIoTargetWdmGetTargetFileHandle untuk mendapatkan handel Win32 dari target jarak jauh yang dibuka menggunakan WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, jangan mengirimkan I/O yang tumpang tindih/asinkron dengan API seperti DeviceIoControl. Melakukannya dapat merusak proses yang menghosting driver. Jika driver harus mengirimkan I/O yang tumpang tindih, driver juga harus mengatur bit berurutan rendah dari anggota hEvent dari struktur TUMPANG TINDIH . Ini karena kerangka kerja secara internal mengikat handel ke port penyelesaian I/O. Handel peristiwa yang valid yang bit berurutan rendahnya diatur membuat penyelesaian I/O tidak diantrekan ke port penyelesaian.

Untuk informasi selengkapnya tentang WdfIoTargetWdmGetTargetFileHandle, lihat Mendapatkan Informasi Tentang Target I/O Umum.

Untuk informasi selengkapnya tentang target I/O, lihat Menggunakan Target I/O.

Contoh

Contoh kode berikut mendapatkan handel ke file yang terkait dengan target I/O jarak jauh tertentu.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Driver UMDF warisan (versi 1.x) memanggil IWDFDevice::RetrieveDeviceName untuk mendapatkan nama perangkat mode kernel yang mendasar dan kemudian membuka handel dengan CreateFile. Driver kemudian mengirim I/O langsung ke perangkat menggunakan DeviceIoControl.

Mulai dari UMDF 2.15, driver membuka target I/O lokal berdasarkan file dan mengambil handelnya. Kerangka kerja membuka dan menutup handel file. Handel file tetap valid dalam kontrak 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

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.15
Header	wdfiotarget.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Lihat juga

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject

Bagikan melalui