WdfRegistryQueryMultiString-Funktion (wdfregistry.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfRegistryQueryMultiString--Methode ruft die Zeichenfolgen ab, die derzeit einem angegebenen Registrierungswert mit mehreren Zeichenfolgen zugewiesen sind, erstellt ein Framework-Zeichenfolgenobjekt für jede Zeichenfolge und fügt jedes Zeichenfolgenobjekt zu einer angegebenen Objektauflistunghinzu.

Syntax

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

Parameter

[in] Key

Ein Handle zu einem Registrierungsschlüsselobjekt, das einen geöffneten Registrierungsschlüssel darstellt.

[in] ValueName

Ein Zeiger auf eine UNICODE_STRING Struktur, die einen Wertnamen enthält.

[in, optional] StringsAttributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für jedes neue Zeichenfolgenobjekt enthält. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[in] Collection

Ein Handle für ein vom Treiber bereitgestelltes Framework-Auflistungsobjekt.

Rückgabewert

WdfRegistryQueryMultiString gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryMultiString wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben.
STATUS_INSUFFICIENT_RESOURCES	Ein Zeichenfolgenobjekt konnte nicht zugeordnet werden.
STATUS_ACCESS_DENIED	Der Treiber hat den Registrierungsschlüssel nicht mit KEY_QUERY_VALUE, KEY_READ oder KEY_ALL_ACCESS Zugriff geöffnet.
STATUS_OBJECT_TYPE_MISMATCH	Der Datentyp des Registrierungswerts, den der angegebene ValueName Parameter nicht REG_MULTI_SZ wurde.
STATUS_OBJECT_NAME_NOT_FOUND	Der Registrierungswert war nicht verfügbar.
STATUS_RESOURCE_DATA_NOT_FOUND	Der Registrierungswert ist unter dem angegebenen Schlüssel vorhanden, ist jedoch leer.

Eine Liste mit anderen Rückgabewerten, die die WdfRegistryQueryMultiString--Methode möglicherweise zurückgeben kann, finden Sie unter Framework-Objekterstellungsfehler.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Bevor Ihr Treiber WdfRegistryQueryMultiStringaufruft, muss er WdfCollectionCreate aufrufen, um ein Auflistungsobjekt zu erstellen.

Wenn der Aufrufer keinen StringsAttributes Parameter bereitstellt, werden alle vom Framework erstellten WDFSTRING-Objekte standardmäßig dem WDFDRIVER zugeordnet.

Nachdem WdfRegistryQueryMultiString- zurückgegeben wurde, kann der Treiber WdfCollectionGetCount- aufrufen, um die Anzahl der abgerufenen Zeichenfolgen abzurufen, und WdfCollectionGetItem-, um Zeichenfolgenobjekte aus der Auflistung abzurufen.

Wenn die Auflistung Objekte enthält, bevor der Treiber die WdfRegistryQueryMultiString--Methode aufruft, werden diese Objekte nicht entfernt oder deren Indexwerte geändert. Die neuen Objekte werden am Ende der Auflistung angefügt.

Um eine Zeichenfolge aus einem Zeichenfolgenobjekt abzurufen, kann der Treiber WdfStringGetUnicodeString-aufrufen.

Weitere Informationen zu Registrierungsschlüsselobjekten finden Sie unter Verwenden der Registrierung in Framework-Based Drivers.

Beispiele

Im folgenden Codebeispiel wird ein Auflistungsobjekt erstellt, eine WDF_OBJECT_ATTRIBUTES Struktur initialisiert, sodass das Auflistungsobjekt das übergeordnete Element aller Zeichenfolgenobjekte ist, die das Framework für die Auflistung erstellt, und ruft die Zeichenfolgen aus einem Registrierungswert mit mehreren Zeichenfolgen ab. Schließlich ruft das Beispiel die Anzahl der Zeichenfolgenobjekte ab, die das Framework der Auflistung hinzugefügt hat.

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfregistry.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)