Fungsi WdfFdoInitQueryProperty (wdffdo.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfFdoInitQueryProperty mengambil properti perangkat tertentu.

Sintaks

NTSTATUS WdfFdoInitQueryProperty(
  [in]  PWDFDEVICE_INIT          DeviceInit,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parameter

[in] DeviceInit

Penunjuk ke struktur WDFDEVICE_INIT yang diperoleh driver dari fungsi panggilan balik EvtDriverDeviceAdd .

[in] DeviceProperty

Nilai 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 properti perangkat yang diminta. Penunjuk ini bisa NULL jika parameter BufferLength adalah nol.

[out] ResultLength

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

Nilai kembali

Jika operasi berhasil, metode akan 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	Struktur WDFDEVICE_INIT tidak diperoleh dari fungsi panggilan balik EvtDriverDeviceAdd driver.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Keterangan

Sebelum menerima data properti perangkat, driver biasanya harus melakukan panggilan awal ke WdfFdoInitQueryProperty untuk mendapatkan ukuran buffer yang diperlukan. Untuk beberapa properti, ukuran data dapat berubah antara waktu ketika ukuran yang diperlukan dikembalikan dan waktu driver memanggil rutinitas ini lagi. Oleh karena itu, driver harus memanggil WdfFdoInitQueryProperty di dalam perulangan yang dijalankan hingga status pengembalian tidak STATUS_BUFFER_TOO_SMALL.

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

Driver hanya dapat memanggil WdfFdoInitQueryProperty sebelum memanggil WdfDeviceCreate. Untuk informasi selengkapnya tentang memanggil WdfDeviceCreate, lihat Membuat Objek Perangkat Kerangka Kerja.

Setelah memanggil WdfDeviceCreate, driver dapat memperoleh informasi properti perangkat dengan memanggil WdfDeviceQueryProperty.

Untuk informasi selengkapnya tentang metode WdfFdoInitQueryProperty , lihat Membuat Objek Perangkat di Driver Fungsi.

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

Contoh

Contoh kode berikut mendapatkan string Unicode yang mewakili nama enumerator perangkat dan mengembalikan TRUE jika string adalah "PCI".

NTSTATUS  status = STATUS_SUCCESS;
WCHAR  enumeratorName[64] = {0};
ULONG  returnSize;
UNICODE_STRING  unicodeEnumName, temp;

status = WdfFdoInitQueryProperty(
                                 DeviceInit,
                                 DevicePropertyEnumeratorName,
                                 sizeof(enumeratorName),
                                 enumeratorName,
                                 &returnSize
                                 );
if(!NT_SUCCESS(status)){
    return status;
}

RtlInitUnicodeString(
                     &unicodeEnumName,
                     enumeratorName
                     );
RtlInitUnicodeString(
                     &temp,
                     L"PCI"
                     );
if(RtlCompareUnicodeString(
                           &unicodeEnumName,
                           &temp,
                           TRUE
                           ) == 0) {
    //
    // This device is a PCI device.
    //
    return TRUE;
}

Persyaratan

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

Lihat juga

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty

Bagikan melalui