Função TlsGetValue (processthreadsapi.h)
Recupera o valor no slot TLS (armazenamento local do thread de chamada) para o índice TLS especificado. Cada thread de um processo tem seu próprio slot para cada índice TLS.
Sintaxe
LPVOID TlsGetValue(
[in] DWORD dwTlsIndex
);
Parâmetros
[in] dwTlsIndex
O índice TLS alocado pela função TlsAlloc.
Valor de retorno
Se a função for bem-sucedida, o valor retornado será o valor armazenado no slot TLS do thread de chamada associado ao índice especificado. Se dwTlsIndex for um índice válido alocado por uma chamada bem-sucedida para TlsAlloc, essa função sempre terá êxito.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Os dados armazenados em um slot TLS podem ter um valor de 0 porque ainda tem seu valor inicial ou porque o thread chamado TlsSetValue função com 0. Portanto, se o valor retornado for 0, você deverá verificar se GetLastError retorna ERROR_SUCCESS antes de determinar se a função falhou. Se GetLastError retornar ERROR_SUCCESS, a função terá êxito e os dados armazenados no slot do TLS serão 0. Caso contrário, a função falhou.
Funções que retornam indicações de chamada de falha SetLastError quando falham. Eles geralmente não chamam SetLastError quando tiverem êxito. A função TlsGetValue é uma exceção a essa regra geral. A função TlsGetValue chama SetLastError para limpar o último erro de um thread quando ele for bem-sucedido. Isso permite verificar a recuperação sem erros de valores zero.
Observações
Windows 8.1, Windows Server 2012 R2e Windows 10, versão 1507: essa função tem suporte para aplicativos da Windows Store no Windows 8.1, Windows Server 2012 R2 e Windows 10, versão 1507. Quando um aplicativo da Windows Store chama essa função, ela é substituída por uma chamada embutida para flsGetValue. Consulte FlsGetValue para obter a documentação da função.
Windows 10, versão 1511 e Windows 10, versão 1607: essa função é totalmente compatível com aplicativos da Plataforma Universal do Windows (UWP) e não é mais substituída por uma chamada embutida para FlsGetValue.
Os índices TLS normalmente são alocados pela função TlsAlloc durante a inicialização do processo ou da DLL. Depois que um índice TLS é alocado, cada thread do processo pode usá-lo para acessar seu próprio slot TLS para esse índice. Um thread especifica um índice TLS em uma chamada para TlsSetValue para armazenar um valor em seu slot. O thread especifica o mesmo índice em uma chamada subsequente para TlsGetValue para recuperar o valor armazenado.
TlsGetValue foi implementado com velocidade como o objetivo principal. A função executa validação mínima de parâmetro e verificação de erros. Em particular, ele terá êxito se dwTlsIndex estiver no intervalo de 0 a (TLS_MINIMUM_AVAILABLE– 1). Cabe ao programador garantir que o índice seja válido e que o thread chame TlsSetValue antes de chamar TlsGetValue.
TlsGetValue sempre define o último erro de um thread. Em alguns casos, um aplicativo (como aqueles com heaps personalizados que dão suporte a malloc) pode precisar chamar GetLastError antes de chamar TlsGetValue para salvar o último erro do thread (seguido por SetLastError para restaurar o erro salvo). Infelizmente, isso pode incorrer em um custo de desempenho não trivial em determinadas CPUs.
Exemplos
Para obter um exemplo, consulte usando de Armazenamento Local de Thread ou usando o Armazenamento Local de Thread em umde Biblioteca de Dynamic-Link .
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | processthreadsapi.h (inclua Windows.h no Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| biblioteca | Kernel32.lib; WindowsPhoneCore.lib no Windows Phone 8.1 |
| de DLL |
KernelBase.dll no Windows Phone 8.1; Kernel32.dll |