Função TlsGetValue (processthreadsapi.h)

Artigo
02/07/2024

Recupera o valor no slot TLS (armazenamento local de thread) 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 que foi alocado pela função TlsAlloc .

Retornar valor

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 têm seu valor inicial ou porque o thread chamou a função TlsSetValue com 0. Portanto, se o valor retornado for 0, você deverá marcar se GetLastErrorretornará 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 TLS serão 0. Caso contrário, a função falhou.

Funções que retornam indicações de falha chamam SetLastError quando falham. Eles geralmente não chamam SetLastError quando são bem-sucedidos. 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 é bem-sucedido. Isso permite verificar a recuperação sem erros de valores zero.

Comentários

Windows Phone 8.1: essa função tem suporte para aplicativos Windows Phone Store no Windows Phone 8.1 e posterior. Quando um aplicativo da Windows Phone Store chama essa função, ele é substituído por uma chamada embutida para FlsGetValue. Consulte FlsGetValue para obter a documentação da função.

Windows 8.1, Windows Server 2012 R2 e Windows 10, versão 1507: essa função tem suporte para aplicativos da Windows Store em 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 tem suporte total para aplicativos 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 o processo ou a inicialização 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 a meta 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.

Exemplos

Para obter um exemplo, consulte Usando o armazenamento local do thread ou Usando o armazenamento local de thread em uma biblioteca de Dynamic-Link.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
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
DLL	KernelBase.dll no Windows Phone 8.1; Kernel32.dll