Função RegReplaceKeyA (winreg.h)

Artigo
03/13/2024

Substitui o arquivo que dá suporte a uma chave do Registro e todas as suas subchaves por outro arquivo, para que, quando o sistema for iniciado em seguida, a chave e as subchaves tenham os valores armazenados no novo arquivo.

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 RegReplaceKeyA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           LPCSTR lpNewFile,
  [in]           LPCSTR lpOldFile
);

Parâmetros

[in] hKey

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

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS

[in, optional] lpSubKey

O nome da chave do Registro cujas subchaves e valores devem ser substituídos. Se a chave existir, ela deverá ser uma subchave da chave identificada pelo parâmetro hKey . Se a subchave não existir, ela será criada. Este parâmetro pode ser NULL.

Se a subchave especificada não for a raiz de um hive, RegReplaceKey percorrerá a estrutura da árvore hive até encontrar uma raiz de hive, então substituirá o conteúdo desse hive pelo conteúdo do arquivo de dados especificado por lpNewFile.

Para obter mais informações, consulte Limites de tamanho do elemento do Registro.

[in] lpNewFile

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

[in] lpOldFile

O nome do arquivo que recebe uma cópia de backup das informações do Registro que estão sendo substituídas.

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.

O arquivo especificado pelo parâmetro lpNewFile permanece aberto até que o sistema seja reiniciado.

Se hKey for um identificador retornado por RegConnectRegistry, os caminhos especificados em lpNewFile e lpOldFile serão relativos ao computador remoto.

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.

Observação

O cabeçalho winreg.h define RegReplaceKey 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