Função SHRegGetValueA (shlwapi.h)
[ SHRegGetValue podem estar alterados ou indisponíveis nas versões subsequentes do sistema operacional ou do produto. Use RegGetValue em seu lugar.]
Recupera um valor do Registro.
Sintaxe
LSTATUS SHRegGetValueA(
[in] HKEY hkey,
[in] LPCSTR pszSubKey,
[in] LPCSTR pszValue,
[in] SRRF srrfFlags,
[in, out] DWORD *pdwType,
[out] void *pvData,
[in, out] DWORD *pcbData
);
Parâmetros
[in] hkey
Tipo: HKEY
Um identificador para a chave aberta no momento ou qualquer um dos valores predefinidos a seguir.
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA
HKEY_USERS
[in] pszSubKey
Tipo: LPCTSTR
Um ponteiro para um cadeia de caracteresterminada nula que especifica o caminho relativo de hkey para a subchave da qual recuperar o valor. Esse parâmetro pode ser
[in] pszValue
Tipo: LPCTSTR
Um ponteiro para um cadeia de caracteresterminada nula que contém o nome do valor. Esse parâmetro pode ser NULL ou uma cadeia de caracteres vazia, nesse caso, os dados são recuperados do valor Padrão.
[in] srrfFlags
Um ou mais dos sinalizadores SRRF
[in, out] pdwType
Tipo: LPDWORD
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 o sinalizador de SRRF_NOEXPAND não estiver definido, REG_EXPAND_SZ tipos serão expandidos e retornados automaticamente como REG_SZ. Se as informações de tipo não forem necessárias, esse parâmetro poderá ser NULL.
[out] pvData
Tipo: LPVOID
Um ponteiro para um buffer que recebe os dados do valor. Esse parâmetro poderá ser NULL se os dados não forem necessários. Por exemplo, se você estivesse testando apenas a existência de um valor, os dados de valor específicos seriam supérfluos.
[in, out] pcbData
Tipo: LPDWORD
Um ponteiro para um DWORD que, na entrada, contém o tamanho do buffer de dados de destino pvData, em bytes. Esse valor poderá ser NULL somente se pvData estiver NULL. Na saída, pcbData aponta para um desses valores.
| pvData | Valor retornado | pcbData |
|---|---|---|
| NULL | ERROR_SUCCESS | Tamanho em bytes suficiente para armazenar os dados do Registro. Observe que isso não é garantido como o tamanho preciso, mas apenas um tamanho suficiente. |
| NULL não |
ERROR_SUCCESS | Número exato de bytes gravados em pvData. |
| NULL não |
ERROR_MORE_DATA | Tamanho em bytes necessários para armazenar os dados inteiros. Observe que isso não é garantido como o tamanho preciso, mas apenas um tamanho suficiente. |
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
SHRegGetValue fornece verificação de tipo de dados, verificação do modo de inicialização, expansão automática de dados REG_EXPAND_SZ e garantia de nulo -terminação de dados REG_SZ, REG_EXPAND_SZ e REG_MULTI_SZ.
A chave identificada por hkey deve ter sido aberta com KEY_QUERY_VALUE acesso de segurança. Se pszSubKey não estiver NULL ou uma cadeia de caracteres vazia, essa chave também deverá ser capaz de ser aberta com KEY_QUERY_VALUE acesso de segurança no contexto de chamada atual.
Se o tipo de dados for REG_SZ, REG_EXPAND_SZ ou REG_MULTI_SZ, todos os dados retornados incluirão ou levarão em conta o nulo da cadeia de caracteres-terminação. Por exemplo, se pvData não estiver NULL, os dados retornados nesse buffer serão nulos - encerrados. Se
A menos que o sinalizador SRRF_NOEXPAND esteja definido, os dados de cadeia de caracteres do tipo REG_EXPAND_SZ serão expandidos automaticamente antes de serem retornados. O tipo de cadeia de caracteres expandida é relatado em pdwType como REG_SZ, o parâmetro pcbData aponta para o número de bytes gravados para a cadeia de caracteres expandida e o buffer apontado por pvData mantém a versão expandida da cadeia de caracteres.
Notas de desempenho do
Se pszSubKey não estiver NULL ou uma cadeia de caracteres vazia, essa chave será aberta e fechada por essa função sempre que for acessada. Se o aplicativo precisar recuperar uma série de valores da mesma subchave, você verá um melhor desempenho abrindo a chave usando RegOpenKeyEx antes de chamar SHRegGetValue. Use a chave retornada no parâmetroO potencial de uma chamada adicional ao Registro para ler ou ler novamente os dados existe quando o tipo de dados é REG_EXPAND_SZ e o sinalizador SRRF_NOEXPAND não foi definido. As condições a seguir resultam nessa chamada adicional.
- pvData é NULL, pcbData não é NULL. Embora os dados não sejam recuperados, o registro deve ser lido para obter a cadeia de caracteres e essa cadeia de caracteres expandida para determinar o tamanho necessário do buffer de dados.
- pvData não é NULL, mas é muito pequeno para armazenar os dados. Os dados são lidos novamente para obter a cadeia de caracteres completa, a cadeia de caracteres é expandida e o tamanho total necessário é determinado.
Nota
O cabeçalho shlwapi.h define SHRegGetValue 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 XP com SP2 [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | shlwapi.h |
| biblioteca | Shlwapi.lib |
| de DLL |
Shlwapi.dll (versão 6.0 ou posterior) |