WdfRegistryOpenKey, fonction (wdfregistry.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfRegistryOpenKey ouvre une clé de Registre spécifiée et crée un objet de clé de Registre d’infrastructure qui représente la clé de Registre.

Syntaxe

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Paramètres

[in, optional] ParentKey

Handle pour un objet de clé de Registre d’infrastructure. Cet objet représente une clé de Registre parente que le pilote a ouverte. Ce paramètre est facultatif et peut être NULL. Si le paramètre n’est pas NULL, la clé spécifiée par KeyName doit résider sous cette clé parente dans le Registre. Pour plus d’informations sur cette clé parente, consultez la section Remarques.

[in] KeyName

Pointeur vers une structure UNICODE_STRING qui contient le nom de la clé à ouvrir. Le nom de la clé peut inclure des informations de chemin d’accès. Si ParentKey a la valeur NULL, KeyName doit spécifier un chemin d’accès complet à une clé de Registre. Pour obtenir des exemples, consultez la section Remarques.

[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. Pour obtenir la liste des droits d’accès que les pilotes utilisent généralement pour les clés de Registre, consultez Ouverture d’un handle à un objet Registry-Key. Votre pilote doit demander uniquement les types d’accès dont il a besoin. Par exemple, le pilote ne doit pas demander KEY_ALL_ACCESS s’il lit uniquement la clé de Registre.

[in, optional] KeyAttributes

Pointeur vers une structure de 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

WdfRegistryOpenKey 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	WdfRegistryOpenKey n’a pas été appelé dans IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet de clé de Registre.
STATUS_ACCESS_DENIED	Le système a refusé les droits d’accès spécifiés.
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 WdfRegistryOpenKey peut retourner, consultez Erreurs de création d’objet framework.

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

Remarques

Pour obtenir un handle pour un objet de clé de Registre qui représente une clé parente, votre pilote peut appeler WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey ou WdfFdoInitOpenRegistryKey.

Le format de chaîne spécifié dans le paramètre KeyName varie selon que l’appelant est un pilote KMDF ou un pilote UMDF. Par exemple, pour ouvrir le chemin d’accès suivant :

HKLM\System\CurrentControlSet\Control

Votre pilote peut utiliser cette logique conditionnelle :

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

Lorsque le pilote a terminé d’utiliser une clé de Registre qu’il ouvre avec WdfRegistryOpenKey, le pilote doit appeler WdfRegistryClose.

Pour plus d’informations sur les objets de clé de Registre, consultez Utilisation du Registre dans les pilotes Framework-Based.

Exemples

L’exemple de code suivant ouvre la clé logicielle d’un pilote, puis ouvre la clé de Registre MySubKey , qui se trouve sous la clé logicielle du pilote.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

Configuration requise

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