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.

Requisitos