Função RegLoadAppKeyA (winreg.h)

  • Artigo

Carrega o hive do registro especificado como um hive de aplicativo.

Sintaxe

LSTATUS RegLoadAppKeyA(
  [in]  LPCSTR lpFile,
  [out] PHKEY  phkResult,
  [in]  REGSAM samDesired,
  [in]  DWORD  dwOptions,
        DWORD  Reserved
);

Parâmetros

[in] lpFile

O nome do arquivo hive. Esse hive deve ter sido criado com a função RegSaveKey ou RegSaveKeyEx . Se o arquivo não existir, um arquivo hive vazio será criado com o nome especificado.

[out] phkResult

Ponteiro para o identificador da chave raiz do hive carregado.

A única maneira de acessar chaves no hive é por meio desse identificador. O registro impedirá que um aplicativo acesse chaves neste hive usando um caminho absoluto para a chave. Como resultado, não é possível navegar até esse hive por meio do namespace do registro.

[in] samDesired

Uma máscara que especifica os direitos de acesso solicitados para a chave raiz retornada. Para obter mais informações, consulte Segurança de chave do Registro e Direitos de Acesso.

[in] dwOptions

Se esse parâmetro for REG_PROCESS_APPKEY, o hive não poderá ser carregado novamente enquanto ele for carregado pelo chamador. Isso impede o acesso a esse hive do registro por outro chamador.

Reserved

Esse parâmetro é reservado.

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

Ao contrário de RegLoadKey, RegLoadAppKey não carrega o hive em HKEY_LOCAL_MACHINE ou HKEY_USERS. Em vez disso, o hive é carregado sob uma raiz especial que não pode ser enumerada. Como resultado, não há como enumerar hives carregados atualmente por RegLoadAppKey. Todas as operações em hives carregadas por RegLoadAppKey devem ser executadas em relação ao identificador retornado em phkResult.

Se dois processos forem necessários para executar operações no mesmo hive, cada processo deverá chamar RegLoadAppKey para recuperar um identificador. Durante a operação RegLoadAppKey , o registro verificará se o arquivo já foi carregado. Se ele tiver sido carregado, o registro retornará um identificador para o hive carregado anteriormente em vez de recarregar o hive.

Todas as chaves dentro do hive devem ter o mesmo descritor de segurança; caso contrário, a função falhará. Esse descritor de segurança deve conceder ao chamador o acesso especificado pelo parâmetro samDesired ou a função falhará. Não é possível usar a função RegSetKeySecurity em nenhuma chave dentro do hive.

Em Windows 8 e posterior, cada processo pode chamar RegLoadAppKey para carregar vários hives. No Windows 7 e versões anteriores, cada processo pode carregar apenas um hive usando RegLoadAppKey por vez.

Qualquer hive carregado usando RegLoadAppKey é descarregado automaticamente quando todos os identificadores para as chaves dentro do hive são fechados usando RegCloseKey.

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0600 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Observação

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

Confira também

RegSaveKey

Funções do Registro

Hive do Registro