Fungsi WdfIoTargetOpen (wdfiotarget.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfIoTargetOpen membuka target I/O jarak jauh sehingga driver dapat mengirim permintaan I/O ke dalamnya.

Sintaks

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

Parameter

[in] IoTarget

Handel ke objek target I/O yang diperoleh dari panggilan sebelumnya ke WdfIoTargetCreate.

[in] OpenParams

Penunjuk ke struktur WDF_IO_TARGET_OPEN_PARAMS yang dialokasikan penelepon.

Nilai kembali

WdfIoTargetOpen mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_STATE	Target I/O yang ditentukan sudah terbuka.
STATUS_INSUFFICIENT_RESOURCES	Sumber daya sistem yang tersedia tidak cukup untuk menyelesaikan operasi.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_IO_TARGET_OPEN_PARAMS yang ditentukan OpenParams salah.
STATUS_NO_SUCH_DEVICE	Anggota TargetFileObject dari struktur WDF_IO_TARGET_OPEN_PARAMS pemanggil menentukan objek file yang tidak valid.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_NOT_FOUND	Nama perangkat yang diidentifikasi dalam parameter OpenParams tidak dapat ditemukan.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Driver dapat membuka target I/O jarak jauh dengan menyediakan string Unicode yang mewakili nama objek atau dengan memasok pointer ke struktur DEVICE_OBJECT Windows Driver Model (WDM). (Driver berbasis kerangka kerja biasanya tidak memiliki penunjuk ke struktur DEVICE_OBJECT driver lain.)

Untuk mendapatkan nama antarmuka perangkat sebelum memanggil WdfIoTargetOpen, driver UMDF harus memanggil CM_Register_Notification untuk mendaftar pemberitahuan kedatangan dan penghapusan antarmuka. Kemudian dapat membuka target jarak jauh menggunakan nama simbolis antarmuka yang diterimanya dalam rutinitas panggilan balik pemberitahuan antarmuka. Driver harus terus mendengarkan pemberitahuan penghapusan saat handel terbuka. Jika driver target gagal, driver UMDF harus menutup handel.

Jika antarmuka sudah ada, driver UMDF harus memanggil CM_Get_Device_Interface_List, mungkin memanggil CM_Get_Device_Interface_List_Size terlebih dahulu untuk menentukan ukuran buffer yang diperlukan.

Jika Anda ingin driver Anda menggunakan target I/O lokalnya, driver harus memanggil WdfDeviceGetIoTarget alih-alih WdfIoTargetOpen.

Jika panggilan ke WdfIoTargetOpen gagal, driver harus memanggil WdfObjectDelete untuk menghapus objek target I/O.

Untuk informasi selengkapnya tentang WdfIoTargetOpen, lihat Menginisialisasi Target I/O Umum.

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

Contoh

Contoh berikut membuat objek target I/O, menginisialisasi struktur WDF_IO_TARGET_OPEN_PARAMS , dan membuka target I/O jarak jauh dengan menentukan nama tautan simbolis perangkat.

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;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfiotarget.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)