WdfFdoInitQueryProperty-Funktion (wdffdo.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfFdoInitQueryProperty-Methode ruft eine angegebene Geräteeigenschaft ab.

Syntax

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

Parameter

[in] DeviceInit

Ein Zeiger auf eine WDFDEVICE_INIT Struktur, die der Treiber aus seiner Rückruffunktion EvtDriverDeviceAdd abgerufen hat.

[in] DeviceProperty

Ein DEVICE_REGISTRY_PROPERTY typisierter Enumeratorwert, der die abzurufende Geräteeigenschaft identifiziert.

[in] BufferLength

Die Größe des Puffers in Bytes, auf den von PropertyBuffer verwiesen wird.

[out] PropertyBuffer

Ein vom Aufrufer bereitgestellter Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die angeforderte Geräteeigenschaft empfängt. Dieser Zeiger kann NULL sein, wenn der BufferLength-Parameter 0 ist.

[out] ResultLength

Ein vom Aufrufer bereitgestellter Speicherort, der bei der Rückgabe die Größe (in Bytes) der Informationen enthält, die WdfFdoInitQueryProperty in PropertyBuffer gespeichert hat. Wenn der Rückgabewert dieser Methode STATUS_BUFFER_TOO_SMALL ist, erhält ResultLength die erforderliche Puffergröße.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Methode STATUS_SUCCESS zurück. Weitere Rückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Der bereitgestellte Puffer ist zu klein, um die Informationen zu empfangen.
STATUS_INVALID_PARAMETER_2	Der angegebene DeviceProperty-Wert ist ungültig.
STATUS_INVALID_DEVICE_REQUEST	Die WDFDEVICE_INIT Struktur wurde nicht von der Rückruffunktion EvtDriverDeviceAdd des Treibers abgerufen.

Die Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

Vor dem Empfangen von Geräteeigenschaftendaten müssen Treiber in der Regel einen ersten Aufruf von WdfFdoInitQueryProperty ausführen, um die erforderliche Puffergröße abzurufen. Bei einigen Eigenschaften kann sich die Datengröße zwischen dem Zeitpunkt, zu dem die erforderliche Größe zurückgegeben wird, und dem Zeitpunkt ändern, zu dem der Treiber diese Routine erneut aufruft. Daher sollten Treiber WdfFdoInitQueryProperty in einer Schleife aufrufen, die ausgeführt wird, bis die Rückgabe status nicht STATUS_BUFFER_TOO_SMALL ist.

Es empfiehlt sich, WdfFdoInitQueryProperty nur zu verwenden, wenn die erforderliche Puffergröße bekannt ist und sich nicht ändert, da in diesem Fall der Treiber WdfFdoInitQueryProperty nur einmal aufrufen muss. Wenn die erforderliche Puffergröße unbekannt ist oder variiert, sollte der Treiber WdfFdoInitAllocAndQueryProperty aufrufen.

Der Treiber kann WdfFdoInitQueryProperty nur aufrufen, bevor WdfDeviceCreate aufgerufen wird. Weitere Informationen zum Aufrufen von WdfDeviceCreate finden Sie unter Erstellen eines Framework-Geräteobjekts.

Nach dem Aufruf von WdfDeviceCreate kann ein Treiber Geräteeigenschafteninformationen abrufen, indem er WdfDeviceQueryProperty aufruft.

Weitere Informationen zur WdfFdoInitQueryProperty-Methode finden Sie unter Erstellen von Geräteobjekten in einem Funktionstreiber.

Alternativ können Sie WdfFdoInitQueryPropertyEx verwenden, um auf Geräteeigenschaften zuzugreifen, die über das Unified-Eigenschaftenmodell verfügbar gemacht werden.

Beispiele

Das folgende Codebeispiel ruft eine Unicode-Zeichenfolge ab, die den Namen des Enumerators eines Geräts darstellt, und gibt TRUE zurück, wenn die Zeichenfolge "PCI" ist.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdffdo.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DeviceInitAPI(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty

Freigeben über