Fonction WdfRegistryCreateKey (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é si elle existe déjà, et crée un objet de clé de Registre d’infrastructure 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 d’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 sur le chemin d’accès. Si ParentKey a lavaleur NULL, KeyName doit spécifier un chemin d’accès complet à une clé de Registre.

[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] 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 avoir la valeur 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 retournée

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

Par défaut, le parent du nouvel objet de clé de Registre est l’objet de pilote d’infrastructure créé par la méthode WdfDriverCreate . Vous pouvez utiliser le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES pour spécifier un autre parent. 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, il doit supprimer l’objet de clé de Registre lorsqu’il a terminé d’utiliser l’objet ; sinon, l’objet de clé de Registre restera jusqu’à ce que le gestionnaire d’E/S décharge votre pilote.

Si votre pilote ne modifie pas le parent par défaut, il doit appeler WdfRegistryClose lorsqu’il a terminé d’utiliser l’objet ; sinon, l’objet de clé de Registre restera 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 les pilotes Framework-Based.

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
                                  );
}

Configuration requise

Voir aussi

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverCréer

WdfDriverOpenParametersRegistryKey

WdfFdoInitOpenRegistryKey

WdfRegistryOpenKey

ZwCreateKey