Funzione ZwOpenKeyTransacted (wdm.h)

Articolo
08/08/2023

La routine ZwOpenKeyTransacted apre una chiave del Registro di sistema esistente e associa la chiave a una transazione.

Sintassi

NTSYSAPI NTSTATUS ZwOpenKeyTransacted(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  HANDLE             TransactionHandle
);

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 aperta. 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.

[in] TransactionHandle

Handle a 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.

Valore restituito

ZwOpenKeyTransacted restituisce STATUS_SUCCESS se la chiamata apre correttamente la chiave. I valori restituiti degli errori possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il parametro ObjectAttributes è NULL o punta a informazioni 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 ha i 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 l'uso dell'handle puntato da KeyHandle , il driver deve chiamare la routine ZwClose per chiuderla.

Se la chiave specificata non esiste nel Registro di sistema, ZwOpenKeyTransacted restituisce un valore di stato di errore e non fornisce un handle chiave. A differenza della routine ZwCreateKeyTransacted , la routine ZwOpenKeyTransacted non crea la chiave specificata se la chiave non esiste. Sia ZwCreateKeyTransacted che ZwOpenKeyTransacted associano una chiave del Registro di sistema a una transazione.

La routine ZwOpenKey è simile a ZwOpenKeyTransacted, ma non associa una chiave a una transazione.

Dopo che un driver in modalità kernel ottiene un handle a 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 delle modifiche apportate nella transazione o eseguendo il rollback della transazione.

Dopo aver completato correttamente 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 delle transazioni. Ad esempio, le chiamate a ZwCreateKeyTransacted e ZwOpenKeyTransacted possono associare una o più chiavi 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 delle transazioni. Ad esempio, una chiamata alla routine ZwSetValueKey può usare un handle di chiavi 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.

ZwOpenKeyTransacted ignora le informazioni di sicurezza nella struttura a cui punta il parametro ObjectAttributes .

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 degli 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 del sistema operativo 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)