Fonction ZwOpenKeyTransactedEx (wdm.h)

Article
08/08/2023

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

Syntaxe

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

Spécifie les options à appliquer lors de l’ouverture de la clé. Définissez ce paramètre sur zéro ou sur la valeur OR au niveau du bit d’un ou plusieurs des bits d’indicateur REG_OPTION_XXX suivants.

Indicateur OpenOptions	Description
REG_OPTION_OPEN_LINK	La clé est un lien symbolique. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.
REG_OPTION_BACKUP_RESTORE	La clé doit être ouverte avec des privilèges spéciaux qui autorisent les opérations de sauvegarde et de restauration. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.

[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

ZwOpenKeyTransactedEx 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_INVALID_PARAMETER_4	La valeur du paramètre OpenOptions spécifie des options 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, ZwOpenKeyTransactedEx retourne une erreur status valeur et ne fournit pas de handle de clé. Contrairement à la routine ZwCreateKeyTransacted , la routine ZwOpenKeyTransactedEx ne crée pas la clé spécifiée si la clé n’existe pas. ZwCreateKeyTransacted et ZwOpenKeyTransactedEx associent une clé de Registre à une transaction.

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

La routine ZwOpenKeyTransacted est similaire à ZwOpenKeyTransactedEx , mais n’accepte pas de paramètre OpenOptions . Le paramètre OpenOptions de ZwOpenKeyTransactedEx permet à l’appelant d’ouvrir une clé qui est un lien symbolique ou d’ouvrir une clé pour les opérations de sauvegarde et de restauration. Un appel à ZwOpenKeyTransactedEx avec le paramètre OpenOptions défini sur zéro équivaut à un appel à ZwOpenKeyTransacted.

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

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