WdfRegistryOpenKey, fonction (wdfregistry.h)

[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 framework 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 vers un objet de clé de registre d’infrastructure. Cet objet représente une clé de Registre parente ouverte par le pilote. Ce paramètre est facultatif et peut être NULL. Si le paramètre n’est pas NULL, la clé qui KeyName spécifie 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 est 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 ACCESS_MASK-typée 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 de KEY_ALL_ACCESS s’il lit uniquement la clé de Registre.

[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 de retour

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

Pour obtenir la liste des autres valeurs de retour que la méthode WdfRegistryOpenKey peut retourner, consultez Framework Object Creation Errors.

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

Remarques

Pour obtenir un handle vers 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 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 s’ouvre avec WdfRegistryOpenKey, le pilote doit appeler WdfRegistryClose.

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

Exemples

L’exemple de code suivant ouvre la clé logicielle d’un pilote, puis ouvre la MySubKey clé de Registre, 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
                                );
}

Spécifications

Voir aussi

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverOpenParametersRegistryKey

WdfFdoInitOpenRegistryKey

WdfRegistryClose

WdfRegistryCreateKey