Funzione ZwCreateKeyTransacted (wdm.h)

Articolo
08/08/2023

La routine ZwCreateKeyTransacted crea una nuova chiave del Registro di sistema o ne apre una esistente e associa la chiave a una transazione.

Sintassi

NTSYSAPI NTSTATUS ZwCreateKeyTransacted(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [in]            HANDLE             TransactionHandle,
  [out, optional] PULONG             Disposition
);

Parametri

[out] KeyHandle

Puntatore a una variabile HANDLE in cui la routine scrive l'handle nella chiave.

[in] DesiredAccess

Specifica il tipo di accesso alla chiave richiesta dal chiamante. Questo parametro è un valore ACCESS_MASK . Per altre informazioni, vedere la descrizione del parametro DesiredAccess della routine ZwCreateKey .

[in] ObjectAttributes

Puntatore agli attributi dell'oggetto della chiave da aprire. Questo parametro punta a una struttura OBJECT_ATTRIBUTES che deve essere stata inizializzata in precedenza dalla routine InitializeObjectAttributes . Il chiamante deve specificare il nome della chiave del Registro di sistema come parametro ObjectName nella chiamata a InitializeObjectAttributes. Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve impostare l'attributo OBJ_KERNEL_HANDLE quando chiama InitializeObjectAttributes.

TitleIndex

I driver di dispositivo e intermedi impostano questo parametro su zero.

[in, optional] Class

I driver di dispositivo e intermedi impostano questo parametro su NULL.

[in] CreateOptions

Specifica le opzioni da applicare quando la routine crea o apre la chiave. Impostare questo parametro su zero o sull'OR bit per bit di uno o più dei bit del flag REG_OPTION_XXX seguenti.

Flag CreateOptions	Descrizione
REG_OPTION_VOLATILE	La chiave non viene mantenuta dopo il riavvio del computer.
REG_OPTION_NON_VOLATILE	La chiave viene mantenuta dopo il riavvio del computer.
REG_OPTION_CREATE_LINK	La chiave è un collegamento simbolico. Questo flag non viene usato dai driver intermedi e del dispositivo.
REG_OPTION_BACKUP_RESTORE	Aprire la chiave con privilegi speciali che abilitano le operazioni di backup e ripristino. Questo flag non viene usato dai driver intermedi e del dispositivo.

[in] TransactionHandle

Handle per un oggetto transazione. Per ottenere questo handle, è possibile chiamare la routine ZwCreateTransaction . In alternativa, se si dispone di un puntatore a un oggetto transazione, è possibile fornire il puntatore alla routine ObOpenObjectByPointer per ottenere l'handle di transazione corrispondente.

[out, optional] Disposition

Puntatore a una posizione in cui la routine scrive uno dei valori seguenti per indicare se la chiamata ha creato una nuova chiave o ne ha aperta una esistente.

Valore di eliminazione	Descrizione
REG_CREATED_NEW_KEY	È stata creata una nuova chiave.
REG_OPENED_EXISTING_KEY	È stata aperta una chiave esistente.

È possibile impostare Disposition = NULL se queste informazioni non sono necessarie.

Valore restituito

ZwCreateKeyTransacted restituisce STATUS_SUCCESS se la chiamata crea o apre correttamente la chiave. I valori restituiti di errore possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il parametro ObjectAttributes è NULL o punta a informazioni non valide oppure il valore del parametro CreateOptions specifica opzioni non valide.
STATUS_OBJECT_PATH_SYNTAX_BAD	Il percorso del Registro di sistema negli attributi dell'oggetto non è valido.
STATUS_OBJECT_NAME_NOT_FOUND	Il percorso del Registro di sistema negli attributi dell'oggetto non è stato trovato.
STATUS_ACCESS_DENIED	Il chiamante non dispone dei diritti di accesso necessari per aprire un handle per la chiave del Registro di sistema denominata.
STATUS_INSUFFICIENT_RESOURCES	Operazione di allocazione della memoria non riuscita.

Commenti

Questa routine fornisce un handle con cui il chiamante può accedere a una chiave del Registro di sistema. Inoltre, questa routine associa la chiave a una transazione attiva.

Dopo che l'handle a cui punta KeyHandle non viene più utilizzato, il driver deve chiamare la routine ZwClose per chiuderla.

Analogamente a ZwCreateKeyTransacted, la routine ZwOpenKeyTransacted associa una chiave a una transazione. A differenza di ZwCreateKeyTransacted, che può creare una nuova chiave o aprire una chiave esistente, ZwOpenKeyTransacted può aprire solo una chiave del Registro di sistema già esistente.

Dopo che un driver in modalità kernel ottiene un handle per una transazione ,ad esempio chiamando ZwCreateTransaction, il driver può eseguire una serie di operazioni del Registro di sistema che fanno parte di questa transazione. Il driver può chiudere la transazione eseguendo il commit alle modifiche apportate nella transazione o eseguendo il rollback della transazione.

Dopo che il driver ha completato tutte le operazioni del Registro di sistema che fanno parte di una transazione, può chiamare la routine ZwCommitTransaction per eseguire il commit delle modifiche. Il driver può chiamare la routine ZwRollbackTransaction per eseguire il rollback della transazione.

Durante una transazione, un'operazione del Registro di sistema fa parte della transazione se la chiamata di sistema che esegue l'operazione soddisfa una delle condizioni seguenti:

La chiamata specifica, come parametro di input, l'handle della transazione. Ad esempio, le chiamate a ZwCreateKeyTransacted e ZwOpenKeyTransacted possono associare uno o più handle alle chiavi del Registro di sistema alla transazione.
La chiamata specifica, come parametro di input, un handle di chiave del Registro di sistema ottenuto da una chiamata a ZwCreateKeyTransacted o ZwOpenKeyTransacted a cui è stato fornito l'handle della transazione. Ad esempio, una chiamata alla routine ZwSetValueKey può usare un handle di chiave ottenuto in questo modo per impostare il valore di una chiave del Registro di sistema come parte di una transazione.

Per altre informazioni sulle transazioni in modalità kernel, vedere Uso di Kernel Transaction Manager.

Il descrittore di sicurezza negli attributi dell'oggetto determina se i diritti di accesso specificati dal parametro DesiredAccess vengono concessi alle routine successive, ad esempio ZwOpenKeyTransacted che accedono alla chiave o a routine, ad esempio ZwCreateKeyTransacted, che creano sottochiavi della chiave.

Se il chiamante in modalità kernel non è in esecuzione in un contesto di thread di sistema, deve assicurarsi che gli handle creati siano handle del kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver. Per altre informazioni, vedere Handle di oggetti.

Per altre informazioni su come usare le chiavi del Registro di sistema in modalità kernel, vedere Uso del Registro di sistema in un driver.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive di Windows.
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	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)