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 :
| Code de retour | Description |
|---|---|
|
WdfRegistryCreateKey n’a pas été appelé à IRQL = PASSIVE_LEVEL. |
|
Un paramètre non valide a été spécifié. |
|
Impossible d’allouer un objet de clé de Registre. |
|
Le système a refusé les droits d’accès spécifiés. |
|
La clé de Registre spécifiée n’existe pas. |
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
| 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) |