Função SHRegGetUSValueA (shlwapi.h)

Recupera um valor de uma subchave do Registro em uma subárvore específica do usuário (HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE).

Sintaxe

LSTATUS SHRegGetUSValueA(
  [in]                LPCSTR pszSubKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out, optional] DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in]                DWORD  dwDefaultDataSize
);

Parâmetros

[in] pszSubKey

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo com o nome da subchave relativa a HKEY_LOCAL_MACHINE e HKEY_CURRENT_USER. Por exemplo: "Software\MyCompany\MyProduct".

[in, optional] pszValue

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo com o nome do valor. Esse valor pode ser NULL.

[in, out, optional] pdwType

Tipo: DWORD*

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 as informações de tipo não forem necessárias, esse parâmetro poderá ser NULL.

[out, optional] pvData

Tipo: void*

Um ponteiro para um buffer que recebe os dados do valor.

[in, out, optional] pcbData

Tipo: DWORD*

Um ponteiro para uma variável que especifica o tamanho, em bytes, do buffer apontado por pvData. Quando SHRegGetUSValue retorna, pcbData contém o tamanho dos dados copiados para pvData.

[in] fIgnoreHKCU

Tipo: BOOL

Uma variável que especifica em qual chave procurar. Quando definido como TRUE, SHRegGetUSValue ignora HKEY_CURRENT_USER e retorna o valor da chave em HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Tipo: void*

Um ponteiro para um buffer que recebe os dados padrão do valor.

[in] dwDefaultDataSize

Tipo: DWORD

O comprimento, em bytes, do buffer apontado por pvDefaultData.

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, SHRegGetUSValue retorna o valor da chave em HKEY_LOCAL_MACHINE. Quando definido como FALSE, SHRegGetUSValue 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 será retornado 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.

Essa função abre a chave sempre que é usada. Se o código envolver a obtenção de uma série de valores da mesma chave, será mais eficiente abrir a chave uma vez com SHRegOpenUSKey e, em seguida, usar SHRegQueryUSValue para recuperar os dados.

Observação

O cabeçalho shlwapi.h define SHRegGetUSValue 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)