Fonction RegCreateKeyA (winreg.h)
Crée la clé de Registre spécifiée. Si la clé existe déjà dans le Registre, la fonction l’ouvre.
Syntaxe
LSTATUS RegCreateKeyA(
[in] HKEY hKey,
[in, optional] LPCSTR lpSubKey,
[out] PHKEY phkResult
);
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 créent des clés 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, 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 avoir la valeur NULL. Dans ce cas, phkResult reçoit le même handle hKey passé à 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 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
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 .
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 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.
Notes
L’en-tête winreg.h définit RegCreateKey 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 |