WdfRegistryQueryMultiString-Funktion (wdfregistry.h)

Artikel
08/08/2023

[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 Frameworkzeichenfolgenobjekt für jede Zeichenfolge und fügt jedes Zeichenfolgenobjekt einer angegebenen Objektauflistung hinzu.

Syntax

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

Parameter

[in] Key

Ein Handle für ein 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 Frameworksammlungsobjekt.

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 unter IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde 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 Geöffnet.
STATUS_OBJECT_TYPE_MISMATCH	Der Datentyp des Registrierungswerts, den der ValueName-Parameter angegeben hat, wurde nicht REG_MULTI_SZ.
STATUS_OBJECT_NAME_NOT_FOUND	Der Registrierungswert war nicht verfügbar.
STATUS_RESOURCE_DATA_NOT_FOUND	Der Registrierungswert befindet sich unter dem angegebenen Schlüssel, ist aber leer.

Eine Liste mit anderen Rückgabewerten, die von der WdfRegistryQueryMultiString-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.

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

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Bevor Der Treiber WdfRegistryQueryMultiString aufruft, muss er WdfCollectionCreate aufrufen, um ein Sammlungsobjekt zu erstellen.

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

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, entfernt die -Methode diese Objekte nicht und ändert ihre Indexwerte nicht. 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-Treibern.

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 die Zeichenfolgen aus einem Registrierungswert mit mehreren Zeichenfolgen abrufen. 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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfregistry.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)