Função SHRegQueryUSValueA (shlwapi.h)

Recupera o tipo e os dados de um nome especificado associado a uma subchave aberta do Registro 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 seguintes valores predefinidos. A subchave deve ter sido aberta com o KEY_SET_VALUE direito de acesso. Para obter mais informações, consulte de Direitos de Acesso e Segurança de Chave do Registro.

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 o cadeia de caracteresterminada nula 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. Esse 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 a chave a ser pesquisada. 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.

Valor de retorno

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.

Observações

Quando fIgnoreHKCU é definido como VERDADEIRO, 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 não for 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 quais cópias de valor para pvData. Para impedir o uso de dados padrão, defina pvDefaultData para 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 abra 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.

Requisitos