Fungsi GetNLSVersionEx (winnls.h)

Artikel
08/27/2023

Mengambil informasi tentang versi kemampuan NLS yang ditentukan saat ini untuk lokal yang ditentukan berdasarkan nama.

Catatan Aplikasi harus memanggil fungsi ini sebagai preferensi ke GetNLSVersion jika dirancang untuk berjalan hanya di Windows Vista dan yang lebih baru.

Sintaks

BOOL GetNLSVersionEx(
  [in]           NLS_FUNCTION       function,
  [in, optional] LPCWSTR            lpLocaleName,
  [in, out]      LPNLSVERSIONINFOEX lpVersionInformation
);

Parameter

[in] function

Kemampuan NLS untuk mengkueri. Nilai ini harus COMPARE_STRING. Lihat enumerasi SYSNLS_FUNCTION .

[in, optional] lpLocaleName

Arahkan ke nama lokal, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini.

[in, out] lpVersionInformation

Arahkan ke struktur NLSVERSIONINFOEX . Aplikasi harus menginisialisasi anggota dwNLSVersionInfoSize ke sizeof(NLSVERSIONINFOEX).

Catatan Pada Windows Vista dan yang lebih baru, fungsi ini dapat memberikan informasi versi secara alternatif dalam struktur NLSVERSIONINFO .

Mengembalikan nilai

Mengembalikan TRUE jika dan hanya jika aplikasi telah menyediakan nilai yang valid dalam lpVersionInformation, atau FALSE sebaliknya. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
ERROR_INVALID_FLAGS. Nilai yang disediakan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Fungsi ini memungkinkan aplikasi seperti Direktori Aktif untuk menentukan apakah perubahan NLS memengaruhi lokal yang digunakan untuk tabel indeks tertentu. Jika tidak, tidak perlu mengindeks ulang tabel. Untuk informasi selengkapnya, lihat Menangani Pengurutan di Aplikasi Anda. Secara khusus, untuk mengetahui apakah versi pengurutan berubah dan Anda perlu mengindeks ulang:

Gunakan GetNLSVersionEx untuk mengambil struktur NLSVERSIONINFOEX saat melakukan pengindeksan asli data Anda.
Simpan properti berikut dengan indeks Anda untuk mengidentifikasi versi:
- NLSVERSIONINFOEX.dwNLSVersion. Ini menentukan versi tabel pengurutan yang Anda gunakan.
- NLSVERSIONINFOEX.dwEffectiveId. Ini menentukan lokal efektif dari jenis Anda. Lokal kustom akan menunjuk ke sortir lokal dalam kotak.
- NLSVERSIONINFOEX.guidCustomVersion. Ini adalah GUID yang menentukan pengurutan kustom tertentu untuk lokal kustom yang memilikinya.
Saat menggunakan indeks, gunakan GetNLSVersionEx untuk menemukan versi data Anda.
Jika salah satu dari tiga properti telah berubah, pengurutan data yang Anda gunakan dapat mengembalikan hasil yang berbeda dan pengindeksan apa pun yang mungkin gagal Anda temukan rekamannya.
Jika Anda tahu bahwa data Anda tidak berisi titik kode Unicode yang tidak valid (artinya, semua string Anda meneruskan panggilan ke IsNLSDefinedString) maka Anda dapat menganggapnya sama jika hanya byte rendah dwNLSVersion yang berubah (versi minor yang dijelaskan di atas).

Ini dibahas secara lebih rinci dalam entri blog "Cara mengetahui apakah versi kolase berubah" (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).

Fungsi ini mendukung lokal kustom. Jika lpLocaleName menentukan lokal tambahan, data yang diambil adalah data yang benar untuk urutan pengurutan yang terkait dengan lokal tambahan tersebut.

Dimulai di Windows 8: Jika aplikasi Anda meneruskan tag bahasa ke fungsi ini dari namespace Windows.Globalization, aplikasi harus terlebih dahulu mengonversi tag dengan memanggil ResolveLocaleName.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winnls.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll