WdfFdoInitOpenRegistryKey, fonction (wdffdo.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfFdoInitOpenRegistryKey ouvre la clé matérielle d’un appareil ou la clé logicielle d’un pilote dans le Registre et crée un objet de clé de registre d’infrastructure qui représente la clé de Registre.

Syntaxe

NTSTATUS WdfFdoInitOpenRegistryKey(
  [in]           PWDFDEVICE_INIT        DeviceInit,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Paramètres

[in] DeviceInit

Pointeur vers une structure WDFDEVICE_INIT que le pilote a obtenu à partir de sa fonction de rappel EvtDriverDeviceAdd .

[in] DeviceInstanceKeyType

Spécifie la clé ou la sous-clé à ouvrir.

Notes

UMDF ne prend pas en charge la création de sous-clés.

Il s’agit d’un OR au niveau du bit des indicateurs suivants (qui sont définis dans Wdm.h).

Indicateur DeviceInstanceKeyType	Signification	Infrastructure
PLUGPLAY_REGKEY_DEVICE	Ouvre la clé matérielle de l’appareil.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Ouvre la clé logicielle du pilote. Un pilote UMDF qui définit cet indicateur doit également définir DesiredAccesssur KEY_READ. Sinon, cette méthode retourne STATUS_ACCESS_DENIED.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Un pilote KMDF utilise cet indicateur pour ouvrir la copie de la clé matérielle ou logicielle qui se trouve dans le profil matériel actuel.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Un pilote UMDF utilise ces indicateurs ensemble pour ouvrir la sous-clé ServiceName de la clé logicielle du pilote pour l’accès en lecture/écriture.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	De même, un pilote UMDF utilise ces indicateurs pour ouvrir la sous-clé ServiceName de la clé matérielle de l’appareil pour l’accès en lecture/écriture.	UMDF

[in] DesiredAccess

Valeur de type ACCESS_MASK qui spécifie les droits d’accès demandés par le pilote pour la clé de Registre spécifiée.

Un pilote KMDF demande généralement KEY_READ, KEY_WRITE ou KEY_READ | KEY_WRITE.

Si vous écrivez un pilote UMDF, utilisez le tableau suivant.

DeviceInstanceKeyType	DesiredAccess
PLUGPLAY_REGKEY_DEVICE	KEY_READ
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	KEY_READ ou KEY_READ \| KEY_SET_VALUE
PLUGPLAY_REGKEY_DRIVER	KEY_READ
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	KEY_READ ou KEY_READ \| KEY_SET_VALUE

Comme meilleure pratique, demandez uniquement les types d’accès dont votre pilote a besoin.

[in, optional] KeyAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui contient des attributs fournis par le pilote pour le nouvel objet de clé de Registre. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet de clé de Registre.

Valeur retournée

WdfFdoInitOpenRegistryKey retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	WdfFdoInitOpenRegistryKey n’a pas été appelé à IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié ou le pilote n’a pas obtenu la structure WDFDEVICE_INIT à partir de sa fonction de rappel EvtDriverDeviceAdd . Pour UMDF, cette valeur de retour peut indiquer des droits d’accès insuffisants.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet de clé de Registre.
STATUS_OBJECT_NAME_NOT_FOUND	La clé de Registre spécifiée n’existe pas.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfFdoInitOpenRegistryKey peut retourner, consultez Erreurs de création d’objet framework.

La méthode peut également retourner d’autres valeurs NTSTATUS.

Remarques

Le pilote doit appeler WdfFdoInitOpenRegistryKey avant d’appelerWdfDeviceCreate. Pour plus d’informations sur l’appel de WdfDeviceCreate, consultez Création d’un objet d’appareil framework.

Pour plus d’informations sur la méthode WdfFdoInitOpenRegistryKey , consultez Création d’objets d’appareil dans un pilote de fonction.

ou plus d’informations sur le Registre, les clés matérielles et logicielles et les objets du Registre, consultez Utilisation du Registre dans les pilotes Framework-Based.

Exemples

L’exemple de code suivant ouvre la clé matérielle d’un appareil, avec accès en lecture.

WDFKEY key;
NTSTATUS status;

status = WdfFdoInitOpenRegistryKey(
                                   DeviceInit,
                                   PLUGPLAY_REGKEY_DEVICE,
                                   GENERIC_READ,
                                   WDF_NO_OBJECT_ATTRIBUTES,
                                   &key
                                   );
if (!NT_SUCCESS(status)) {
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdffdo.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DeviceInitAPI(kmdf),DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WdfDeviceOpenRegistryKey

WdfDriverOpenParametersRegistryKey