Fungsi GetLocaleInfoEx (winnls.h)

Artikel
03/13/2024

Mengambil informasi tentang lokal yang ditentukan berdasarkan nama.

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

Catatan Fungsi ini dapat mengambil data yang berubah di antara rilis, misalnya, karena lokal kustom. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

Sintaks

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

Parameter

[in, optional] lpLocaleName

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

[in] LCType

Informasi lokal untuk diambil. Untuk nilai yang mungkin, lihat bagian "Konstanta yang Digunakan dalam Parameter LCType dari GetLocaleInfo, GetLocaleInfoEx, dan SetLocaleInfo" di Konstanta Informasi Lokal. Perhatikan bahwa hanya satu informasi lokal yang dapat ditentukan per panggilan.

Aplikasi dapat menggunakan operator OR biner untuk menggabungkan LOCALE_RETURN_NUMBER dengan konstanta lain yang diizinkan. Dalam hal ini, fungsi mengambil nilai sebagai angka, bukan string. Buffer yang menerima nilai harus setidaknya panjang nilai DWORD, yaitu 2.

Hati Dimungkinkan juga untuk menggabungkan LOCALE_NOUSEROVERRIDE dengan konstanta lainnya. Namun, penggunaan konstanta ini sangat tidak disarankan. (Bahkan tanpa menggunakan penimpaan pengguna saat ini, data dapat berbeda dari komputer ke komputer, dan lokal kustom dapat mengubah data. Misalnya, nama bulan atau hari pun tunduk pada reformasi ejaan.)

Jika LCType diatur ke LOCALE_IOPTIONALCALENDAR, fungsi hanya mengambil kalender alternatif pertama.

Catatan Untuk mendapatkan semua kalender alternatif, aplikasi harus menggunakan EnumCalendarInfoEx.

Dimulai dengan Windows Vista, aplikasi Anda tidak boleh menggunakan LOCALE_ILANGUAGE dalam parameter LCType untuk menghindari kegagalan atau pengambilan data yang tidak terduga. Sebaliknya, disarankan bagi aplikasi Anda untuk memanggil GetLocaleInfoEx.

[out, optional] lpLCData

Penunjuk ke buffer tempat fungsi ini mengambil informasi lokal yang diminta. Penunjuk ini tidak digunakan jika cchData diatur ke 0.

[in] cchData

Ukuran, dalam karakter, dari buffer data yang ditunjukkan oleh lpLCData. Atau, aplikasi dapat mengatur parameter ini ke 0. Dalam hal ini, fungsi tidak menggunakan parameter lpLCData dan mengembalikan ukuran buffer yang diperlukan, termasuk karakter null yang mengakhiri.

Mengembalikan nilai

Mengembalikan jumlah karakter yang diambil dalam buffer data lokal jika berhasil dan cchData adalah nilai bukan nol. Jika fungsi berhasil, cchData bukan nol, dan LOCALE_RETURN_NUMBER ditentukan, nilai yang dikembalikan adalah ukuran bilangan bulat yang diambil dalam buffer data, yaitu 2. Jika fungsi berhasil dan nilai cchData adalah 0, nilai yang dikembalikan adalah ukuran yang diperlukan, dalam karakter termasuk karakter null, untuk buffer data lokal.

Fungsi mengembalikan 0 jika tidak berhasil. 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 diberikan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Fungsi ini biasanya mengambil informasi dalam format teks. Jika informasi adalah nilai numerik dan nilai LCTypeLOCALE_ILANGUAGE atau LOCALE_IDEFAULTLANGUAGE, fungsi ini mengambil string yang berisi angka heksadesimal. Jika tidak, teks yang diambil untuk informasi numerik adalah angka desimal.

Ada dua pengecualian untuk aturan ini. Pertama, aplikasi dapat mengambil nilai numerik sebagai bilangan bulat dengan menentukan LOCALE_RETURN_NUMBER dalam parameter LCType . Pengecualian kedua adalah bahwa LOCALE_FONTSIGNATURE berperilaku berbeda dari semua konstanta informasi lokal lainnya. Aplikasi harus menyediakan buffer data setidaknya byte sizeof (LOCALESIGNATURE). Pada pengembalian yang berhasil dari fungsi, buffer diisi sebagai struktur LOCALESIGNATURE .

Catatan Bahkan ketika parameter LCType ditentukan sebagai LOCALE_FONTSIGNATURE, cchData dan pengembalian fungsi masih merupakan jumlah karakter. Ketika aplikasi memanggil GetLocaleInfoEx dengan LCType yang ditentukan sebagai LOCALE_FONTSIGNATURE, cchData dapat ditentukan dengan aman sebagai sizeof(LOCALESIGNATURE) / sizeof(WCHAR).

Contoh berikut menangani dengan benar ukuran buffer untuk nilai non-teks:

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

Fungsi ini dapat mengambil data dari lokal kustom. Data tidak dijamin sama dari komputer ke komputer atau antara eksekusi aplikasi. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

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.

Contoh

Contoh yang menunjukkan penggunaan fungsi ini dapat ditemukan di NLS: Sampel API berbasis nama dan NLS: Sampel Mitigasi Nama Domain Internasional (IDN).

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