RegEnumValueA-Funktion (winreg.h)

Artikel
08/27/2023

Listet die Werte für den angegebenen offenen Registrierungsschlüssel auf. Die Funktion kopiert bei jedem Aufruf einen indizierten Wertnamen und einen Datenblock für den Schlüssel.

Syntax

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   lpValueName,
  [in, out]           LPDWORD lpcchValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

Parameter

[in] hKey

Ein Handle für einen geöffneten Registrierungsschlüssel. Der Schlüssel muss mit dem zugriffsrecht KEY_QUERY_VALUE 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 Werts. Dieser Parameter sollte für den ersten Aufruf der RegEnumValue-Funktion null und dann für nachfolgende Aufrufe erhöht werden.

Da Werte nicht sortiert werden, weist jeder neue Wert einen beliebigen Index auf. Dies bedeutet, dass die Funktion Werte in beliebiger Reihenfolge zurückgeben kann.

[out] lpValueName

Ein Zeiger auf einen Puffer, der den Namen des Werts als NULL-Zeichenfolge empfängt.

Dieser Puffer muss groß genug sein, um das beendende NULL-Zeichen zu enthalten.

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

[in, out] lpcchValueName

Ein Zeiger auf eine Variable, die die Größe des Puffers angibt, auf den der lpValueName-Parameter in Zeichen verweist. Wenn die Funktion zurückgibt, empfängt die Variable die Anzahl von Zeichen, die im Puffer gespeichert sind, ohne das beendende NULL-Zeichen .

Wenn der durch lpValueName angegebene Puffer nicht groß genug ist, um die Daten aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück, und die Puffergröße in der Variablen, auf die von lpValueName verwiesen wird, wird nicht geändert. In diesem Fall ist der Inhalt von lpcchValueName nicht definiert.

Registrierungswertnamen sind auf 32.767 Bytes beschränkt. Die ANSI-Version dieser Funktion behandelt diesen Parameter als SHORT-Wert . Wenn Sie also einen Wert größer als 32.767 Bytes angeben, tritt ein Überlauf auf, und die Funktion gibt möglicherweise ERROR_MORE_DATA zurück.

lpReserved

Dieser Parameter ist reserviert und muss NULL sein.

[out, optional] lpType

Ein Zeiger auf eine Variable, die einen Code empfängt, der den Typ der im angegebenen Wert gespeicherten Daten angibt. Eine Liste der möglichen Typcodes finden Sie unter Registrierungswerttypen. Der lpType-Parameter kann NULL sein, wenn der Typcode nicht erforderlich ist.

[out, optional] lpData

Ein Zeiger auf einen Puffer, der die Daten für den Werteintrag empfängt. Dieser Parameter kann NULL sein, wenn die Daten nicht erforderlich sind.

Wenn lpDataNULL und lpcbData nicht NULL ist, speichert die Funktion die Größe der Daten in Bytes in der Variablen, auf die von lpcbData verwiesen wird. Dadurch kann eine Anwendung die beste Methode zum Zuweisen eines Puffers für die Daten ermitteln.

[in, out, optional] lpcbData

Ein Zeiger auf eine Variable, der die Größe des Puffers angibt, auf den der lpData-Parameter in Bytes verweist. Wenn die Funktion zurückgibt, empfängt die Variable die Anzahl der im Puffer gespeicherten Bytes.

Dieser Parameter kann nur NULL sein, wenn lpDataNULL ist.

Wenn die Daten über den typ REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ verfügen, umfasst diese Größe alle beendenden NULL-Zeichen oder Zeichen. Weitere Informationen finden Sie in den Hinweisen.

Wenn der von lpData angegebene Puffer nicht groß genug ist, um die Daten aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück und speichert die erforderliche Puffergröße in der Variablen, auf die von lpcbData verwiesen wird. In diesem Fall ist der Inhalt von lpData nicht definiert.

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 Werte verfügbar sind, gibt die Funktion ERROR_NO_MORE_ITEMS zurück.

Wenn der durch lpValueName oder lpData angegebene Puffer zu klein ist, um den Wert zu empfangen, gibt die Funktion ERROR_MORE_DATA zurück.

Hinweise

Zum Auflisten von Werten sollte eine Anwendung zunächst die RegEnumValue-Funktion aufrufen, wobei der dwIndex-Parameter auf 0 festgelegt ist. Die Anwendung sollte dann dwIndex erhöhen und die RegEnumValue-Funktion aufrufen, bis keine weiteren Werte vorhanden sind (bis die Funktion ERROR_NO_MORE_ITEMS zurückgibt).

Die Anwendung kann dwIndex auch auf den Index des letzten Werts beim ersten Aufruf der Funktion festlegen und den Index dekrementieren, bis der Wert mit Index 0 aufgezählt wird. Um den Index des letzten Werts abzurufen, verwenden Sie die RegQueryInfoKey-Funktion .

Bei verwendung von RegEnumValue sollte eine Anwendung keine Registrierungsfunktionen aufrufen, die den abgefragten Schlüssel ändern könnten.

Wenn die Daten über den typ REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ verfügen, wurde die Zeichenfolge möglicherweise nicht mit den richtigen NULL-Endzeichen gespeichert. Selbst wenn die Funktion ERROR_SUCCESS zurückgibt, sollte die Anwendung daher sicherstellen, dass die Zeichenfolge ordnungsgemäß beendet wird, bevor sie sie verwendet. Andernfalls kann ein Puffer überschrieben werden. (Beachten Sie, dass REG_MULTI_SZ Zeichenfolgen zwei NULL-Endzeichen aufweisen sollten.)

Verwenden Sie die RegQueryInfoKey-Funktion , um die maximale Größe des Namens und der Datenpuffer zu bestimmen.

Hinweis

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

Beispiele

Ein Beispiel finden Sie unter Aufzählung von Registrierungsunterschlüsseln.

Hinweis

Der winreg.h-Header definiert RegEnumValue 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 nicht codierungsneutralem Code 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 (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll