RegSetValueExA-Funktion (winreg.h)

Artikel
03/06/2024

Legt die Daten und den Typ eines angegebenen Werts unter einem Registrierungsschlüssel fest.

Syntax

LSTATUS RegSetValueExA(
  [in]           HKEY       hKey,
  [in, optional] LPCSTR     lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

Parameter

[in] hKey

Ein Handle für einen geöffneten Registrierungsschlüssel. Der Schlüssel muss mit dem Zugriffsrecht KEY_SET_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

Die Unicode-Version dieser Funktion unterstützt die folgenden zusätzlichen vordefinierten Schlüssel:

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

Der Name des festzulegenden Werts. Wenn ein Wert mit diesem Namen noch nicht im Schlüssel vorhanden ist, fügt die Funktion ihn dem Schlüssel hinzu.

Wenn lpValueNameNULL oder eine leere Zeichenfolge ist, legt die Funktion den Typ und die Daten für den unbenannten oder Standardwert des Schlüssels fest.

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

Registrierungsschlüssel haben keine Standardwerte, aber sie können einen unbenannten Wert haben, der von einem beliebigen Typ sein kann.

Reserved

Dieser Parameter ist reserviert und muss null sein.

[in] dwType

Der Datentyp, auf den der lpData-Parameter verweist. Eine Liste der möglichen Typen finden Sie unter Registrierungswerttypen.

[in] lpData

Die zu speichernden Daten.

Bei zeichenfolgenbasierten Typen, z. B. REG_SZ, muss die Zeichenfolge NULL-endend sein. Mit dem Datentyp REG_MULTI_SZ muss die Zeichenfolge mit zwei NULL-Zeichen beendet werden.

Beachten Sie , dass lpData, der einen NULL-Wert angibt, gültig ist. Wenn dies jedoch der Fall ist, muss cbData auf "0" festgelegt werden.

[in] cbData

Die Größe der Informationen, auf die der lpData-Parameter in Bytes verweist. Wenn die Daten vom Typ REG_SZ, REG_EXPAND_SZ oder REG_MULTI_SZ sind, muss cbData die Größe des oder der abschließenden NULL-Zeichen enthalten.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein in Winerror.h definierter Fehlercode ungleich null. Sie können die FormatMessage-Funktion mit dem flag FORMAT_MESSAGE_FROM_SYSTEM verwenden, um eine generische Beschreibung des Fehlers abzurufen.

Hinweise

Die Wertgrößen werden durch den verfügbaren Arbeitsspeicher begrenzt. Das Speichern großer Werte in der Registrierung kann sich jedoch auf die Leistung auswirken. Lange Werte (mehr als 2.048 Bytes) sollten als Dateien gespeichert werden, wobei die Speicherorte der Dateien in der Registrierung gespeichert werden.

Anwendungselemente wie Symbole, Bitmaps und ausführbare Dateien sollten als Dateien gespeichert und nicht in der Registrierung platziert werden.

Wenn dwType der REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ ist und die ANSI-Version dieser Funktion verwendet wird (entweder durch expliziten Aufruf von RegSetValueExA oder durch Nichtdefinition von UNICODE vor dem Einschließen der Datei Windows.h), müssen die Daten, auf die der lpData-Parameter verweist, eine ANSI-Zeichenfolge sein. Die Zeichenfolge wird in Unicode konvertiert, bevor sie in der Registrierung gespeichert wird.

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.

Erwägen Sie die Verwendung der RegSetKeyValue-Funktion , die eine bequemere Möglichkeit zum Festlegen des Werts eines Registrierungsschlüssels bietet.

Hinweis

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