RegSaveKeyExA, fonction (winreg.h)

Article
08/27/2023

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

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

Paramètres

[in] hKey

Handle d’une clé de Registre ouverte.

Cette fonction ne prend pas en charge la clé prédéfinie HKEY_CLASSES_ROOT .

[in] lpFile

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

Le nouveau fichier a l’attribut archive.

Si la chaîne n’inclut pas de chemin, le fichier est créé dans le répertoire actif du processus appelant pour une clé locale ou dans le répertoire %systemroot%\system32 pour une clé distante.

[in, optional] lpSecurityAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES qui spécifie un descripteur de sécurité pour le nouveau fichier. Si lpSecurityAttributes a la valeur 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.

[in] Flags

Format de la clé ou de la ruche enregistrée. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
REG_STANDARD_FORMAT 1	La clé ou la ruche est enregistrée au format standard. Le format standard est le seul format pris en charge par Windows 2000.
REG_LATEST_FORMAT 2	La clé ou la ruche est enregistrée dans le dernier format. Le dernier format est pris en charge à partir de Windows XP. Une fois la clé ou la ruche enregistrée dans ce format, elle ne peut pas être chargée sur un système antérieur.
REG_NO_COMPRESSION 4	La ruche est enregistrée sans compression, pour des opérations d’enregistrement plus rapides. Le paramètre hKey doit spécifier la racine d’une ruche sous HKEY_LOCAL_MACHINE ou HKEY_USERS. Par exemple, HKLM\SOFTWARE est la racine d’une ruche.

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.

Si plusieurs des valeurs possibles répertoriées ci-dessus pour le paramètre Flags sont spécifiées dans un appel à cette fonction (par exemple, si deux ou plusieurs valeurs sont OR’ed) ou si REG_NO_COMPRESSION est spécifié et que hKey spécifie une clé qui n’est pas la racine d’une ruche, cette fonction retourne ERROR_INVALID_PARAMETER.

Remarques

Contrairement à RegSaveKey, cette fonction ne prend pas en charge la clé prédéfinie HKEY_CLASSES_ROOT .

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

La fonction RegSaveKeyEx enregistre uniquement les clés non volatiles. Il n’enregistre pas les clés volatiles. Une clé est rendue volatile ou non volatile lors de sa création ; consultez RegCreateKeyEx.

Vous pouvez utiliser le fichier créé par RegSaveKeyEx dans les appels suivants à la fonction RegLoadKey, RegReplaceKey ou RegRestoreKey . Si RegSaveKeyEx échoue au cours de son opération, le fichier est endommagé et les appels suivants à RegLoadKey, RegReplaceKey ou RegRestoreKey pour le fichier échouent.

L’utilisation de RegSaveKeyEx 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 privilège SE_BACKUP_NAME doit être activé pour le processus appelant. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.

Notes

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

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