ZwCreateKeyTransacted, fonction (wdm.h)

Article
02/27/2024

La routine ZwCreateKeyTransacted crée une clé de Registre ou en ouvre une existante et associe la clé à une transaction.

Syntaxe

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

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 précédemment 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.

TitleIndex

Les pilotes de périphérique et intermédiaire définissent ce paramètre sur zéro.

[in, optional] Class

Les pilotes de périphérique et intermédiaire définissent ce paramètre sur NULL.

[in] CreateOptions

Spécifie les options à appliquer lorsque la routine crée ou ouvre la clé. Définissez ce paramètre sur zéro ou sur le bit OR d’un ou plusieurs des bits d’indicateur REG_OPTION_XXX suivants.

Indicateur CreateOptions	Description
REG_OPTION_VOLATILE	La clé n’est pas conservée après le redémarrage de l’ordinateur.
REG_OPTION_NON_VOLATILE	La clé est conservée après le redémarrage de l’ordinateur.
REG_OPTION_CREATE_LINK	La clé est un lien symbolique. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaires.
REG_OPTION_BACKUP_RESTORE	Ouvrez la clé avec des privilèges spéciaux qui activent les opérations de sauvegarde et de restauration. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaires.

[in] TransactionHandle

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

[out, optional] Disposition

Pointeur vers un emplacement dans lequel la routine écrit l’une des valeurs suivantes pour indiquer si l’appel a créé une nouvelle clé ou ouvert une clé existante.

Valeur de destruction	Description
REG_CREATED_NEW_KEY	Une nouvelle clé a été créée.
REG_OPENED_EXISTING_KEY	Une clé existante a été ouverte.

Vous pouvez définir Disposition = NULL si ces informations ne sont pas nécessaires.

Valeur retournée

ZwCreateKeyTransacted retourne STATUS_SUCCESS si l’appel crée ou 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, ou la valeur du paramètre CreateOptions spécifie des options non valides.
STATUS_OBJECT_PATH_SYNTAX_BAD	Le chemin du Registre dans les attributs de l’objet n’est pas valide.
STATUS_OBJECT_NAME_NOT_FOUND	Le chemin du Registre dans les attributs de l’objet est introuvable.
STATUS_ACCESS_DENIED	L’appelant ne disposait pas des droits d’accès requis 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.

Comme ZwCreateKeyTransacted, la routine ZwOpenKeyTransacted associe une clé à une transaction. Contrairement à ZwCreateKeyTransacted, qui peut créer une clé ou ouvrir une clé existante, ZwOpenKeyTransacted ne peut ouvrir qu’une clé de Registre qui existe déjà.

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 en validant les modifications apportées à la transaction ou en annulant la transaction.

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 annuler 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 un ou plusieurs descripteurs à des clés de Registre à 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.

Le descripteur de sécurité dans les attributs d’objet détermine si les droits d’accès spécifiés par le paramètre DesiredAccess sont accordés lors d’appels ultérieurs à des routines, telles que ZwOpenKeyTransacted qui accèdent à la clé, ou à des routines, telles que ZwCreateKeyTransacted, qui créent des sous-clés de la clé.

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 tous les handles qu’il crée sont des handles de noyau. Sinon, le handle est accessible par le processus dans le contexte 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 plus récentes de Windows.
Plateforme cible	Universal
En-tête	wdm.h (include 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)