RegCreateKeyTransactedA, fonction (winreg.h)
Crée la clé de Registre spécifiée et l’associe à une transaction. Si la clé existe déjà, la fonction l’ouvre. Notez que les noms de clé ne respectent pas la casse.
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 de Registre.
Syntaxe
LSTATUS RegCreateKeyTransactedA(
[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,
[in] HANDLE hTransaction,
PVOID pExtendedParemeter
);
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, il peut être utilisé 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 RegCreateKeyTransacted ou RegOpenKeyTransacted , 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 pour la clé spécifiée par hKey.
Ce paramètre ne peut pas être NULL.
Reserved
Ce paramètre est réservé et doit être égal à zéro.
[in, optional] lpClass
Classe définie 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 |
|---|---|
|
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 sauvegarder ou restaurer la clé. Si le thread appelant a le privilège SE_BACKUP_NAME activé, la clé est ouverte avec le ACCESS_SYSTEM_SECURITY et les droits d’accès KEY_READ. Si le thread appelant a le privilège SE_RESTORE_NAME activé, la clé est ouverte avec les droits d’accès ACCESS_SYSTEM_SECURITY 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. |
|
Cette clé n’est pas volatile ; il s’agit de la valeur par défaut. Les informations sont stockées dans un fichier et conservées lors du redémarrage du système. La fonction RegSaveKey enregistre les clés qui ne sont pas volatiles. |
|
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. Par HKEY_LOCAL_MACHINE, cela se produit lorsque le système est arrêté. Pour les clés de Registre chargées par la fonction RegLoadKey , cela se produit lorsque la RegUnLoadKey correspondante est effectuée. La fonction RegSaveKey n’enregistre pas les clés volatiles. Cet indicateur est ignoré pour les clés qui existent déjà. |
[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 SECURITY_ATTRIBUTES qui détermine si le handle retourné peut être hérité par les 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 listes de contrôle d’accès dans 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é ne fait pas partie 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 |
|---|---|
|
La clé n’existait pas et a été créée. |
|
La clé existait et a été simplement ouverte sans être modifiée. |
Si lpdwDisposition a la valeur NULL, aucune information de disposition n’est retournée.
[in] hTransaction
Handle pour une transaction active. Ce handle est retourné par la fonction CreateTransaction .
pExtendedParemeter
Ce paramètre est réservé et doit être NULL.
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
Lorsqu’une clé est créée à l’aide de cette fonction, les opérations suivantes sur la clé sont traitées. Si une opération non transactionnelle est effectuée sur la clé avant la validation de la transaction, la transaction est restaurée. Une fois qu’une transaction est validée ou restaurée, vous devez rouvrir la clé à l’aide de RegCreateKeyTransacted ou RegOpenKeyTransacted avec un handle de transaction actif pour effectuer des opérations supplémentaires traitées. Pour plus d’informations sur les transactions, consultez Kernel Transaction Manager.
Notez que les opérations suivantes sur les sous-clés de cette clé ne sont pas traitées automatiquement. Par conséquent, RegDeleteKeyEx n’effectue pas d’opération de suppression transactionnée. Utilisez plutôt la fonction RegDeleteKeyTransacted pour effectuer une opération de suppression transactionnée.
La clé créée par la fonction RegCreateKeyTransacted n’a aucune valeur. Une application peut utiliser la fonction RegSetValueEx pour définir des valeurs de clé.
La fonction RegCreateKeyTransacted 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é de quatre niveaux de profondeur en même temps que les trois sous-clés précédentes en spécifiant une chaîne de la forme suivante 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 incorrectement 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 .
Notes
L’en-tête winreg.h définit RegCreateKeyTransacted en tant qu’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. La combinaison 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
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winreg.h (inclure Windows.h) |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |