Funzione ZwSetValueKey (wdm.h)

Articolo
03/08/2023

La routine ZwSetValueKey crea o sostituisce la voce del valore di una chiave del Registro di sistema.

Sintassi

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

Parametri

[in] KeyHandle

Gestire la chiave del Registro di sistema per scrivere una voce di valore. Questo handle viene creato da una chiamata riuscita a ZwCreateKey o ZwOpenKey.

[in] ValueName

Puntatore al nome della voce del valore per cui i dati devono essere scritti. Questo parametro può essere un puntatore NULL se la voce del valore non ha alcun nome. Se viene specificata una stringa di nome e il nome specificato non è univoco rispetto alla chiave contenente, i dati per una voce di valore esistente vengono sostituiti.

[in, optional] TitleIndex

Questo parametro è riservato. I driver intermedi e del dispositivo devono impostare questo parametro su zero.

[in] Type

Uno dei tipi di dati definiti dal sistema seguenti da scrivere:

Valore del tipo	Significato
REG_BINARY	Dati binari in qualsiasi forma.
REG_DWORD	Valore numerico a 4 byte.
REG_DWORD_LITTLE_ENDIAN	Valore numerico a 4 byte con il byte minimo significativo all'indirizzo più basso. Identico a REG_DWORD.
REG_DWORD_BIG_ENDIAN	Valore numerico a 4 byte con il byte minimo significativo all'indirizzo più alto.
REG_EXPAND_SZ	Stringa Unicode con terminazione null contenente riferimenti non esplorati alle variabili di ambiente, ad esempio "%PATH%".
REG_LINK	Stringa Unicode che assegna un nome a un collegamento simbolico. Questo tipo è irrilevante per i driver intermedi e del dispositivo.
REG_MULTI_SZ	Matrice di stringhe con terminazione null, terminate da un altro zero.
REG_NONE	Dati senza un tipo specifico.
REG_SZ	Stringa Unicode con terminazione null.
REG_RESOURCE_LIST	Elenco di risorse hardware di un driver di dispositivo, usato dal driver o da uno dei dispositivi fisici che controlla, nell'albero \ResourceMap
REG_RESOURCE_REQUIREMENTS_LIST	Elenco delle possibili risorse hardware di un driver di dispositivo o uno dei dispositivi fisici che può usare, da cui il sistema scrive un subset nell'albero \ResourceMap
REG_FULL_RESOURCE_DESCRIPTOR	Elenco di risorse hardware usate da un dispositivo fisico, rilevate e scritte nell'albero \HardwareDescription dal sistema

I driver di dispositivo non devono tentare di chiamare ZwSetValueKey per scrivere in modo esplicito le voci di valore in una sottochiave della chiave \Registro di sistema...\ResourceMap . Solo il sistema può scrivere voci di valore nell'albero \Registry...\HardwareDescription .

[in, optional] Data

Puntatore a un buffer allocato dal chiamante che contiene i dati per la voce del valore.

[in] DataSize

Specifica le dimensioni, in byte, del buffer dati . Se Type è REG_XXX_SZ, questo valore deve includere spazio per gli zero terminanti.

Valore restituito

ZwSetValueKey restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questa routine potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_ACCESS_DENIED	Il chiamante non dispone dell'accesso appropriato al valore del Registro di sistema.
STATUS_INVALID_HANDLE	Handle non valido.

Commenti

KeyHandle passato a ZwSetValueKey deve essere stato aperto con il flag KEY_SET_VALUE DesiredAccess impostato per la riuscita della chiamata. Per una descrizione dei valori possibili per DesiredAccess, vedere ZwCreateKey.

Se la chiave specificata non ha alcuna voce di valore esistente con un nome corrispondente al valore specificato,ZwSetValueKey crea una nuova voce di valore con il nome specificato. Se esiste un nome di voce di valore corrispondente, questa routine sovrascrive la voce del valore originale per il valore specificato ValueName. ZwSetValueKey mantiene quindi un nome univoco per ogni voce di valore di qualsiasi chiave specifica. Anche se ogni nome di voce di valore deve essere univoco per la chiave contenente, molte chiavi diverse nel Registro di sistema possono avere voci di valore con gli stessi nomi.

Per altre informazioni sull'uso delle chiavi del Registro di sistema, vedere Uso del Registro di sistema in un driver.

Se la chiamata a questa funzione si verifica in modalità utente, è necessario usare il nome "NtSetValueKey" anziché "ZwSetValueKey".

Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Uso di nt e zw versioni delle routine di Servizi di sistema nativo.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)