Fonction IoOpenDeviceRegistryKey (wdm.h)
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) |