Função RegRestoreKeyA (winreg.h)

Artigo
03/04/2024

Lê as informações do Registro em um arquivo especificado e copia-as pela chave especificada. Essas informações do Registro podem estar na forma de uma chave e vários níveis de subchaves.

Os aplicativos que fazem backup ou restauram o estado do sistema, incluindo arquivos do sistema e hives do Registro, devem usar o Serviço de Cópia de Sombra de Volume em vez das funções do Registro.

Sintaxe

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

Parâmetros

[in] hKey

Um identificador para uma chave aberta do Registro. Esse identificador é retornado pela função RegCreateKeyEx ou RegOpenKeyEx . Ela também pode ser uma das seguintes chaves predefinidas:

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS Todas as informações contidas nessa chave e suas chaves descendentes são substituídas pelas informações no arquivo apontado pelo parâmetro lpFile .

[in] lpFile

O nome do arquivo com as informações do Registro. Normalmente, esse arquivo é criado usando a função RegSaveKey .

[in] dwFlags

Os sinalizadores que indicam como a chave ou as chaves devem ser restauradas. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
REG_FORCE_RESTORE 0x00000008L	Se especificada, a operação de restauração será executada mesmo se houver identificadores abertos no local ou abaixo do local na hierarquia do Registro para a qual o parâmetro hKey aponta.
REG_WHOLE_HIVE_VOLATILE 0x00000001L	Se especificado, um novo conjunto volátil (somente memória) de informações do Registro, ou hive, será criado. Se REG_WHOLE_HIVE_VOLATILE for especificado, a chave identificada pelo parâmetro hKey deverá ser o valor HKEY_USERS ou HKEY_LOCAL_MACHINE .

Retornar valor

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor de retorno será o código de erro diferente de zero definido em Winerror.h. Você pode usar a função FormatMessage com o sinalizador FORMAT_MESSAGE_FROM_SYSTEM para obter uma descrição genérica do erro.

Comentários

Há dois formatos de arquivo hive de registro diferentes. Os hives do Registro criados nos sistemas operacionais atuais normalmente não podem ser carregados por outros anteriores.

Se alguma subchave do parâmetro hKey estiver aberta, RegRestoreKey falhará.

O processo de chamada deve ter os privilégios SE_RESTORE_NAME e SE_BACKUP_NAME no computador em que o registro reside. Para obter mais informações, confira Executar com privilégios especiais.

Essa função substitui as chaves e os valores abaixo da chave especificada pelas chaves e valores que são subsidiárias da chave de nível superior no arquivo, independentemente do nome da chave de nível superior no arquivo. Por exemplo, hKey pode identificar uma chave A com subchaves B e C, enquanto o parâmetro lpFile especifica um arquivo que contém a chave X com subchaves Y e Z. Após uma chamada para RegRestoreKey, o Registro conteria a chave A com as subchaves Y e Z. As entradas de valor de A seriam substituídas pelas entradas de valor de X.

As novas informações no arquivo especificado por lpFile substituem o conteúdo da chave especificada pelo parâmetro hKey , exceto pelo nome da chave.

Se hKey representar uma chave em um computador remoto, o caminho descrito por lpFile será relativo ao computador remoto.

Observação

O cabeçalho winreg.h define RegRestoreKey como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winreg.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll