ZwSetValueKey-Funktion (wdm.h)

Artikel
02/29/2024

Die ZwSetValueKey-Routine erstellt oder ersetzt den Werteintrag eines Registrierungsschlüssels.

Syntax

NTSYSAPI NTSTATUS ZwSetValueKey(
  [in]           HANDLE          KeyHandle,
  [in]           PUNICODE_STRING ValueName,
  [in, optional] ULONG           TitleIndex,
  [in]           ULONG           Type,
  [in, optional] PVOID           Data,
  [in]           ULONG           DataSize
);

Parameter

[in] KeyHandle

Behandeln Sie den Registrierungsschlüssel, für den ein Werteintrag geschrieben werden soll. Dieses Handle wird durch einen erfolgreichen Aufruf von ZwCreateKey oder ZwOpenKey erstellt.

[in] ValueName

Zeiger auf den Namen des Werteintrags, für den die Daten geschrieben werden sollen. Dieser Parameter kann ein NULL-Zeiger sein, wenn der Werteintrag keinen Namen hat. Wenn eine Namenszeichenfolge angegeben wird und der angegebene Name relativ zum enthaltenden Schlüssel nicht eindeutig ist, werden die Daten für einen vorhandenen Werteintrag ersetzt.

[in, optional] TitleIndex

Dieser Parameter ist reserviert. Geräte- und Zwischentreiber sollten diesen Parameter auf Null festlegen.

[in] Type

Einer der folgenden systemdefinierten Datentypen zum Schreiben:

Typwert	Bedeutung
REG_BINARY	Binärdaten in beliebiger Form.
REG_DWORD	Ein numerischer Wert von 4 Byte.
REG_DWORD_LITTLE_ENDIAN	Ein numerischer Wert von 4 Byte mit dem geringsten Byte an der niedrigsten Adresse. Identisch mit REG_DWORD.
REG_DWORD_BIG_ENDIAN	Ein numerischer Wert von 4 Byte mit dem geringsten Byte an der höchsten Adresse.
REG_EXPAND_SZ	Eine Unicode-Zeichenfolge mit Null-Beendigung, die nicht erweitere Verweise auf Umgebungsvariablen enthält, z. B. "%PATH%".
REG_LINK	Eine Unicode-Zeichenfolge, die einen symbolischen Link benennt. Dieser Typ ist für Geräte- und Zwischentreiber irrelevant.
REG_MULTI_SZ	Ein Array von NULL-beendeten Zeichenfolgen, das durch eine andere Null beendet wird.
REG_NONE	Daten ohne bestimmten Typ.
REG_SZ	Eine null-terminierte Unicode-Zeichenfolge.
REG_RESOURCE_LIST	Die Liste der Hardwareressourcen eines Gerätetreibers, die vom Treiber oder einem der von diesem gesteuerten physischen Geräte verwendet wird, in der Struktur \ResourceMap
REG_RESOURCE_REQUIREMENTS_LIST	Die Liste der möglichen Hardwareressourcen eines Gerätetreibers oder eines der von ihr gesteuerten physischen Geräte, aus denen das System eine Teilmenge in die Struktur \ResourceMap schreibt
REG_FULL_RESOURCE_DESCRIPTOR	Eine Liste der Hardwareressourcen, die ein physisches Gerät verwendet, erkannt und vom System in die Struktur \HardwareDescription geschrieben wird.

Gerätetreiber sollten nicht versuchen, ZwSetValueKey aufzurufen, um Werteinträge explizit in einen Unterschlüssel des Schlüssels \Registry...\ResourceMap zu schreiben. Nur das System kann Werteinträge in die Struktur \Registry...\HardwareDescription schreiben.

[in, optional] Data

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Daten für den Werteintrag enthält.

[in] DataSize

Gibt die Größe des Datenpuffers in Bytes an. Wenn Type REG_XXX_SZ ist, muss dieser Wert Speicherplatz für alle beendenden Nullen enthalten.

Rückgabewert

ZwSetValueKey gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Routine möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_ACCESS_DENIED	Der Aufrufer hat keinen entsprechenden Zugriff auf den Registrierungswert.
STATUS_INVALID_HANDLE	Das Handle ist ungültig.

Hinweise

Das an ZwSetValueKey übergebeneKeyHandle muss mit dem KEY_SET_VALUE DesiredAccess-Flag geöffnet worden sein, damit dieser Aufruf erfolgreich ist. Eine Beschreibung der möglichen Werte für DesiredAccess finden Sie unter ZwCreateKey.

Wenn der angegebene Schlüssel keinen vorhandenen Werteintrag mit einem Namen aufweist, der mit dem angegebenen ValueName übereinstimmt, erstellt ZwSetValueKey einen neuen Werteintrag mit dem angegebenen Namen. Wenn ein übereinstimmender Werteintragsname vorhanden ist, überschreibt diese Routine den ursprünglichen Werteintrag für den angegebenen ValueName. Daher behält ZwSetValueKey einen eindeutigen Namen für jeden Werteintrag eines bestimmten Schlüssels bei. Während jeder Werteintragsname für seinen enthaltenden Schlüssel eindeutig sein muss, können viele verschiedene Schlüssel in der Registrierung Werteinträge mit denselben Namen aufweisen.

Weitere Informationen zum Arbeiten mit Registrierungsschlüsseln finden Sie unter Verwenden der Registrierung in einem Treiber.

Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtSetValueKey" anstelle von "ZwSetValueKey" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)