Função SHRegGetValueW (shlwapi.h)
[SHRegGetValue pode ser alterado ou indisponível em versões subsequentes do sistema operacional ou do produto. Use RegGetValue em seu lugar.]
Recupera um valor do Registro.
Sintaxe
LSTATUS SHRegGetValueW(
[in] HKEY hkey,
[in] LPCWSTR pszSubKey,
[in] LPCWSTR pszValue,
[in] SRRF srrfFlags,
[in, out] DWORD *pdwType,
[out] void *pvData,
[in, out] DWORD *pcbData
);
Parâmetros
[in] hkey
Tipo: HKEY
Um identificador para a chave aberta no momento ou qualquer um dos valores predefinidos a seguir.
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA
HKEY_USERS
[in] pszSubKey
Tipo: LPCTSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho relativo de hkey para a subchave da qual recuperar o valor. Esse parâmetro pode ser NULL ou uma cadeia de caracteres vazia, nesse caso, os dados são recuperados do local do hkey .
[in] pszValue
Tipo: LPCTSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do valor. Esse parâmetro pode ser NULL ou uma cadeia de caracteres vazia, nesse caso, os dados são recuperados do valor Padrão.
[in] srrfFlags
Tipo: SRRF
Um ou mais dos sinalizadores SRRF que restringem os dados a serem recuperados. Pelo menos um valor de restrição de tipo (SRRF_RT) deve ser especificado.
[in, out] pdwType
Tipo: LPDWORD
Um ponteiro para um DWORD que recebe o tipo de dados armazenados no valor recuperado. Ao usar valores padrão, o pdwType de entrada é o tipo do valor padrão. Para obter valores possíveis, consulte Tipos de dados do Registro. Se o sinalizador SRRF_NOEXPAND não estiver definido, REG_EXPAND_SZ tipos serão automaticamente expandidos e retornados como REG_SZ. Se as informações de tipo não forem necessárias, esse parâmetro poderá ser NULL.
[out] pvData
Tipo: LPVOID
Um ponteiro para um buffer que recebe os dados do valor. Esse parâmetro poderá ser NULL se os dados não forem necessários. Por exemplo, se você estivesse testando apenas a existência de um valor, os dados de valor específicos seriam supérfluos.
[in, out] pcbData
Tipo: LPDWORD
Um ponteiro para um DWORD que, na entrada, contém o tamanho do buffer de dados de destino pvData, em bytes. Esse valor só poderá ser NULL se pvData for NULL. Na saída, pcbData aponta para um desses valores.
pvData | Valor Retornado | pcbData |
---|---|---|
NULL | ERROR_SUCCESS | Tamanho em bytes suficiente para armazenar os dados do Registro. Observe que isso não é garantido para ser o tamanho preciso, mas apenas um tamanho suficiente. |
Não NULL | ERROR_SUCCESS | Número exato de bytes gravados em pvData. |
Não NULL | ERROR_MORE_DATA | Tamanho em bytes necessários para manter todos os dados. Observe que isso não é garantido para ser o tamanho preciso, mas apenas um tamanho suficiente. |
Retornar valor
Tipo: LSTATUS
Retorna ERROR_SUCCESS se tiver êxito ou um código de erro diferente de zero definido em Winerror.h caso contrário. Você pode usar a função FormatMessage com o sinalizador FORMAT_MESSAGE_FROM_SYSTEM para recuperar uma descrição genérica do erro.
Comentários
SHRegGetValue fornece verificação de tipo de dados, verificação do modo de inicialização, expansão automática de dados REG_EXPAND_SZ e terminação nula garantida de dados de REG_SZ, REG_EXPAND_SZ e REG_MULTI_SZ.
A chave identificada pelo hkey deve ter sido aberta com KEY_QUERY_VALUE acesso de segurança. Se pszSubKey não for NULL ou uma cadeia de caracteres vazia, essa chave também deverá ser capaz de ser aberta com KEY_QUERY_VALUE acesso de segurança no contexto de chamada atual.
Se o tipo de dados for REG_SZ, REG_EXPAND_SZ ou REG_MULTI_SZ, todos os dados retornados incluirão ou levarão em conta o encerramento nulo da cadeia de caracteres. Por exemplo, se pvData não for NULL, os dados retornados nesse buffer serão encerrados em nulo. Se pcbData não for NULL, o tamanho do buffer para o qual ele aponta incluirá os bytes necessários para manter o caractere nulo de terminação.
A menos que o sinalizador SRRF_NOEXPAND esteja definido, os dados de cadeia de caracteres do tipo REG_EXPAND_SZ serão expandidos automaticamente antes de serem retornados. O tipo da cadeia de caracteres expandida é relatado em pdwType como REG_SZ, o parâmetro pcbData aponta para o número de bytes gravados para a cadeia de caracteres expandida e o buffer apontado por pvData mantém a versão expandida da cadeia de caracteres.
Notas de desempenho
Se pszSubKey não for NULL ou uma cadeia de caracteres vazia, essa chave será aberta e fechada por essa função sempre que for acessada. Se o aplicativo precisar recuperar uma série de valores da mesma subchave, você verá um melhor desempenho abrindo a chave usando RegOpenKeyEx antes de chamar SHRegGetValue. Use a chave retornada no parâmetro phkResult de RegOpenKeyEx como o parâmetro hkey nessa função, com pszSubKey definido como NULL.O potencial de uma chamada adicional ao Registro para ler ou ler novamente os dados existe quando o tipo de dados é REG_EXPAND_SZ e o sinalizador SRRF_NOEXPAND não foi definido. As condições a seguir resultam nessa chamada adicional.
- pvData é NULL, pcbData não é NULL. Embora os dados não sejam recuperados, o registro deve ser lido para obter a cadeia de caracteres e essa cadeia de caracteres expandida para determinar o tamanho necessário do buffer de dados.
- pvData não é NULL, mas é muito pequeno para manter os dados. Os dados são lidos novamente para obter a cadeia de caracteres completa, a cadeia de caracteres é expandida e o tamanho total necessário é determinado.
Observação
O cabeçalho shlwapi.h define SHRegGetValue 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 com SP2 [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 | shlwapi.h |
Biblioteca | Shlwapi.lib |
DLL | Shlwapi.dll (versão 6.0 ou posterior) |
Confira também
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de