Função SHRegGetUSValueA (shlwapi.h)

Artigo
11/20/2024

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, a entrada pdwType é 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 a chave a ser pesquisada. 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.

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 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 não for zero, os dados padrão serão copiados para pvData e ERROR_SUCCESS retorna. 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.

Essa função abre a chave sempre que ela é 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shlwapi.h
biblioteca	Shlwapi.lib
de DLL	Shlwapi.dll (versão 4.71 ou posterior)

Compartilhar via