Fungsi TlsGetValue (processthreadsapi.h)

Artikel
02/02/2024

Mengambil nilai dalam slot penyimpanan lokal utas panggilan (TLS) untuk indeks TLS yang ditentukan. Setiap utas proses memiliki slot sendiri untuk setiap indeks TLS.

Sintaks

LPVOID TlsGetValue(
  [in] DWORD dwTlsIndex
);

Parameter

[in] dwTlsIndex

Indeks TLS yang dialokasikan oleh fungsi TlsAlloc .

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah nilai yang disimpan dalam slot TLS utas panggilan yang terkait dengan indeks yang ditentukan. Jika dwTlsIndex adalah indeks valid yang dialokasikan oleh panggilan yang berhasil ke TlsAlloc, fungsi ini selalu berhasil.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Data yang disimpan dalam slot TLS dapat memiliki nilai 0 karena masih memiliki nilai awal atau karena utas yang disebut fungsi TlsSetValue dengan 0. Oleh karena itu, jika nilai yang dikembalikan adalah 0, Anda harus memeriksa apakah GetLastError mengembalikan ERROR_SUCCESS sebelum menentukan bahwa fungsi telah gagal. Jika GetLastError mengembalikan ERROR_SUCCESS, maka fungsi telah berhasil dan data yang disimpan di slot TLS adalah 0. Jika tidak, fungsi telah gagal.

Fungsi yang mengembalikan indikasi kegagalan memanggil SetLastError saat gagal. Mereka umumnya tidak memanggil SetLastError ketika berhasil. Fungsi TlsGetValue adalah pengecualian untuk aturan umum ini. Fungsi TlsGetValue memanggil SetLastError untuk menghapus kesalahan terakhir utas saat berhasil. Hal ini memungkinkan pemeriksaan pengambilan nilai nol tanpa kesalahan.

Keterangan

Windows Phone 8.1: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8.1 dan yang lebih baru. Saat aplikasi Windows Phone Store memanggil fungsi ini, aplikasi tersebut diganti dengan panggilan sebaris ke FlsGetValue. Lihat FlsGetValue untuk dokumentasi fungsi.

Windows 8.1, Windows Server 2012 R2, dan Windows 10, versi 1507: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan Windows 10, versi 1507. Ketika aplikasi Windows Store memanggil fungsi ini, aplikasi diganti dengan panggilan sebaris ke FlsGetValue. Lihat FlsGetValue untuk dokumentasi fungsi.

Windows 10, versi 1511 dan Windows 10, versi 1607: Fungsi ini didukung penuh untuk aplikasi Platform Windows Universal (UWP), dan tidak lagi diganti dengan panggilan sebaris ke FlsGetValue.

Indeks TLS biasanya dialokasikan oleh fungsi TlsAlloc selama proses atau inisialisasi DLL. Setelah indeks TLS dialokasikan, setiap utas proses dapat menggunakannya untuk mengakses slot TLS-nya sendiri untuk indeks tersebut. Utas menentukan indeks TLS dalam panggilan ke TlsSetValue untuk menyimpan nilai di slotnya. Utas menentukan indeks yang sama dalam panggilan berikutnya ke TlsGetValue untuk mengambil nilai yang disimpan.

TlsGetValue diimplementasikan dengan kecepatan sebagai tujuan utama. Fungsi ini melakukan validasi parameter minimal dan pemeriksaan kesalahan. Secara khusus, ini berhasil jika dwTlsIndex berada dalam rentang 0 hingga (TLS_MINIMUM_AVAILABLE– 1). Terserah programmer untuk memastikan bahwa indeks valid dan bahwa utas memanggil TlsSetValue sebelum memanggil TlsGetValue.

Contoh

Misalnya, lihat Menggunakan Penyimpanan Lokal Utas atau Menggunakan Penyimpanan Lokal Utas di Pustaka Dynamic-Link.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	processthreadsapi.h (termasuk Windows.h di Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka	Kernel32.lib; WindowsPhoneCore.lib di Windows Phone 8.1
DLL	KernelBase.dll pada Windows Phone 8.1; Kernel32.dll