Fonction RegCreateKeyExA (winreg.h)

Article
08/27/2023

Crée la clé de Registre spécifiée. Si la clé existe déjà, la fonction l’ouvre. Notez que les noms de clés ne respectent pas la casse.

Pour effectuer des opérations de Registre traitées sur une clé, appelez la fonction RegCreateKeyTransacted .

Les applications qui sauvegardent ou restaurent l’état du système, y compris les fichiers système et les ruches du Registre, doivent utiliser le service de cliché instantané de volume au lieu des fonctions du Registre.

Syntaxe

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

Paramètres

[in] hKey

Handle d’une clé de Registre ouverte. Le processus appelant doit avoir KEY_CREATE_SUB_KEY accès à la clé. Pour plus d’informations, consultez Sécurité de la clé de Registre et droits d’accès.

L’accès pour la création de clé est vérifié par rapport au descripteur de sécurité de la clé de Registre, et non au masque d’accès spécifié lors de l’obtention du handle. Par conséquent, même si hKey a été ouvert avec un samDesired de KEY_READ, elle peut être utilisée dans les opérations qui modifient le Registre si son descripteur de sécurité l’autorise.

Ce handle est retourné par la fonction RegCreateKeyEx ou RegOpenKeyEx , ou il peut s’agir de l’une des clés prédéfinies suivantes :

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in] lpSubKey

Nom d’une sous-clé que cette fonction ouvre ou crée. La sous-clé spécifiée doit être une sous-clé de la clé identifiée par le paramètre hKey ; il peut se trouver jusqu’à 32 niveaux de profondeur dans l’arborescence du Registre. Pour plus d’informations sur les noms de clés, consultez Structure du Registre.

Si lpSubKey est un pointeur vers une chaîne vide, phkResult reçoit un nouveau handle vers la clé spécifiée par hKey.

Ce paramètre ne peut pas avoir la valeur NULL.

Reserved

Ce paramètre est réservé et doit être égal à zéro.

[in, optional] lpClass

Type de classe défini par l’utilisateur de cette clé. Ce paramètre peut être ignoré. Ce paramètre peut être NULL.

[in] dwOptions

Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
REG_OPTION_BACKUP_RESTORE 0x00000004L	Si cet indicateur est défini, la fonction ignore le paramètre samDesired et tente d’ouvrir la clé avec l’accès requis pour la sauvegarde ou la restauration de la clé. Si le privilège SE_BACKUP_NAME est activé pour le thread appelant, la clé est ouverte avec les droits d’accès ACCESS_SYSTEM_SECURITY et KEY_READ. Si le privilège SE_RESTORE_NAME est activé sur le thread appelant, à compter de Windows Vista, la clé est ouverte avec les droits d’accès ACCESS_SYSTEM_SECURITY, DELETE et KEY_WRITE. Si les deux privilèges sont activés, la clé dispose des droits d’accès combinés pour les deux privilèges. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.
REG_OPTION_CREATE_LINK 0x00000002L	Note Les liens symboliques du Registre ne doivent être utilisés pour la compatibilité des applications que lorsque cela est absolument nécessaire. Cette clé est un lien symbolique. Le chemin d’accès cible est affecté à la valeur L " SymbolicLinkValue " de la clé. Le chemin d’accès cible doit être un chemin d’accès de Registre absolu.
REG_OPTION_NON_VOLATILE 0x000000000L	Cette clé n’est pas volatile ; il s’agit de la valeur par défaut. Les informations sont stockées dans un fichier et sont conservées lors du redémarrage du système. La fonction RegSaveKey enregistre les clés qui ne sont pas volatiles.
REG_OPTION_VOLATILE 0x00000001L	Toutes les clés créées par la fonction sont volatiles. Les informations sont stockées en mémoire et ne sont pas conservées lorsque la ruche de Registre correspondante est déchargée. Pour HKEY_LOCAL_MACHINE, cela se produit uniquement lorsque le système lance un arrêt complet. Pour les clés de Registre chargées par la fonction RegLoadKey , cela se produit lorsque le RegUnLoadKey correspondant est effectué. La fonction RegSaveKey n’enregistre pas les clés volatiles. Cet indicateur est ignoré pour les clés qui existent déjà. Note Sur un arrêt sélectionné par l’utilisateur, un arrêt de démarrage rapide est le comportement par défaut du système.

[in] samDesired

Masque qui spécifie les droits d’accès pour la clé à créer. Pour plus d’informations, consultez Sécurité de la clé de Registre et droits d’accès.

[in, optional] lpSecurityAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui détermine si le handle retourné peut être hérité par des processus enfants. Si lpSecurityAttributes a la valeur NULL, le handle ne peut pas être hérité.

Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour la nouvelle clé. Si lpSecurityAttributes a la valeur NULL, la clé obtient un descripteur de sécurité par défaut. Les ACL d’un descripteur de sécurité par défaut pour une clé sont héritées de sa clé parente directe.

[out] phkResult

Pointeur vers une variable qui reçoit un handle vers la clé ouverte ou créée. Si la clé n’est pas l’une des clés de Registre prédéfinies, appelez la fonction RegCloseKey une fois que vous avez terminé d’utiliser le handle.

[out, optional] lpdwDisposition

Pointeur vers une variable qui reçoit l’une des valeurs de disposition suivantes.

Valeur	Signification
REG_CREATED_NEW_KEY 0x00000001L	La clé n’existait pas et a été créée.
REG_OPENED_EXISTING_KEY 0x00000002L	La clé existait et était simplement ouverte sans être modifiée.

Si lpdwDisposition a la valeur NULL, aucune information de disposition n’est retournée.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est un code d’erreur différent de zéro défini dans Winerror.h. Vous pouvez utiliser la fonction FormatMessage avec l’indicateur FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.

Remarques

La clé créée par la fonction RegCreateKeyEx n’a aucune valeur. Une application peut utiliser la fonction RegSetValueEx pour définir des valeurs de clé.

La fonction RegCreateKeyEx crée toutes les clés manquantes dans le chemin spécifié. Une application peut tirer parti de ce comportement pour créer plusieurs clés à la fois. Par exemple, une application peut créer une sous-clé à quatre niveaux de profondeur en même temps que les trois sous-clés précédentes en spécifiant une chaîne au format suivant pour le paramètre lpSubKey :

subkey1\subkey2\subkey3\subkey4

Notez que ce comportement entraîne la création de clés indésirables si une clé existante dans le chemin d’accès est mal orthographiée.

Une application ne peut pas créer une clé qui est un enfant direct de HKEY_USERS ou HKEY_LOCAL_MACHINE. Une application peut créer des sous-clés dans les niveaux inférieurs des arborescences HKEY_USERS ou HKEY_LOCAL_MACHINE .

Si votre service ou votre application emprunte l’identité de différents utilisateurs, n’utilisez pas cette fonction avec HKEY_CURRENT_USER. Au lieu de cela, appelez la fonction RegOpenCurrentUser .

Notez que les opérations qui accèdent à certaines clés de Registre sont redirigées. Pour plus d’informations, consultez Virtualisation du Registre et Données d’application 32 bits et 64 bits dans le Registre.

Notes

L’en-tête winreg.h définit RegCreateKeyEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winreg.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll