Função SHRegQueryUSValueA (shlwapi.h)
Recupera o tipo e os dados de um nome especificado associado a uma subchave do Registro aberta em uma subárvore específica do usuário (HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE).
Sintaxe
LSTATUS SHRegQueryUSValueA(
[in] HUSKEY hUSKey,
[in, optional] LPCSTR pszValue,
[in, out, optional] DWORD *pdwType,
[out, optional] void *pvData,
[in, out] DWORD *pcbData,
[in] BOOL fIgnoreHKCU,
[in, optional] void *pvDefaultData,
[in, optional] DWORD dwDefaultDataSize
);
Parâmetros
[in] hUSKey
Tipo: HUSKEY
Um identificador para uma subchave do Registro aberta no momento ou um dos valores predefinidos a seguir. A subchave deve ter sido aberta com o direito de acesso KEY_SET_VALUE. Para obter mais informações, consulte Segurança de chave do Registro e Direitos de Acesso.
Esse identificador pode ser obtido por meio da função SHRegOpenUSKey .
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA
HKEY_USERS
[in, optional] pszValue
Tipo: LPCTSTR
Um ponteiro para a cadeia de caracteres terminada em nulo que contém o nome do valor a ser consultado.
[in, out, optional] pdwType
Tipo: LPDWORD*
Um ponteiro para a variável que define ou recebe o tipo de valor da chave. Para obter mais informações, consulte Tipos de dados do Registro. Este parâmetro pode ser NULL.
[out, optional] pvData
Tipo: LPVOID*
Um ponteiro para o buffer que recebe os dados do valor. Esse parâmetro poderá ser NULL se os dados não forem necessários.
[in, out] pcbData
Tipo: LPDWORD*
Um ponteiro para a variável que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvData . Quando a função retorna, essa variável contém o tamanho dos dados copiados para pvData.
[in] fIgnoreHKCU
Tipo: BOOL
A variável que especifica em qual chave procurar. Quando definido como TRUE, SHRegQueryUSValue ignora HKEY_CURRENT_USER e retorna o valor da chave em HKEY_LOCAL_MACHINE.
[in, optional] pvDefaultData
Tipo: LPVOID*
Um ponteiro para os dados padrão.
[in, optional] dwDefaultDataSize
Tipo: DWORD
O comprimento, em bytes, dos dados padrão.
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
Quando fIgnoreHKCU é definido como TRUE, SHRegQueryUSValue retorna o valor da chave em HKEY_LOCAL_MACHINE. Quando definido como FALSE, SHRegQueryUSValue primeiro tenta retornar o valor da chave em HKEY_CURRENT_USER. No entanto, se a chave não for encontrada em HKEY_CURRENT_USER, o valor retornará da chave em HKEY_LOCAL_MACHINE. Se nenhuma das chaves estiver presente ou se ocorrer um erro e dwDefaultDataSize for diferente de zero, os dados padrão serão copiados para pvData e ERROR_SUCCESS retornará. ERROR_SUCCESS retorna para dados padrão e não padrão e não há como distinguir qual valor copia para pvData. Para impedir o uso de dados padrão, defina pvDefaultData como NULL e dwDefaultDataSize como zero.
Se você precisar ler apenas um único valor, SHRegGetUSValue abrirá a chave e retornará o valor. Para usar SHRegQueryUSValue, primeiro você deve abrir a chave com SHRegOpenUSKey. No entanto, depois que a chave for aberta, você poderá usar SHRegQueryUSValue quantas vezes forem necessárias. Se você precisar recuperar mais de um valor da mesma chave, usar várias chamadas para SHRegQueryUSValue geralmente é mais eficiente do que SHRegGetUSValue, pois a chave só é aberta uma vez.
Observação
O cabeçalho shlwapi.h define SHRegQueryUSValue 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, Windows XP [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 | shlwapi.h |
Biblioteca | Shlwapi.lib |
DLL | Shlwapi.dll (versão 4.71 ou posterior) |
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