RegEnumValueA-Funktion (winreg.h)

Artikel
11/20/2024

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

Da Werte nicht sortiert sind, hat jeder neue Wert einen beliebigen Index. 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--terminated-Zeichenfolge empfängt.

Dieser Puffer muss groß genug sein, um das Beenden NULL-zeichens einzuschließen.

Weitere Informationen finden Sie unter Registrierungselementgrößenbeschränkungen.

[in, out] lpcchValueName

Ein Zeiger auf eine Variable, der die Größe des Puffers angibt, auf den der lpValueName Parameter in Zeichen verweist. Wenn die Funktion zurückgegeben wird, empfängt die Variable die Anzahl der zeichen, die im Puffer gespeichert sind, nicht einschließlich des endenden null- Zeichens.

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 durch lpValueName verweist, wird nicht geändert. In diesem Fall sind die Inhalte 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 daher einen Wert angeben, der größer als 32.767 Byte ist, gibt es einen Überlauf, und die Funktion kann ERROR_MORE_DATA zurückgeben.

lpReserved

Dieser Parameter ist reserviert und muss NULL-sein.

[out, optional] lpType

Ein Zeiger auf eine Variable, die einen Code empfängt, der den Datentyp angibt, der im angegebenen Wert gespeichert ist. Eine Liste der möglichen Typcodes finden Sie unter Registrierungswerttypen. Der parameter lpType 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- werden, wenn die Daten nicht erforderlich sind.

Wenn lpData-NULL- ist und lpcbData- nichtNULL-ist, speichert die Funktion die Größe der Daten in Bytes in der Variablen, auf die durch lpcbDataverwiesen wird. Auf diese Weise kann eine Anwendung die beste Methode zum Zuordnen 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 Byte verweist. Wenn die Funktion zurückgegeben wird, empfängt die Variable die Anzahl der im Puffer gespeicherten Bytes.

Dieser Parameter kann nur NULL- werden, wenn lpData-NULL-ist.

Wenn die Daten über die REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ verfügen, enthält diese Größe alle endenden NULL- Zeichen oder Zeichen. Weitere Informationen finden Sie in den Hinweisen.

Wenn der durch lpData- angegebene Puffer nicht groß genug ist, um die Daten zu speichern, gibt die Funktion ERROR_MORE_DATA zurück und speichert die erforderliche Puffergröße in der Variablen, auf die durch lpcbDataverwiesen wird. In diesem Fall sind die Inhalte 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 erhalten, gibt die Funktion ERROR_MORE_DATA zurück.

Bemerkungen

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

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

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

Wenn die Daten den REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ aufweisen, wurde die Zeichenfolge möglicherweise nicht mit den richtigen NULL-zeichen-endating-Zeichen gespeichert. Selbst wenn die Funktion ERROR_SUCCESS zurückgibt, sollte die Anwendung daher sicherstellen, dass die Zeichenfolge ordnungsgemäß beendet wird, bevor sie verwendet wird; andernfalls kann ein Puffer überschrieben werden. (Beachten Sie, dass REG_MULTI_SZ Zeichenfolgen zwei null-endating characters aufweisen sollen.)

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

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 RegEnumValue 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 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