Функция TlsGetValue (processthreadsapi.h)

Статья
03/01/2024

Извлекает значение в слоте локального хранилища потока (TLS) вызывающего потока для указанного индекса TLS. Каждый поток процесса имеет собственную ячейку для каждого индекса TLS.

Синтаксис

LPVOID TlsGetValue(
  [in] DWORD dwTlsIndex
);

Параметры

[in] dwTlsIndex

Индекс TLS, выделенный функцией TlsAlloc .

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение — это значение, хранящееся в слоте TLS вызывающего потока, связанном с указанным индексом. Если dwTlsIndex является допустимым индексом, выделенным при успешном вызове TlsAlloc, эта функция всегда выполняется успешно.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Данные, хранящиеся в слоте TLS, могут иметь значение 0, так как они по-прежнему имеют начальное значение или поток, называемый функцией TlsSetValue с 0. Поэтому, если возвращаемое значение равно 0, перед определением сбоя функции необходимо проверка, возвращает ли GetLastErrorERROR_SUCCESS. Если GetLastError возвращает ERROR_SUCCESS, то функция выполнена успешно и данные, хранящиеся в слоте TLS, имеют значение 0. В противном случае функция завершилась сбоем.

Функции, возвращающие признаки сбоя, вызывают SetLastError при сбое. Как правило, при успешном выполнении они не вызывают SetLastError . Функция TlsGetValue является исключением из этого общего правила. Функция TlsGetValue вызывает SetLastError , чтобы удалить последнюю ошибку потока при успешном выполнении. Это позволяет проверять получение нулевых значений без ошибок.

Windows Phone 8.1. Эта функция поддерживается для приложений магазина Windows Phone в Windows Phone 8.1 и более поздних версий. Когда приложение Windows Phone Store вызывает эту функцию, она заменяется встроенным вызовом 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 для этого индекса. Поток задает индекс TLS в вызове TlsSetValue для хранения значения в своем слоте. Поток задает тот же индекс в последующем вызове TlsGetValue для получения сохраненного значения.

TlsGetValue был реализован со скоростью в качестве основной цели. Функция выполняет минимальную проверку параметров и проверку ошибок. В частности, он завершается успешно, если dwTlsIndex находится в диапазоне от 0 до (TLS_MINIMUM_AVAILABLE–1). Программист может убедиться, что индекс действителен и что поток вызывает TlsSetValue перед вызовом TlsGetValue.

Примеры

Пример см. в разделе Использование локального хранилища потока или Использование локального хранилища потока в библиотеке Dynamic-Link.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	processthreadsapi.h (включая Windows.h в Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Библиотека	Kernel32.lib; WindowsPhoneCore.lib на Windows Phone 8.1
DLL	KernelBase.dll Windows Phone 8.1; Kernel32.dll