TlsGetValue 函式 (processthreadsapi.h)

發行項
03/13/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 Store 應用程式支援此函式。當 Windows Phone 市集應用程式呼叫此函式時，它會取代為 FlsGetValue 的內嵌呼叫。如需函式檔，請參閱 FlsGetValue 。

Windows 8.1、Windows Server 2012 R2 和 Windows 10 1507 版：Windows 市集應用程式支援 Windows 8.1、Windows Server 2012 R2 和 Windows 10 版本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)
程式庫	Kernel32.lib;Windows Phone 8.1 上的 WindowsPhoneCore.lib
Dll	Windows Phone 8.1 上的 KernelBase.dll;Kernel32.dll