tlsGetValue 函数 (processthreadsapi.h)

项目
03/01/2024

检索调用线程的线程本地存储 (指定 TLS 索引的 TLS) 槽中的值。进程中的每个线程都具有自己的针对每个 TLS 索引的槽。

语法

LPVOID TlsGetValue(
  [in] DWORD dwTlsIndex
);

参数

[in] dwTlsIndex

TlsAlloc 函数分配的 TLS 索引。

返回值

如果函数成功，则返回值是存储在与指定索引关联的调用线程的 TLS 槽中的值。如果 dwTlsIndex 是由成功调用 TlsAlloc 分配的有效索引，则此函数始终成功。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

存储在 TLS 槽中的数据的值可能为 0，因为它仍具有其初始值，或者因为线程调用 TlsSetValue 函数的值为 0。因此，如果返回值为 0，则必须在确定函数失败之前检查 GetLastError 是否返回ERROR_SUCCESS。如果 GetLastError 返回 ERROR_SUCCESS，则表示函数已成功，并且存储在 TLS 槽中的数据为 0。否则，函数失败。

返回失败指示的函数在失败时调用 SetLastError 。它们通常不会在成功时调用 SetLastError 。 TlsGetValue 函数是此常规规则的例外。 TlsGetValue 函数调用 SetLastError 以清除线程成功时的最后一个错误。这允许检查零值的无错误检索。

注解

Windows Phone 8.1：Windows Phone 8.1 及更高版本上的 Windows Phone 应用商店应用支持此函数。当 Windows Phone Store 应用调用此函数时，它将替换为对 FlsGetValue 的内联调用。有关函数文档，请参阅 FlsGetValue 。

Windows 8.1、Windows Server 2012 R2 和 Windows 10 版本 1507：Windows 8.1、Windows Server 2012 R2 和 Windows 10 版本上的 Windows 应用商店应用支持此函数1507. 当 Windows 应用商店应用调用此函数时，它将替换为 对 FlsGetValue 的内联调用。有关函数文档，请参阅 FlsGetValue 。

Windows 10版本 1511 和 Windows 10 版本 1607：通用 Windows 平台 (UWP) 应用完全支持此函数，不再替换为对 FlsGetValue 的内联调用。

TLS 索引通常由 TlsAlloc 函数在进程或 DLL 初始化期间分配。分配 TLS 索引后，进程的每个线程都可以使用它来访问该索引的自己的 TLS 槽。线程在调用 TlsSetValue 时指定 TLS 索引，以在其槽中存储值。线程在后续调用 TlsGetValue 中指定相同的索引，以检索存储的值。

TlsGetValue 以速度实现为主要目标。函数执行最小参数验证和错误检查。具体而言，如果 dwTlsIndex 在范围 0 到 (TLS_MINIMUM_AVAILABLE – 1) ，则成功。程序员需要确保索引有效，并且线程在调用 TlsGetValue 之前调用 TlsSetValue。

示例

有关示例，请参阅使用线程本地存储或在 Dynamic-Link 库中使用线程本地存储。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	processthreadsapi.h (包括 Windows Vista 上的 Windows.h、Windows 7、Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib;Windows Phone 8.1 上的 WindowsPhoneCore.lib
DLL	Windows Phone 8.1 上的 KernelBase.dll;Kernel32.dll