Fungsi WdfIoTargetQueryTargetProperty (wdfiotarget.h)

Artikel
02/27/2024

[Berlaku untuk KMDF saja]

Metode WdfIoTargetQueryTargetProperty mengambil properti perangkat tertentu untuk target I/O tertentu.

Sintaks

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

Parameter

[in] IoTarget

Handel ke objek target I/O lokal atau jarak jauh yang diperoleh dari panggilan sebelumnya ke WdfDeviceGetIoTarget atau WdfIoTargetCreate, atau dari metode yang disediakan target I/O khusus.

[in] DeviceProperty

Nilai jenis DEVICE_REGISTRY_PROPERTY yang mengidentifikasi properti perangkat yang akan diambil.

[in] BufferLength

Ukuran, dalam byte, dari buffer yang dirujuk PropertyBuffer .

[out, optional] PropertyBuffer

Penunjuk ke buffer yang dialokasikan pemanggil yang menerima informasi properti perangkat yang diminta. Penunjuk ini bisa NULL jika BufferLength adalah nol.

[out] ResultLength

Penunjuk ke lokasi yang, saat dikembalikan, berisi ukuran, dalam byte, dari informasi yang dituju WdfIoTargetQueryTargetProperty dalam buffer yang dituju PropertyBuffer . Jika WdfIoTargetQueryTargetProperty mengembalikan STATUS_BUFFER_TOO_SMALL, lokasi ini menerima ukuran buffer yang diperlukan.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_BUFFER_TOO_SMALL	Buffer yang ditujuk parameter PropertyBuffer terlalu kecil untuk menerima informasi yang diminta.
STATUS_INVALID_PARAMETER_2	Nilai yang ditentukan parameter DeviceProperty tidak valid.
STATUS_INVALID_DEVICE_REQUEST	Driver perangkat belum melaporkan properti perangkat.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Sebelum driver menerima data properti perangkat, mereka biasanya memanggil metode WdfIoTargetQueryTargetProperty untuk mendapatkan ukuran buffer yang diperlukan. Untuk beberapa properti, ukuran data dapat berubah antara kapan ukuran yang diperlukan dikembalikan dan ketika driver memanggil WdfIoTargetQueryTargetProperty lagi. Oleh karena itu, driver harus memanggil WdfIoTargetQueryTargetProperty di dalam perulangan yang dijalankan hingga status pengembalian tidak STATUS_BUFFER_TOO_SMALL.

Alih-alih memanggil WdfIoTargetQueryTargetProperty, driver Anda dapat memanggil WdfIoTargetAllocAndQueryTargetProperty, yang mengalokasikan buffer dan menempatkan informasi properti di buffer.

Untuk informasi selengkapnya tentang WdfIoTargetQueryTargetProperty, 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 properti DevicePropertyUINumber perangkat. Contoh memanggil WdfIoTargetQueryTargetProperty alih-alih WdfIoTargetAllocAndQueryTargetProperty karena panjang nomor UI diketahui.

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

Persyaratan

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