RegGetValueA-Funktion (winreg.h)

Artikel
03/11/2023

Ruft den Typ und die Daten für den angegebenen Registrierungswert ab.

Syntax

LSTATUS RegGetValueA(
  [in]                HKEY    hkey,
  [in, optional]      LPCSTR  lpSubKey,
  [in, optional]      LPCSTR  lpValue,
  [in, optional]      DWORD   dwFlags,
  [out, optional]     LPDWORD pdwType,
  [out, optional]     PVOID   pvData,
  [in, out, optional] LPDWORD pcbData
);

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_PERFORMANCE_NLSTEXT

HKEY_PERFORMANCE_TEXT

HKEY_USERS

[in, optional] lpSubKey

Der Pfad eines Registrierungsschlüssels relativ zum durch den hkey-Parameter angegebenen Schlüssel. Der Registrierungswert wird aus diesem Unterschlüssel abgerufen.

Beim Pfad wird die Groß-/Kleinschreibung nicht beachtet.

Wenn dieser Parameter NULL oder eine leere Zeichenfolge , "", ist, wird der Wert aus dem Schlüssel gelesen, der von hkey selbst angegeben wird.

[in, optional] lpValue

Der Name des Registrierungswerts.

Wenn dieser Parameter NULL oder eine leere Zeichenfolge "" ist, ruft die Funktion den Typ und die Daten für den unbenannten oder Standardwert des Schlüssels ab, falls vorhanden. Schlüssel verfügen nicht automatisch über einen unbenannten oder Standardwert, und unbenannte Werte können einen beliebigen Typ aufweisen.

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

[in, optional] dwFlags

Die Flags, die den datentyp des abzufragenden Werts einschränken. Wenn der Datentyp des Werts diese Kriterien nicht erfüllt, schlägt die Funktion fehl. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln.

Wert	Bedeutung
RRF_RT_ANY 0x0000ffff	Keine Typeinschränkung.
RRF_RT_DWORD 0x00000018	Einschränken des Typs auf 32-Bit-RRF_RT_REG_BINARY \| RRF_RT_REG_DWORD.
RRF_RT_QWORD 0x00000048	Einschränken des Typs auf 64-Bit-RRF_RT_REG_BINARY \| RRF_RT_REG_QWORD.
RRF_RT_REG_BINARY 0x00000008	Beschränken Sie den Typ auf REG_BINARY.
RRF_RT_REG_DWORD 0x00000010	Beschränken Sie den Typ auf REG_DWORD.
RRF_RT_REG_EXPAND_SZ 0x00000004	Beschränken Sie den Typ auf REG_EXPAND_SZ.
RRF_RT_REG_MULTI_SZ 0x00000020	Beschränken Sie den Typ auf REG_MULTI_SZ.
RRF_RT_REG_NONE 0x00000001	Beschränken Sie den Typ auf REG_NONE.
RRF_RT_REG_QWORD 0x00000040	Beschränken Sie den Typ auf REG_QWORD.
RRF_RT_REG_SZ 0x00000002	Beschränken Sie den Typ auf REG_SZ.

Dieser Parameter kann auch einen oder mehrere der folgenden Werte enthalten.

Wert	Bedeutung
RRF_NOEXPAND 0x10000000	Erweitern Sie Umgebungszeichenfolgen nicht automatisch, wenn der Wert vom Typ REG_EXPAND_SZ ist.
RRF_ZEROONFAILURE 0x20000000	Wenn pvData nicht NULL ist, legen Sie den Inhalt des Puffers bei Einem Fehler auf Nullen fest.
RRF_SUBKEY_WOW6464KEY 0x00010000	Wenn lpSubKey nicht NULL ist, öffnen Sie den Unterschlüssel, den lpSubKey mit dem KEY_WOW64_64KEY Zugriffsrechten angibt. Informationen zu diesen Zugriffsrechten finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel. Sie können RRF_SUBKEY_WOW6464KEY nicht in Kombination mit RRF_SUBKEY_WOW6432KEY angeben.
RRF_SUBKEY_WOW6432KEY 0x00020000	Wenn lpSubKey nicht NULL ist, öffnen Sie den Unterschlüssel, den lpSubKey mit dem KEY_WOW64_32KEY Zugriffsrechten angibt. Informationen zu diesen Zugriffsrechten finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel. Sie können RRF_SUBKEY_WOW6432KEY nicht in Kombination mit RRF_SUBKEY_WOW6464KEY angeben.

[out, optional] pdwType

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. Dieser Parameter kann NULL sein, wenn der Typ nicht erforderlich ist.

[out, optional] pvData

Ein Zeiger auf einen Puffer, der die Daten des Werts empfängt. Dieser Parameter kann NULL sein, wenn die Daten nicht erforderlich sind.

Wenn es sich bei den Daten um eine Zeichenfolge handelt, sucht die Funktion nach einem beendenden NULL-Zeichen . Wenn eine nicht gefunden wird, wird die Zeichenfolge mit einem NULL-Abschlussator gespeichert, wenn der Puffer groß genug ist, um das zusätzliche Zeichen aufzunehmen. Andernfalls schlägt die Funktion fehl und gibt ERROR_MORE_DATA zurück.

[in, out, optional] pcbData

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

Der pcbData-Parameter kann nur NULL sein, wenn pvDataNULL 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 vom pvData-Parameter 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 pcbData verwiesen wird. In diesem Fall sind die Inhalte des pvData-Puffers Nullen, wenn dwFlags RRF_ZEROONFAILURE angibt und andernfalls nicht definiert ist.

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

Wenn hKeyHKEY_PERFORMANCE_DATA angibt und der pvData-Puffer nicht groß genug ist, um alle zurückgegebenen Daten zu enthalten, gibt die Funktion ERROR_MORE_DATA zurück, und der über den parameter pcbData zurückgegebene Wert ist nicht definiert. Dies liegt daran, dass sich die Größe der Leistungsdaten von einem Aufruf zum nächsten ändern kann. In diesem Fall müssen Sie die Puffergröße erhöhen und RegGetValue erneut aufrufen und die aktualisierte Puffergröße im parameter pcbData übergeben. Wiederholen Sie dies, bis die Funktion erfolgreich ist. Sie müssen eine separate Variable verwalten, um die Puffergröße nachzuverfolgen, da der von pcbData zurückgegebene Wert unvorhersehbar ist.

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 pvData-Puffer zu klein ist, um den Wert zu erhalten, gibt die Funktion ERROR_MORE_DATA zurück.

Wenn der Registrierungswert lpValue nicht vorhanden ist, gibt die Funktion ERROR_FILE_NOT_FOUND zurück.

Wenn dwFlags eine Kombination aus RRF_SUBKEY_WOW6464KEY und RRF_SUBKEY_WOW6432KEY angibt, gibt die Funktion ERROR_INVALID_PARAMETER zurück.

Bemerkungen

Eine Anwendung ruft in der Regel RegEnumValue auf, um die Wertnamen zu bestimmen, und regGetValue , um die Daten für die Namen abzurufen.

Wenn die Daten den REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ aufweisen und die ANSI-Version dieser Funktion verwendet wird (entweder durch expliziten Aufruf von RegGetValueA oder durch nicht definierte UNICODE vor dem Einschließen der Datei Windows.h), konvertiert diese Funktion die gespeicherte Unicode-Zeichenfolge in eine ANSI-Zeichenfolge, bevor sie in den Puffer kopiert wird, auf den von pvData verwiesen wird.

Wenn Sie diese Funktion aufrufen, wobei hkey auf das HKEY_PERFORMANCE_DATA-Handle und eine Wertzeichenfolge eines angegebenen Objekts festgelegt ist, enthält die zurückgegebene Datenstruktur manchmal nicht angeforderte Objekte. Wundern Sie sich nicht; Dies ist ein normales Verhalten. Sie sollten immer erwarten, dass Sie die zurückgegebene Datenstruktur durchlaufen, um nach dem angeforderten Objekt zu suchen.

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.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0600 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Hinweis

Der winreg.h-Header definiert RegGetValue 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 Vista, Windows XP Professional x64 Edition
Unterstützte Mindestversion (Server)	Windows Server 2008, Windows Server 2003 mit SP1
Zielplattform	Windows
Kopfzeile	winreg.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll