Fonction IoOpenDeviceRegistryKey (wdm.h)

Article
03/05/2024

La routine IoOpenDeviceRegistryKey retourne un handle à un emplacement d’état du Registre pour un appareil particulier instance.

Syntaxe

NTSTATUS IoOpenDeviceRegistryKey(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  ULONG          DevInstKeyType,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        DeviceRegKey
);

Paramètres

[in] DeviceObject

Pointeur vers l’objet d’appareil physique (PDO) de l’appareil instance pour lequel l’emplacement de l’état du Registre doit être ouvert.

[in] DevInstKeyType

Spécifie des indicateurs indiquant s’il faut ouvrir une clé matérielle spécifique au périphérique ou une clé logicielle spécifique au pilote. Les indicateurs indiquent également si la clé est relative au profil matériel actuel. Pour plus d’informations sur les clés matérielles et logicielles, consultez Présentation des clés de Registre pour les pilotes.

Les indicateurs sont définis comme suit :

PLUGPLAY_REGKEY_DEVICE

Ouvrez la clé matérielle de l’appareil, un emplacement d’état de registre spécifique à l’appareil qui contient des informations sur l’appareil. Cet indicateur ne peut pas être spécifié avec PLUGPLAY_REGKEY_DRIVER.

PLUGPLAY_REGKEY_DRIVER

Ouvrez la clé logicielle de l’appareil, un emplacement d’état du Registre spécifique au périphérique pour stocker des informations spécifiques au pilote. Cet indicateur ne peut pas être spécifié avec PLUGPLAY_REGKEY_DEVICE.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

Les profils matériels sont déconseillés et l’état ne doit pas être stocké par rapport à un profil matériel.

Ouvrez une clé relative au profil matériel actuel pour obtenir des informations sur le périphérique ou le pilote. Cela permet au pilote d’accéder aux informations de configuration spécifiques au profil matériel. L’appelant doit spécifier PLUGPLAY_REGKEY_DEVICE ou PLUGPLAY_REGKEY_DRIVER avec cet indicateur.

[in] DesiredAccess

Spécifie la valeur ACCESS_MASK qui représente l’accès dont l’appelant a besoin à la clé. Consultez la routine ZwCreateKey pour obtenir une description de chaque droit d’accès KEY_XXX .

[out] DeviceRegKey

Pointeur vers une mémoire tampon allouée à l’appelant qui, en cas de retour réussi, contient un handle vers l’emplacement d’état du Registre demandé.

Valeur retournée

IoOpenDeviceRegistryKey retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Indique éventuellement que l’appelant a spécifié un ensemble illégal d’indicateurs DevInstKeyType ou fourni un DeviceObject qui n’est pas un PDO valide.

Remarques

Le pilote doit appeler ZwClose pour fermer le handle retourné par cette routine lorsque l’accès n’est plus nécessaire.

Les clés de Registre ouvertes par cette routine ne sont pas volatiles.

Les applications de configuration en mode utilisateur peuvent accéder à ces clés de Registre à l’aide de fonctions CM_Open_DevNode_Key ou d’informations sur l’appareil telles que SetupDiOpenDevRegKey ou SetupDiCreateDevRegKey.

Pour préremplir l’état dans ces emplacements d’état du Registre au moment de l’installation du package de pilotes, utilisez les directives INF AddReg dans un fichier INF.

Les appelants de IoOpenDeviceRegistryKey doivent s’exécuter sur IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.

Configuration requise

Condition requise	Valeur
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 (voir la section Remarques)
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)