RegCreateKeyW, fonction (winreg.h)

Article
11/20/2024

Crée la clé de Registre spécifiée. Si la clé existe déjà dans le Registre, la fonction l’ouvre.

Remarque Cette fonction est fournie uniquement pour la compatibilité avec les versions 16 bits de Windows. Les applications doivent utiliser la fonction RegCreateKeyEx. Toutefois, les applications qui sauvegardent ou restaurent l’état du système, y compris les fichiers système et les ruches de Registre, doivent utiliser le service de cliché instantané de volume au lieu des fonctions de Registre.

Syntaxe

LSTATUS RegCreateKeyW(
  [in]           HKEY    hKey,
  [in, optional] LPCWSTR lpSubKey,
  [out]          PHKEY   phkResult
);

Paramètres

[in] hKey

Handle vers 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é des clés de Registre et droits d’accès.

L’accès à 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, il peut être utilisé dans les opérations qui créent des clés si elles sont autorisées par son descripteur de sécurité.

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, optional] lpSubKey

Nom d’une clé que cette fonction ouvre ou crée. Cette clé doit être une sous-clé de la clé identifiée par le paramètre hKey.

Pour plus d’informations sur les noms de clés, consultez Structure du Registre.

Si hKey est l’une des clés prédéfinies, lpSubKey peut être NULL. Dans ce cas, phkResult reçoit le même handle hKey transmis à la fonction.

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

Valeur de retour

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 de FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.

Remarques

Une application ne peut pas créer une clé qui est un enfant direct de HKEY_USERS ou de HKEY_LOCAL_MACHINE. Une application peut créer des sous-clés dans des 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.

La fonction RegCreateKey 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 quatre niveaux de sous-clé en même temps que les trois sous-clés précédentes en spécifiant une chaîne du formulaire 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 orthographié de manière incorrecte.

Note

L’en-tête winreg.h définit RegCreateKey comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winreg.h (inclure Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll