IoOpenDeviceRegistryKey, fonction (wdm.h)
La routine IoOpenDeviceRegistryKey retourne un handle à un emplacement d’état de Registre pour une instance d’appareil particulière.
Syntaxe
NTSTATUS IoOpenDeviceRegistryKey(
[in] PDEVICE_OBJECT DeviceObject,
[in] ULONG DevInstKeyType,
[in] ACCESS_MASK DesiredAccess,
[out] PHANDLE DeviceRegKey
);
Paramètres
[in] DeviceObject
Pointeur vers la objet d’appareil physique (PDO) de l’instance d’appareil pour laquelle 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 à l’appareil 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 de Registre spécifique à l’appareil 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é par rapport au profil matériel actuel pour les informations de périphérique ou de 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 pour la clé. Consultez la routine ZwCreateKey pour obtenir une description de chaque KEY_XXX droit d’accès.
[out] DeviceRegKey
Pointeur vers une mémoire tampon allouée par l’appelant qui, lors d’un retour réussi, contient un handle vers l’emplacement d’état du Registre demandé.
Valeur de retour
IoOpenDeviceRegistryKey retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes :
| Retourner le code | Description |
|---|---|
| STATUS_INVALID_PARAMETER | Indique peut-être que l’appelant a spécifié un ensemble illégal d’indicateurs de 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 pasvolatiles.
Les applications de configuration en mode utilisateur peuvent accéder à ces clés de Registre à l’aide de CM_Open_DevNode_Key ou de fonctions d’informations d’appareil telles que SetupDiOpenDevRegKey ou SetupDiCreateDevRegKey.
Pour préremplir l’état dans ces emplacements d’état de Registre au moment de l’installation du package de pilotes, utilisez directives AddReg INF dans un fichier INF.
Les appelants de IoOpenDeviceRegistryKey doivent s’exécuter à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| d’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) |