RegSaveKeyA, fonction (winreg.h)

Article
11/20/2024

Enregistre la clé spécifiée et toutes ses sous-clés et valeurs dans un nouveau fichier, au format standard.

Pour spécifier le format de la clé ou de la ruche enregistrée, utilisez la fonction RegSaveKeyEx.

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 RegSaveKeyA(
  [in]           HKEY                        hKey,
  [in]           LPCSTR                      lpFile,
  [in, optional] const LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Paramètres

[in] hKey

Handle vers une clé de Registre ouverte.

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_USER

[in] lpFile

Nom du fichier dans lequel la clé et les sous-clés spécifiés doivent être enregistrés. Si le fichier existe déjà, la fonction échoue.

Si la chaîne n’inclut pas de chemin d’accès, le fichier est créé dans le répertoire actif du processus appelant pour une clé locale, ou dans le répertoire %systemroot%\system32 d’une clé distante. Le nouveau fichier a l’attribut archive.

[in, optional] lpSecurityAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES qui spécifie un descripteur de sécurité pour le nouveau fichier. Si lpSecurityAttributes est NULL, le fichier 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 un fichier sont héritées de son répertoire parent.

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.

Si le fichier existe déjà, la fonction échoue avec l’erreur ERROR_ALREADY_EXISTS.

Remarques

Si hKey représente une clé sur un ordinateur distant, le chemin décrit par lpFile est relatif à l’ordinateur distant.

La fonction RegSaveKey enregistre uniquement les clés nonvolatiles. Il n’enregistre pas les clés volatiles. Une clé est rendue volatile ou nonvolatile lors de sa création ; voir RegCreateKeyEx.

Vous pouvez utiliser le fichier créé par RegSaveKey dans les appels suivants aux fonctions RegLoadKey, RegReplaceKeyou RegRestoreKey. Si RegSaveKey échoue en partie par le biais de son opération, le fichier est endommagé et les appels suivants à RegLoadKey, RegReplaceKey, ou RegRestoreKey pour le fichier échoue.

L’utilisation de RegSaveKey avec RegRestoreKey pour copier des sous-arborescences dans le Registre n’est pas recommandée. Cette méthode ne déclenche pas de notifications et peut invalider les handles utilisés par d’autres applications. Utilisez plutôt la fonction SHCopyKey ou la fonction RegCopyTree.

Le processus appelant doit avoir le privilège SE_BACKUP_NAME activé. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.

Note

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