Fonction ZwOpenKeyTransacted (wdm.h)

Article
08/08/2023

La routine ZwOpenKeyTransacted ouvre une clé de Registre existante et associe la clé à une transaction.

Syntaxe

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

Paramètres

[out] KeyHandle

Pointeur vers une variable HANDLE dans laquelle la routine écrit le handle sur la clé.

[in] DesiredAccess

Spécifie le type d’accès à la clé que l’appelant demande. Ce paramètre est une valeur ACCESS_MASK . Pour plus d’informations, consultez la description du paramètre DesiredAccess de la routine ZwCreateKey .

[in] ObjectAttributes

Pointeur vers les attributs d’objet de la clé en cours d’ouverture. Ce paramètre pointe vers une structure OBJECT_ATTRIBUTES qui doit avoir été initialisée par la routine InitializeObjectAttributes . L’appelant doit spécifier le nom de la clé de Registre en tant que paramètre ObjectName dans l’appel à InitializeObjectAttributes. Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit définir l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes.

[in] TransactionHandle

Handle d’un objet de transaction. Pour obtenir ce handle, vous pouvez appeler la routine ZwCreateTransaction . Ou, si vous avez un pointeur vers un objet de transaction, vous pouvez fournir le pointeur vers la routine ObOpenObjectByPointer pour obtenir le handle de transaction correspondant.

Valeur retournée

ZwOpenKeyTransacted retourne STATUS_SUCCESS si l’appel ouvre correctement la clé. Les valeurs de retour d’erreur possibles sont les suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Le paramètre ObjectAttributes a la valeur NULL ou pointe vers des informations non valides.
STATUS_OBJECT_PATH_SYNTAX_BAD	Le chemin d’accès du Registre dans les attributs d’objet n’est pas valide.
STATUS_OBJECT_NAME_NOT_FOUND	Le chemin d’accès du Registre dans les attributs d’objet est introuvable.
STATUS_ACCESS_DENIED	L’appelant ne disposait pas des droits d’accès nécessaires pour ouvrir un handle pour la clé de Registre nommée.
STATUS_INSUFFICIENT_RESOURCES	Une opération d’allocation de mémoire a échoué.

Remarques

Cette routine fournit un handle avec lequel l’appelant peut accéder à une clé de Registre. En outre, cette routine associe la clé à une transaction active.

Une fois que le handle pointé par KeyHandle n’est plus utilisé, le pilote doit appeler la routine ZwClose pour la fermer.

Si la clé spécifiée n’existe pas dans le Registre, ZwOpenKeyTransacted retourne une erreur status valeur et ne fournit pas de handle de clé. Contrairement à la routine ZwCreateKeyTransacted , la routine ZwOpenKeyTransacted ne crée pas la clé spécifiée si la clé n’existe pas. ZwCreateKeyTransacted et ZwOpenKeyTransacted associent une clé de Registre à une transaction.

La routine ZwOpenKey est similaire à ZwOpenKeyTransacted, mais n’associe pas de clé à une transaction.

Une fois qu’un pilote en mode noyau a obtenu un handle pour une transaction (par exemple, en appelant ZwCreateTransaction), le pilote peut effectuer une série d’opérations de Registre qui font partie de cette transaction. Le pilote peut fermer la transaction soit en commitant sur les modifications apportées à la transaction, soit en la supprimant.

Une fois que le pilote a effectué toutes les opérations de Registre qui font partie d’une transaction, il peut appeler la routine ZwCommitTransaction pour valider les modifications. Le pilote peut appeler la routine ZwRollbackTransaction pour restaurer la transaction.

Pendant une transaction, une opération de Registre fait partie de la transaction si l’appel système qui effectue l’opération remplit l’une des conditions suivantes :

L’appel spécifie, en tant que paramètre d’entrée, le handle de transaction. Par exemple, les appels à ZwCreateKeyTransacted et ZwOpenKeyTransacted peuvent associer une ou plusieurs clés à la transaction.
L’appel spécifie, en tant que paramètre d’entrée, un handle de clé de Registre obtenu par un appel à ZwCreateKeyTransacted ou ZwOpenKeyTransacted auquel le handle de transaction a été fourni. Par exemple, un appel à la routine ZwSetValueKey peut utiliser un handle de clé obtenu de cette façon pour définir la valeur d’une clé de Registre dans le cadre d’une transaction.

Pour plus d’informations sur les transactions en mode noyau, consultez Utilisation du Gestionnaire de transactions de noyau.

ZwOpenKeyTransacted ignore les informations de sécurité dans la structure vers laquelle pointe le paramètre ObjectAttributes .

Si l’appelant en mode noyau n’est pas en cours d’exécution dans un contexte de thread système, il doit s’assurer que les handles qu’il crée sont des handles de noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution. Pour plus d’informations, consultez Handles d’objet.

Pour plus d’informations sur l’utilisation des clés de Registre en mode noyau, consultez Utilisation du Registre dans un pilote.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions ultérieures du système d’exploitation Windows.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm)