Fonction RegRestoreKeyA (winreg.h)

Article
08/27/2023

Lit les informations du Registre dans un fichier spécifié et les copie sur la clé spécifiée. Ces informations de Registre peuvent se présenter sous la forme d’une clé et de plusieurs niveaux de sous-clés.

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 du Registre.

Syntaxe

LSTATUS RegRestoreKeyA(
  [in] HKEY   hKey,
  [in] LPCSTR lpFile,
  [in] DWORD  dwFlags
);

Paramètres

[in] hKey

Handle d’une clé de Registre ouverte. Ce handle est retourné par la fonction RegCreateKeyEx ou RegOpenKeyEx . Il peut également s’agir de l’une des clés prédéfinies suivantes :

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS Toutes les informations contenues dans cette clé et ses clés descendantes sont remplacées par les informations du fichier pointées par le paramètre lpFile .

[in] lpFile

Nom du fichier avec les informations du Registre. Ce fichier est généralement créé à l’aide de la fonction RegSaveKey .

[in] dwFlags

Indicateurs qui indiquent comment la clé ou les clés doivent être restaurées. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
REG_FORCE_RESTORE 0x00000008L	Si elle est spécifiée, l’opération de restauration est exécutée même si des handles ouverts existent au niveau ou en dessous de l’emplacement dans la hiérarchie du Registre vers lequel pointe le paramètre hKey .
REG_WHOLE_HIVE_VOLATILE 0x00000001L	S’il est spécifié, un nouvel ensemble volatile (mémoire uniquement) d’informations du Registre, ou hive, est créé. Si REG_WHOLE_HIVE_VOLATILE est spécifié, la clé identifiée par le paramètre hKey doit être la valeur HKEY_USERS ou HKEY_LOCAL_MACHINE .

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

Il existe deux formats de fichier hive de Registre différents. Les ruches de Registre créées sur les systèmes d’exploitation actuels ne peuvent généralement pas être chargées par les systèmes d’exploitation précédents.

Si des sous-clés du paramètre hKey sont ouvertes, RegRestoreKey échoue.

Le processus appelant doit disposer des privilèges SE_RESTORE_NAME et SE_BACKUP_NAME sur l’ordinateur sur lequel réside le Registre. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.

Cette fonction remplace les clés et les valeurs situées sous la clé spécifiée par les clés et valeurs qui sont filiales de la clé de niveau supérieur dans le fichier, quel que soit le nom de la clé de niveau supérieur dans le fichier. Par exemple, hKey peut identifier une clé A avec les sous-clés B et C, tandis que le paramètre lpFile spécifie un fichier contenant la clé X avec les sous-clés Y et Z. Après un appel à RegRestoreKey, le Registre contient la clé A avec les sous-clés Y et Z. Les entrées de valeur de A sont remplacées par les entrées de valeur de X.

Les nouvelles informations dans le fichier spécifié par lpFile remplacent le contenu de la clé spécifiée par le paramètre hKey , à l’exception du nom de clé.

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

Notes

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