WdfRegistryCreateKey, fonction (wdfregistry.h)

[S’applique à KMDF et UMDF]

La méthode WdfRegistryCreateKey crée et ouvre une clé de Registre spécifiée, ou ouvre simplement la clé s’il existe déjà, et crée un objet de clé de registre framework qui représente la clé de Registre.

Syntaxe

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [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.

[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] CreateOptions

Un ou plusieurs indicateurs. Pour plus d’informations sur ces indicateurs, consultez le paramètre CreateOptions ou ZwCreateKey.

[out, optional] CreateDisposition

Pointeur vers un emplacement qui reçoit REG_CREATED_NEW_KEY si une nouvelle clé est créée ou REG_OPENED_EXISTING_KEY si une clé existante est ouverte. Ces valeurs sont définies dans Wdm.h. Ce pointeur est facultatif et peut être NULL.

[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

WdfRegistryCreateKey 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 WdfRegistryCreateKey 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.

Par défaut, le parent du nouvel objet de clé de Registre est l’objet de pilote de framework créé par la méthode WdfDriverCreate. Vous pouvez utiliser le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES pour spécifier un parent différent. L’infrastructure supprime l’objet de clé de Registre lorsqu’il supprime l’objet parent. Si votre pilote ne modifie pas le parent par défaut, le pilote doit supprimer l’objet de clé de Registre une fois l’objet terminé à l’aide de l’objet ; sinon, l’objet de clé de Registre reste jusqu’à ce que le gestionnaire d’E/S décharge votre pilote.

Si votre pilote ne modifie pas le parent par défaut, le pilote doit appeler WdfRegistryClose lorsqu’il a terminé d’utiliser l’objet ; sinon, l’objet de clé de Registre reste jusqu’à ce que le gestionnaire d’E/S décharge votre pilote. Le pilote peut également appeler WdfObjectDelete pour supprimer l’objet de clé de Registre.

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 crée et ouvre la clé de Registre myKeyStr, 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"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &subkey
                                  );
}

Spécifications

Voir aussi

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverCreate

WdfDriverOpenParametersRegistryKey

WdfFdoInitOpenRegistryKey

WdfRegistryOpenKey

ZwCreateKey