RegQueryValueA-Funktion (winreg.h)

Artikel
08/27/2023

Ruft die Daten ab, die dem Standardwert oder dem unbenannten Wert eines angegebenen Registrierungsschlüssels zugeordnet sind. Die Daten müssen eine NULL-endende Zeichenfolge sein.

Hinweis Diese Funktion wird nur aus Gründen der Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Anwendungen sollten die RegQueryValueEx-Funktion verwenden.

Syntax

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  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_USERS

[in, optional] lpSubKey

Der Name des Unterschlüssels des hKey-Parameters , für den der Standardwert abgerufen wird.

Bei Schlüsselnamen wird die Groß-/Kleinschreibung nicht beachtet.

Wenn dieser Parameter NULL ist oder auf eine leere Zeichenfolge zeigt, ruft die Funktion den Standardwert für den durch hKey identifizierten Schlüssel ab.

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

[out, optional] lpData

Ein Zeiger auf einen Puffer, der den Standardwert des angegebenen Schlüssels empfängt.

Wenn lpValueNULL und lpcbValue ungleich NULL ist, gibt die Funktion ERROR_SUCCESS zurück und speichert die Größe der Daten in Bytes in der Variablen, auf die von lpcbValue verwiesen wird. Dadurch kann eine Anwendung die beste Methode zum Zuordnen eines Puffers für die Daten des Werts ermitteln.

[in, out, optional] lpcbData

Ein Zeiger auf eine Variable, der die Größe des Puffers angibt, auf den der lpValue-Parameter in Bytes verweist. Wenn die Funktion zurückgibt, enthält diese Variable die Größe der in lpValue kopierten Daten, einschließlich aller endenden NULL-Zeichen .

Wenn die Daten den typ "REG_SZ", "REG_MULTI_SZ" oder "REG_EXPAND_SZ" aufweisen, schließt diese Größe alle endenden NULL-Zeichen oder -Zeichen ein. Weitere Informationen finden Sie in den Hinweisen.

Wenn der angegebene Puffer lpValue 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 lpcbValue verwiesen wird. In diesem Fall ist der Inhalt des lpValue-Puffers 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 der lpValue-Puffer zu klein ist, um den Wert zu empfangen, gibt die Funktion ERROR_MORE_DATA zurück.

Hinweise

Wenn die ANSI-Version dieser Funktion verwendet wird (entweder durch expliziten Aufruf von RegQueryValueA oder durch Nichtdefinition von UNICODE vor dem Einschließen der Datei Windows.h), konvertiert diese Funktion die gespeicherte Unicode-Zeichenfolge in eine ANSI-Zeichenfolge, bevor sie in den durch den lpValue-Parameter angegebenen Puffer kopiert wird.

Wenn die Daten über den REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ verfügen, wurde die Zeichenfolge möglicherweise nicht mit den richtigen Nullabschlusszeichen 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-Endzeichen enthalten sollten.)

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

Der winreg.h-Header definiert RegQueryValue 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


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