RtlQueryRegistryValues-Funktion (wdm.h)

Artikel
07/16/2024

Die RtlQueryRegistryValues Routine ermöglicht es dem Aufrufer, mehrere Werte aus der Registrierungsunterstruktur mit einem einzelnen Aufruf abzufragen.

Syntax

NTSYSAPI NTSTATUS RtlQueryRegistryValues(
  [in]           ULONG                     RelativeTo,
  [in]           PCWSTR                    Path,
  [in, out]      PRTL_QUERY_REGISTRY_TABLE QueryTable,
  [in, optional] PVOID                     Context,
  [in, optional] PVOID                     Environment
);

Parameter

[in] RelativeTo

Gibt an, ob Path ein absoluter Registrierungspfad ist oder relativ zu einem vordefinierten Pfad als einer der folgenden Pfade ist.

Wert	Bedeutung
RTL_REGISTRY_ABSOLUTE	Der Pfad ist ein absoluter Registrierungspfad.
RTL_REGISTRY_CONTROL	Der Pfad ist relativ zu \Registry\Machine\System\CurrentControlSet\Control.
RTL_REGISTRY_DEVICEMAP	Der Pfad ist relativ zu \Registry\Machine\Hardware\DeviceMap.
RTL_REGISTRY_SERVICES	Der Pfad ist relativ zu \Registry\Machine\System\CurrentControlSet\Services.
RTL_REGISTRY_USER	Der Pfad ist relativ zu \Registry\User\CurrentUser. (Bei einem Systemprozess ist dies \User\. Standard-.)
RTL_REGISTRY_WINDOWS_NT	Der Pfad ist relativ zu \Registry\Machine\Software\Microsoft\Windows NT\CurrentVersion.

Der RelativeTo- Wert kann durch bitweises ORingen mit einem der folgenden Flags geändert werden.

Flagge	Bedeutung
RTL_REGISTRY_OPTIONAL	Gibt an, dass der Von diesem Parameter referenzierte Schlüssel und der Path Parameter optional sind.
RTL_REGISTRY_HANDLE	Gibt an, dass der Path Parameter tatsächlich ein Registrierungshandle ist, das verwendet werden soll.

[in] Path

Zeigen Sie entweder auf einen absoluten Registrierungspfad oder einen Pfad relativ zu dem bekannten Speicherort, der durch den Parameter RelativeTo angegeben wird. Beachten Sie, dass die Namen von Schlüsseln in einem solchen Pfad dem Aufrufer bekannt sein müssen, einschließlich des letzten Schlüssels im Pfad. Wenn das RTL_REGISTRY_HANDLE Flag angegeben ist, ist dieser Parameter ein Registrierungshandle für einen bereits geöffneten Schlüssel, der direkt abgefragt werden kann.

[in, out] QueryTable

Zeigen Sie auf eine Tabelle mit mindestens einem Wertnamen und Unterschlüsselnamen, für die der Aufrufer interessiert ist. Jeder Tabelleneintrag enthält die Adresse eines vom Aufrufer bereitgestellten QueryRoutine--Funktion, die für jeden Wertnamen aufgerufen wird, der in der Registrierung vorhanden ist. Die Tabelle muss mit einem NULL- Tabelleneintrag beendet werden, bei dem es sich um einen Tabelleneintrag mit einem NULL-QueryRoutine Member und einem NULLName Member handelt. Die Struktur für Abfragetabelleneinträge ist wie folgt definiert:

typedef struct _RTL_QUERY_REGISTRY_TABLE {
    PRTL_QUERY_REGISTRY_ROUTINE QueryRoutine;
    ULONG Flags;
    PWSTR Name;
    PVOID EntryContext;
    ULONG DefaultType;
    PVOID DefaultData;
    ULONG DefaultLength;
} RTL_QUERY_REGISTRY_TABLE, *PRTL_QUERY_REGISTRY_TABLE;

Wenn der Aufrufer Speicher für die Abfragetabelle zuweist, auf die der parameter QueryTable verweist, ist der Aufrufer dafür verantwortlich, diesen Speicher freizugeben, nachdem die RtlQueryRegistryValues Aufruf zurückgegeben wurde.

QueryRoutine

Die Adresse einer QueryRoutine--Funktion, die mit dem Namen, Typ, Daten und der Datenlänge eines Registrierungswerts aufgerufen wird. Wenn dieses Element und der Name Member beide NULL-sind, wird das Ende der Tabelle markiert.

Eine QueryRoutine--Funktion wird wie folgt deklariert:

NTSTATUS
QueryRoutine (
    IN PWSTR ValueName,
    IN ULONG ValueType,
    IN PVOID ValueData,
    IN ULONG ValueLength,
    IN PVOID Context,
    IN PVOID EntryContext
    );

Weitere Informationen finden Sie unter QueryRoutine.

Flaggen

Flags zum Steuern, wie die verbleibenden Member der RTL_QUERY_REGISTRY_TABLE Struktur interpretiert werden sollen. Die folgenden Flagbits werden für dieses Element definiert.

Wert	Bedeutung
RTL_QUERY_REGISTRY_SUBKEY	Der Name dieses Tabelleneintrags ist ein anderer Pfad zu einem Registrierungsschlüssel, und alle folgenden Tabelleneinträge gelten für diesen Schlüssel und nicht für den durch den Parameter Path angegebenen Schlüssel. Diese Änderung des Fokus dauert bis zum Ende der Tabelle oder bis ein anderer RTL_REGISTRY_SUBKEY oder RTL_QUERY_REGISTRY_TOPKEY Eintrag angezeigt wird. Jeder solcher Eintrag muss einen Pfad angeben, der relativ zum Path im Aufruf von RtlQueryRegistryValuesangegeben ist.
RTL_QUERY_REGISTRY_TOPKEY	Setzt den aktuellen Registrierungsschlüsselhandle auf das ursprüngliche Handle zurück, das durch die Parameter RelativeTo und Path angegeben wurde. Dies ist nützlich, um zum ursprünglichen Knoten zurückzukehren, nachdem er in Unterschlüssel absteigend mit der RTL_QUERY_REGISTRY_SUBKEY-Kennzeichnung absteigend ist.
RTL_QUERY_REGISTRY_REQUIRED	Gibt an, dass dieser Registrierungswert vorhanden sein muss, wenn DefaultType- = REG_NONE; andernfalls wird RtlQueryRegistryValues sofort mit einem Statuscode von STATUS_OBJECT_NAME_NOT_FOUND beendet. Dieser Exit tritt auf, wenn der Name Member NULL- ist und der aktuelle Schlüssel keine Unterschlüssel aufweist oder wenn Name einen nicht vorhandenen Unterschlüssel angibt. (Wenn dieses Flag nicht angegeben ist, verwendet die Routine das DefaultValue- Element als Wert, wenn keine Übereinstimmung für ein nichtNULL-Namegefunden wird. Wenn Name-NULL- ist und der aktuelle Schlüssel keine Unterschlüssel enthält, überspringt die Routine einfach diesen Tabelleneintrag.)
RTL_QUERY_REGISTRY_NOVALUE	Gibt an, dass obwohl für diesen Tabelleneintrag kein Name vorhanden ist, der gesamte Aufrufer ein Rückruf ist, d. h. der Aufrufer möchte nicht alle Werte unter dem aktuellen Schlüssel aufzählen. QueryRoutine- wird mit NULL- für ValueData-, REG_NONE für ValueType-und Null für ValueLength-aufgerufen.
RTL_QUERY_REGISTRY_NOEXPAND	Bei einem Registrierungswert vom Typ REG_EXPAND_SZ oder REG_MULTI_SZ überschreibt dieses Flag das Standardverhalten, das vor dem Aufrufen der QueryRoutine Routine vor der Verarbeitung des Registrierungswerts besteht. Standardmäßig erweitert RtlQueryRegistryValues Umgebungsvariablenverweise in REG_EXPAND_SZ Werten und listet jede null-beendete Zeichenfolge in einem REG_MULTI_SZ Wert in einem separaten QueryRoutine- Aufruf auf, sodass die Zeichenfolgen als REG_SZ Werte angezeigt werden, die dieselbe ValueNamehaben. Wenn dieses Flag festgelegt ist, empfängt QueryRoutine den rohen REG_EXPAND_SZ oder REG_MULTI_SZ Wert aus der Registrierung. Weitere Informationen zu den Datenformaten für diese Werte finden Sie unter KEY_VALUE_BASIC_INFORMATION.
RTL_QUERY_REGISTRY_DIRECT	Das QueryRoutine Member wird nicht verwendet (und muss NULL-sein), und die EntryContext- verweist auf den Puffer, um den Wert zu speichern. Wenn der Aufrufer dieses Flag festlegt, sollte der Aufrufer zusätzlich das RTL_QUERY_REGISTRY_TYPECHECK Flag festlegen, um den Pufferüberlauf zu schützen. Weitere Informationen finden Sie im Abschnitt "Hinweise".
RTL_QUERY_REGISTRY_TYPECHECK	Verwenden Sie dieses Flag mit der RTL_QUERY_REGISTRY_DIRECT-Kennzeichnung, um zu überprüfen, ob der REG_XXX- Typ des gespeicherten Registrierungswerts dem vom Aufrufer erwarteten Typ entspricht. Wenn die Typen nicht übereinstimmen, schlägt der Aufruf fehl. Weitere Informationen finden Sie im Abschnitt "Hinweise".
RTL_QUERY_REGISTRY_DELETE	Dieses Kennzeichen wird verwendet, um Wertschlüssel zu löschen, nachdem sie abgefragt wurden.

Ab Windows 2000 wird die Posteingangsunterstützung für alle Flagbits in der vorherigen Tabelle bereitgestellt, mit Ausnahme von RTL_QUERY_REGISTRY_TYPECHECK. Die Posteingangsunterstützung für RTL_QUERY_REGISTRY_TYPECHECK ist ab Windows 8 verfügbar. Für frühere Versionen von Windows wird die Unterstützung für RTL_QUERY_REGISTRY_TYPECHECK über Windows Update bereitgestellt. Weitere Informationen finden Sie in den Hinweisen.

Name

Dies ist der Name eines Werts, den der Aufrufer abgefragt hat. Wenn NameNULL-ist, wird die für diesen Tabelleneintrag angegebene QueryRoutine- funktion für alle Werte aufgerufen, die dem aktuellen Registrierungsschlüssel zugeordnet sind. Wenn das RTL_QUERY_REGISTRY_DIRECT Flag festgelegt ist, muss ein nichtNULL- Wert für Name- angegeben werden.

EntryContext

Wenn das RTL_QUERY_REGISTRY_DIRECT Flag festgelegt ist, ist dies ein Zeiger auf den Puffer, um das Ergebnis des Abfragevorgangs für diesen Schlüssel zu speichern. Andernfalls wird dieser Wert als EntryContext Parameter von QueryRoutineübergeben.

DefaultType

Das am wenigsten signifikante Byte dieses Elements gibt den REG_XXX- Typ der zurückgegebenen Daten an, wenn kein übereinstimmenden Schlüssel gefunden wird und das RTL_QUERY_REGISTRY_REQUIRED Flag nicht angegeben wird. Geben Sie REG_NONE für keinen Standardtyp an. Wenn das RTL_QUERY_REGISTRY_TYPECHECK Flag festgelegt ist, gibt das wichtigste Byte dieses Elements den REG_XXX- Typ des gespeicherten Registrierungswerts an, den der Aufrufer erwartet. Bits 8 bis 23 dieses Mitglieds sind reserviert und sollten null sein.

DefaultData

Ein Zeiger auf den Standardwert, der zurückgegeben werden soll, wenn kein übereinstimmende Schlüssel gefunden wird und das RTL_QUERY_REGISTRY_REQUIRED Flag nicht angegeben ist. Dieses Element wird ignoriert, wenn DefaultType = REG_NONE. Andernfalls sollte der Datentyp, auf den DefaultData- verweist, dem Registrierungswerttyp entsprechen, der vom DefaultType Member angegeben wird. Weitere Informationen zu Registrierungswerttypen finden Sie in der Definition des parameters Type in KEY_VALUE_BASIC_INFORMATION.

DefaultLength

Gibt die Länge des DefaultData--Elements in Byte an. Wenn DefaultType- REG_SZ, REG_EXPAND_SZ oder REG_MULTI_SZ ist, können Aufrufer optional Null angeben, um anzugeben, RtlQueryRegistryValues die Länge basierend auf dem Standardwert berechnen soll. Wenn DefaultType = REG_NONE, wird dieses Element ignoriert.

[in, optional] Context

Gibt den Wert an, der bei jedem Aufruf als Context-Parameter einer QueryRoutine- Funktion übergeben wird.

[in, optional] Environment

Zeiger auf die Umgebung, die beim Erweitern von Variablenwerten in REG_EXPAND_SZ Registrierungswerten oder einem NULL- Zeiger (optional) verwendet wird.

Rückgabewert

RtlQueryRegistryValues gibt einen NTSTATUS-Code zurück. Zu den möglichen Rückgabewerten gehören:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die gesamte Abfragetabelle wurde erfolgreich verarbeitet.
STATUS_INVALID_PARAMETER	Die Verarbeitung der Abfragetabelle wurde mit einem ungültigen Tabelleneintrag beendet. Ein Tabelleneintrag kann ungültig sein, wenn für die angegebenen Flags die QueryRoutine oder Name Member nichtNULL-erforderlich ist, aber ein NULL- Wert bereitgestellt wurde.
STATUS_OBJECT_NAME_NOT_FOUND	Der Path Parameter stimmt nicht mit einem gültigen Schlüssel überein, oder die Verarbeitung der Abfragetabelle wurde mit einem Eintrag mit dem RTL_QUERY_REGISTRY_REQUIRED Flagsatz beendet, und es wird kein übereinstimmenden Schlüssel gefunden. Dies tritt auf, wenn der Name Member NULL- ist und der aktuelle Schlüssel keine Unterschlüssel aufweist, oder wenn Name einen nicht vorhandenen Unterschlüssel angibt.
STATUS_BUFFER_TOO_SMALL	Das RTL_QUERY_REGISTRY_DIRECT Flag wird festgelegt, und der durch EntryContext- angegebene Puffer ist zu klein, um die Schlüsselwertdaten aufzunehmen.
STATUS_OBJECT_TYPE_MISMATCH	Das flag RTL_QUERY_REGISTRY_TYPECHECK ist festgelegt, und der Typ des gespeicherten Registrierungswerts stimmt nicht mit dem typ überein, der vom Aufrufer erwartet wird.

RtlQueryRegistryValues beendet auch die Verarbeitung der Tabelle, wenn die QueryRoutine--Funktion für einen Tabelleneintrag einen NTSTATUS-Fehlercode zurückgibt und diesen Fehlercode als Ergebnis zurückgibt. (Mit einer Ausnahme: Wenn QueryRoutine STATUS_BUFFER_TOO_SMALL zurückgibt, wird der Fehlercode ignoriert.)

Bemerkungen

Der Aufrufer gibt einen anfänglichen Schlüsselpfad und eine Tabelle an. Die Tabelle enthält mindestens einen Eintrag, der die Schlüsselwerte und Unterschlüsselnamen beschreibt, an denen der Aufrufer interessiert ist. Die Tabelle wird durch einen Eintrag mit einem NULL-QueryRoutine Member und einem NULLName Member beendet. Die Tabelle muss aus nicht seitengebundenen Pools zugewiesen werden.

Kernelmodustreiber müssen das RTL_QUERY_REGISTRY_NOEXPAND Flag angeben, um die Aufrufumgebungsvariablen-Routinen zu verhindern. Diese Routinen sind unsicher, sodass Kernelmodustreiber sie nicht verwenden sollten.

Vorsicht

Wenn Sie das RTL_QUERY_REGISTRY_DIRECT-Flag verwenden, kann eine nicht vertrauenswürdige Benutzermodusanwendung möglicherweise einen Pufferüberlauf verursachen. Ein Pufferüberlauf kann auftreten, wenn ein Treiber dieses Flag verwendet, um einen Registrierungswert zu lesen, dem der falsche Typ zugewiesen ist. In allen Fällen sollte ein Treiber, der das RTL_QUERY_REGISTRY_DIRECT Flag verwendet, zusätzlich das RTL_QUERY_REGISTRY_TYPECHECK Flag verwenden, um solche Überläufe zu verhindern.

Wenn das RTL_QUERY_REGISTRY_TYPECHECK Flag in einem Tabelleneintrag festgelegt ist, muss der Aufrufer den erwarteten REG_XXX- Typ in den 8 wichtigsten Bits (MSBs) des 32-Bit-DefaultType Member des Tabelleneintrags angeben. Wie im folgenden Codebeispiel gezeigt, kann die RTL_QUERY_REGISTRY_TYPECHECK_SHIFT Konstanten, die als 24 definiert ist, als schichtanzahl verwendet werden, die erforderlich ist, um den erwarteten REG_XXX Typ in den 8 MSBs des DefaultType Member zu platzieren.

RTL_QUERY_REGISTRY_TABLE QueryRegTable[2];    
...
QueryRegTable[0].DefaultType = (REG_SZ << RTL_QUERY_REGISTRY_TYPECHECK_SHIFT) | REG_NONE;
...
QueryRegTable[1].DefaultType = (REG_DWORD << RTL_QUERY_REGISTRY_TYPECHECK_SHIFT) | REG_NONE;
...

Ab Windows 8 greift ein RtlQueryRegistryValues- Anruf auf eine nicht vertrauenswürdige Struktur zu, und der Aufrufer legt das RTL_QUERY_REGISTRY_DIRECT Flag für diesen Anruf fest, muss der Aufrufer zusätzlich das RTL_QUERY_REGISTRY_TYPECHECK Flag festlegen. Ein Verstoß gegen diese Regel durch einen Aufruf aus dem Benutzermodus verursacht eine Ausnahme. Ein Verstoß gegen diese Regel durch einen Aufruf aus dem Kernelmodus führt zu einer 0x139 Fehlerüberprüfung (KERNEL_SECURITY_CHECK_FAILURE).

Nur Systemstrukturen sind vertrauenswürdig. Ein RtlQueryRegistryValues- Aufruf, der auf eine Systemstruktur zugreift, verursacht keine Ausnahme oder eine Fehlerüberprüfung, ob das RTL_QUERY_REGISTRY_DIRECT Flag festgelegt ist und das RTL_QUERY_REGISTRY_TYPECHECK Flag nicht festgelegt ist. Als bewährte Methode sollte jedoch immer das RTL_QUERY_REGISTRY_TYPECHECK-Flag festgelegt werden, wenn das RTL_QUERY_REGISTRY_DIRECT Flag festgelegt ist.

Ebenso sollte in Windows-Versionen vor Windows 8 als bewährte Methode ein RtlQueryRegistryValues- Aufruf, der das RTL_QUERY_REGISTRY_DIRECT Flag festlegt, zusätzlich das RTL_QUERY_REGISTRY_TYPECHECK Flag festlegen. Wenn Diese Empfehlung nicht befolgt wird, führt dies jedoch nicht zu einer Ausnahme oder zu einer Fehlerüberprüfung.

Es folgt eine Liste der Systemstrukturen:

\REGISTRY\MACHINE\HARDWARE
\REGISTRY\MACHINE\SOFTWARE
\REGISTRY\MACHINE\SYSTEM
\REGISTRY\MACHINE\SECURITY
\REGISTRY\MACHINE\SAM

Die Unterstützung für die RTL_QUERY_REGISTRY_TYPECHECK-Kennzeichnung ist über Windows Update für Windows 7, Windows Vista, Windows Server 2003 und Windows XP verfügbar. Weitere Informationen zu diesem Update finden Sie unter Sicherheitsanfälligkeiten in Windows Kernel Could Allow Elevation of Privilege (2393802). In Versionen dieser Betriebssysteme, die nicht über dieses Update verfügen, kann der Aufrufer das RTL_QUERY_REGISTRY_TYPECHECK Flag verwenden. Diese Kennzeichnung wird jedoch von der RtlQueryRegistryValues Routine ignoriert.

Ab Windows Driver Kit (WDK) 8 wird das RTL_QUERY_REGISTRY_TYPECHECK Flag in der Wdm.h-Headerdatei wie folgt definiert:

#define RTL_QUERY_REGISTRY_TYPECHECK 0x00000100

Wenn ein Eintrag das RTL_QUERY_REGISTRY_DIRECT-Flag nicht angibt, verwendet RtlQueryRegistryValues die angegebene QueryRoutine- funktion, um den Wertnamen, typ, daten und die Datenlänge an den Aufrufer zu melden. Wenn der Name Mitglied des Eintrags NULL-ist, meldet RtlQueryRegistryValues jeden direkten Unterschlüssel des Schlüssels. Wenn der Schlüsseltyp REG_MULTI_SZ und das RTL_QUERY_REGISTRY_NOEXPAND Flag nicht angegeben ist, ruft die Routine QueryRoutine separat für jede einzelne Zeichenfolge auf; andernfalls meldet die Routine sie als einzelner Wert. Wenn ein Eintrag das RTL_QUERY_REGISTRY_DIRECT-Flag angibt, speichert RtlQueryRegistryValues den Wert des Schlüssels im Puffer, auf den durch das EntryContext Member des Eintrags verwiesen wird. Das Format der zurückgegebenen Daten lautet wie folgt.

Schlüsseldatentyp	Gibt an, wie Daten zurückgegeben werden
Eine mit Null beendete Unicode-Zeichenfolge (z. B. REG_SZ, REG_EXPAND_SZ).	EntryContext- muss auf eine initialisierte UNICODE_STRING Struktur verweisen. Wenn das Buffer Member von UNICODE_STRINGNULL-ist, weist die Routine Speicher für die Zeichenfolgendaten zu. Andernfalls werden die Zeichenfolgendaten im Puffer gespeichert, auf die Buffer verweist.
REG_MULTI_SZ	Sie müssen das kennzeichen RTL_QUERY_REGISTRY_NOEXPAND für diesen Schlüsseldatentyp angeben. EntryContext verweist auf eine initialisierte UNICODE_STRING Struktur. Die Routine speichert den Schlüsselwert als einzelnen Zeichenfolgenwert. Jede einzelne Komponente innerhalb der Zeichenfolge wird durch eine Null beendet. Wenn das Buffer Member von UNICODE_STRINGNULL-ist, weist die Routine Speicher für die Zeichenfolgendaten zu. Andernfalls werden die Zeichenfolgendaten im Puffer gespeichert, auf die Buffer verweist.
Daten ohne Zeichenfolge mit Größe in Bytes <= Größe des(ULONG)	Der Wert wird an dem durch EntryContextangegebenen Speicherspeicherort gespeichert.
Nichtzeichenfolgendaten mit Größe in Byte >Größe von(ULONG)	Der Puffer, auf den EntryContext verweist muss mit einem signierten LONG-Wert beginnen. Die Größe des Werts muss die Größe des Puffers in Bytes angeben. Wenn das Vorzeichen des Werts negativ ist, speichert RtlQueryRegistryValues nur die Daten des Schlüsselwerts. Andernfalls wird der erste ULONG-Wert im Puffer verwendet, um die Wertlänge in Bytes, die zweite ULONG zum Aufzeichnen des Werttyps und den rest des Puffers zum Speichern der Wertdaten zu verwenden.

Wenn ein Fehler in einer Phase der Verarbeitung der Abfragetabelle auftritt, RtlQueryRegistryValues beendet die Verarbeitung der Tabelle und gibt den Fehlerstatus zurück.

Eine Beschreibung der möglichen REG_XXX- finden Sie unter ZwSetValueKey-.