Funzione ZwOpenKeyTransactedEx (wdm.h)

Articolo
03/05/2024

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

Sintassi

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [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] OpenOptions

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

Flag OpenOptions	Descrizione
REG_OPTION_OPEN_LINK	La chiave è un collegamento simbolico. Questo flag non viene usato dai driver di dispositivo e intermedi.
REG_OPTION_BACKUP_RESTORE	La chiave deve essere aperta con privilegi speciali che consentono operazioni di backup e ripristino. Questo flag non viene usato dai driver di dispositivo e intermedi.

[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

ZwOpenKeyTransactedEx 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_INVALID_PARAMETER_4	Il valore del parametro OpenOptions specifica le 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 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, ZwOpenKeyTransactedEx restituisce un valore di stato di errore e non fornisce un handle chiave. A differenza della routine ZwCreateKeyTransacted , la routine ZwOpenKeyTransactedEx non crea la chiave specificata se la chiave non esiste. Sia ZwCreateKeyTransacted che ZwOpenKeyTransactedEx associano una chiave del Registro di sistema a una transazione.

La routine ZwOpenKeyEx è simile a ZwOpenKeyTransactedEx, ma non associa una chiave a una transazione.

La routine ZwOpenKeyTransacted è simile a ZwOpenKeyTransactedEx, ma non accetta un parametro OpenOptions. Il parametro OpenOptions di ZwOpenKeyTransactedEx consente al chiamante di aprire una chiave che è un collegamento simbolico o di aprire una chiave per le operazioni di backup e ripristino. Una chiamata a ZwOpenKeyTransactedEx con parametro OpenOptions impostata su zero equivale a una chiamata a ZwOpenKeyTransacted.

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

ZwOpenKeyTransactedEx 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 7 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)