Fungsi WdfDeviceQueryProperty (wdfdevice.h)

Artikel
03/01/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfDeviceQueryProperty mengambil properti perangkat tertentu.

Sintaks

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] DeviceProperty

Enumerator jenis DEVICE_REGISTRY_PROPERTY yang mengidentifikasi properti perangkat yang akan diambil.

[in] BufferLength

Ukuran, dalam byte, dari buffer yang ditujukkan oleh PropertyBuffer.

[out] PropertyBuffer

Penunjuk yang disediakan penelepon ke buffer yang dialokasikan pemanggil yang menerima informasi yang diminta. Penunjuk dapat berupa NULL jika parameter BufferLength adalah nol.

[out] ResultLength

Lokasi yang disediakan penelepon yang, saat dikembalikan, berisi ukuran, dalam byte, dari informasi yang disimpan metode di PropertyBuffer. Jika nilai pengembalian fungsi STATUS_BUFFER_TOO_SMALL, lokasi ini menerima ukuran buffer yang diperlukan.

Nilai kembali

Jika operasi berhasil, WdfDeviceQueryProperty mengembalikan STATUS_SUCCESS. Nilai pengembalian tambahan meliputi:

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

Metode ini mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

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

Yang terbaik adalah menggunakan WdfDeviceQueryProperty hanya jika ukuran buffer yang diperlukan diketahui dan tidak berubah, karena dalam hal ini driver harus memanggil WdfDeviceQueryProperty hanya sekali. Jika ukuran buffer yang diperlukan tidak diketahui atau bervariasi, driver harus memanggil WdfDeviceAllocAndQueryProperty.

Atau, Anda dapat menggunakan WdfDeviceQueryPropertyEx untuk mengakses properti perangkat yang diekspos melalui Model Properti Terpadu.

Contoh

Contoh kode berikut mendapatkan properti DevicePropertyBusTypeGuid perangkat. Contoh memanggil WdfDeviceQueryProperty alih-alih WdfDeviceAllocAndQueryProperty karena panjang GUID diketahui.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfdevice.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)

Lihat juga

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty