RegEnumKeyExA-Funktion (winreg.h)

Artikel
03/11/2023

Listet die Unterschlüssel des angegebenen geöffneten Registrierungsschlüssels auf. Die Funktion ruft bei jedem Aufruf Informationen zu einem Unterschlüssel ab.

Syntax

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

Parameter

[in] hKey

Ein Handle für einen geöffneten Registrierungsschlüssel. Der Schlüssel muss mit dem Zugriffsrecht KEY_ENUMERATE_SUB_KEYS geöffnet worden sein. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.

Dieses Handle wird von der RegCreateKeyEx-, RegCreateKeyTransacted-, RegOpenKeyEx- oder RegOpenKeyTransacted-Funktion zurückgegeben. Es kann auch einer der folgenden vordefinierten Schlüssel sein:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

Der Index des abzurufenden Unterschlüssels. Dieser Parameter sollte für den ersten Aufruf der RegEnumKeyEx-Funktion null sein und dann für nachfolgende Aufrufe inkrementiert werden.

Da Unterschlüssel nicht sortiert sind, verfügt jeder neue Unterschlüssel über einen beliebigen Index. Dies bedeutet, dass die Funktion Unterschlüssel in beliebiger Reihenfolge zurückgeben kann.

[out] lpName

Ein Zeiger auf einen Puffer, der den Namen des Unterschlüssels empfängt, einschließlich des abschließenden NULL-Zeichens. Die Funktion kopiert nur den Namen des Unterschlüssels, nicht die vollständige Schlüsselhierarchie, in den Puffer.

Wenn die Funktion fehlschlägt, werden keine Informationen in diesen Puffer kopiert.

Weitere Informationen finden Sie unter Größenbeschränkungen für Registrierungselemente.

[in, out] lpcchName

Ein Zeiger auf eine Variable, die die Größe des Puffers angibt, der durch den lpName-Parameter in Zeichen angegeben wird. Diese Größe sollte das abschließende NULL-Zeichen enthalten. Wenn die Funktion erfolgreich ist, enthält die Variable, auf die von lpcchName verwiesen wird, die Anzahl der im Puffer gespeicherten Zeichen, ohne das abschließende NULL-Zeichen .

Um die erforderliche Puffergröße zu bestimmen, verwenden Sie die RegQueryInfoKey-Funktion , um die Größe des größten Unterschlüssels für den schlüssel zu bestimmen, der durch den hKey-Parameter identifiziert wird.

lpReserved

Dieser Parameter ist reserviert und muss NULL sein.

[in, out] lpClass

Ein Zeiger auf einen Puffer, der die benutzerdefinierte Klasse des aufgezählten Unterschlüssels empfängt. Dieser Parameter kann NULL sein.

[in, out, optional] lpcchClass

Ein Zeiger auf eine Variable, die die Größe des Puffers angibt, der durch den lpClass-Parameter in Zeichen angegeben wird. Die Größe sollte das endende NULL-Zeichen enthalten. Wenn die Funktion erfolgreich ist, enthält lpcchClass die Anzahl der im Puffer gespeicherten Zeichen, ohne das abschließende NULL-Zeichen . Dieser Parameter kann nur NULL sein, wenn lpClassNULL ist.

[out, optional] lpftLastWriteTime

Ein Zeiger auf die FILETIME-Struktur , die den Zeitpunkt empfängt, zu dem der aufgezählte Unterschlüssel zuletzt geschrieben wurde. Dieser Parameter kann NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode. Wenn keine Weiteren Unterschlüssel verfügbar sind, gibt die Funktion ERROR_NO_MORE_ITEMS zurück.

Wenn der puffer lpName zu klein ist, um den Namen des Schlüssels zu erhalten, gibt die Funktion ERROR_MORE_DATA zurück.

Bemerkungen

Zum Aufzählen von Unterschlüsseln sollte eine Anwendung zunächst die RegEnumKeyEx-Funktion aufrufen, wobei der dwIndex-Parameter auf null festgelegt ist. Die Anwendung sollte dann den dwIndex-Parameter erhöhen und RegEnumKeyEx aufrufen, bis keine Weiteren Unterschlüssel vorhanden sind (d. h. die Funktion gibt ERROR_NO_MORE_ITEMS zurück).

Die Anwendung kann dwIndex auch beim ersten Aufruf der Funktion auf den Index des letzten Unterschlüssels festlegen und den Index dekrementieren, bis der Unterschlüssel mit dem Index 0 aufgezählt wird. Verwenden Sie die RegQueryInfoKey-Funktion , um den Index des letzten Unterschlüssels abzurufen.

Während eine Anwendung die RegEnumKeyEx-Funktion verwendet, sollte sie keine Registrierungsfunktionen aufrufen, die den aufgezählten Schlüssel ändern könnten.

Beachten Sie, dass Vorgänge, die auf bestimmte Registrierungsschlüssel zugreifen, umgeleitet werden. Weitere Informationen finden Sie unter Registrierungsvirtualisierung und 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.

Hinweis

In Legacyversionen von Windows wird diese API auch von kernel32.dll verfügbar gemacht.

Beispiele

Ein Beispiel finden Sie unter Auflisten von Registrierungsunterschlüsseln.

Hinweis

Der winreg.h-Header definiert RegEnumKeyEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Aliases mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winreg.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll