Função RegSaveKeyExA (winreg.h)

Artigo
03/13/2024

Salva a chave especificada e todas as subchaves e valores em um arquivo do Registro, no formato especificado.

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

Parâmetros

[in] hKey

Um identificador para uma chave aberta do Registro.

Essa função não dá suporte à chave predefinida HKEY_CLASSES_ROOT.

[in] lpFile

O nome do arquivo no qual a chave e as subchaves especificadas devem ser salvas. Se o arquivo já existir, a função falhará.

O novo arquivo tem o atributo archive.

Se a cadeia de caracteres não incluir um caminho, o arquivo será criado no diretório atual do processo de chamada para uma chave local ou no diretório %systemroot%\system32 para uma chave remota.

[in, optional] lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo arquivo. Se lpSecurityAttributes for NULL, o arquivo receberá um descritor de segurança padrão. As ACLs em um descritor de segurança padrão para um arquivo são herdadas de seu diretório pai.

[in] Flags

O formato da chave salva ou do hive. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
REG_STANDARD_FORMAT 1	A chave ou o hive é salvo no formato padrão. O formato padrão é o único formato compatível com o Windows 2000.
REG_LATEST_FORMAT 2	A chave ou o hive é salvo no formato mais recente. O formato mais recente tem suporte a partir do Windows XP. Depois que a chave ou o hive for salvo nesse formato, ele não poderá ser carregado em um sistema anterior.
REG_NO_COMPRESSION 4	O hive é salvo sem compactação, para operações de salvamento mais rápidas. O parâmetro hKey deve especificar a raiz de um hive em HKEY_LOCAL_MACHINE ou HKEY_USERS. Por exemplo, HKLM\SOFTWARE é a raiz de um hive.

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.

Se mais de um dos valores possíveis listados acima para o parâmetro Flags for especificado em uma chamada para essa função, por exemplo, se dois ou mais valores forem OR'ed, ou se REG_NO_COMPRESSION for especificado e hKey especificar uma chave que não seja a raiz de um hive, essa função retornará ERROR_INVALID_PARAMETER.

Comentários

Ao contrário de RegSaveKey, essa função não dá suporte à chave predefinida HKEY_CLASSES_ROOT .

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

A função RegSaveKeyEx salva apenas chaves nãovolatile. Ele não salva chaves voláteis. Uma chave é torna-se volátil ou não volátil em sua criação; consulte RegCreateKeyEx.

Você pode usar o arquivo criado por RegSaveKeyEx em chamadas subsequentes para a função RegLoadKey, RegReplaceKey ou RegRestoreKey . Se RegSaveKeyEx falhar parcialmente em sua operação, o arquivo será corrompido e as chamadas subsequentes para RegLoadKey, RegReplaceKey ou RegRestoreKey para o arquivo falharão.

Não é recomendável usar RegSaveKeyEx junto com RegRestoreKey para copiar subárvores no registro. Esse método não dispara notificações e pode invalidar identificadores usados por outros aplicativos. Em vez disso, use a função SHCopyKey ou a função RegCopyTree .

O processo de chamada deve ter o privilégio SE_BACKUP_NAME habilitado. Para obter mais informações, confira Executar com privilégios especiais.

Observação

O cabeçalho winreg.h define RegSaveKeyEx 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 XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winreg.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll