RegEnumKeyExA-Funktion (winreg.h)
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 zu einem geöffneten Registrierungsschlüssel. Der Schlüssel muss mit dem KEY_ENUMERATE_SUB_KEYS Zugriffsrecht geöffnet worden sein. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.
Dieses Handle wird von der RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExoder RegOpenKeyTransacted Funktion zurückgegeben. Es kann auch einer der folgenden vordefinierten Schlüsselsein:
- 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 erhöht 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 Endvorgangs 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 Registrierungselementgrößenbeschränkungen.
[in, out] lpcchName
Ein Zeiger auf eine Variable, der die Größe des durch den parameter lpName parameter angegebenen Puffers in Zeichen angibt. Diese Größe sollte das beendende null Zeichen enthalten. Wenn die Funktion erfolgreich ausgeführt wird, enthält die Variable, auf die durch lpcchName verweist, die Anzahl der im Puffer gespeicherten Zeichen, nicht einschließlich des endenden Null- Zeichens.
Um die erforderliche Puffergröße zu ermitteln, 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, der die Größe des durch den parameter lpClass angegebenen Puffers in Zeichen angibt. Die Größe sollte das beendende null Zeichen enthalten. Wenn die Funktion erfolgreich ist, enthält lpcchClass- die Anzahl der im Puffer gespeicherten Zeichen, nicht einschließlich des endenden NULL- Zeichens. Dieser Parameter kann nur NULL- werden, wenn lpClass-NULL-ist.
[out, optional] lpftLastWriteTime
Ein Zeiger auf 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 lpName Puffer 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 inkrementieren und RegEnumKeyEx aufrufen, bis keine Weiteren Unterschlüssel vorhanden sind (d. h. die Funktion gibt ERROR_NO_MORE_ITEMS zurück).
Die Anwendung kann auch dwIndex- auf den Index des letzten Unterschlüssels für den ersten Aufruf der Funktion festlegen und den Index verringern, bis der Unterschlüssel mit dem Index 0 aufgezählt wird. Um den Index des letzten Unterschlüssels abzurufen, verwenden Sie die RegQueryInfoKey--Funktion.
Während eine Anwendung die RegEnumKeyEx--Funktion verwendet, sollte sie keine Aufrufe an Registrierungsfunktionen durchführen, die den aufgezählten Schlüssel ändern können.
Beachten Sie, dass Vorgänge, die auf bestimmte Registrierungsschlüssel zugreifen, umgeleitet werden. Weitere Informationen finden Sie unter Registry Virtualization und 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.
Anmerkung
In älteren Versionen von Windows wird diese API auch von kernel32.dllverfügbar gemacht.
Beispiele
Ein Beispiel finden Sie unter Aufzählen von Registrierungsunterschlüsseln.
Anmerkung
Der winreg.h-Header definiert RegEnumKeyEx als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias 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
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 Professional [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winreg.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |