Fungsi GetLocaleInfoA (winnls.h)

Artikel
03/08/2023

Mengambil informasi tentang lokal yang ditentukan oleh pengidentifikasi.

Catatan Untuk alasan interoperabilitas, aplikasi harus lebih memilih fungsi GetLocaleInfoEx ke GetLocaleInfo karena Microsoft bermigrasi ke penggunaan nama lokal alih-alih pengidentifikasi lokal untuk lokal baru. Aplikasi apa pun yang hanya berjalan di Windows Vista dan yang lebih baru harus menggunakan GetLocaleInfoEx.

Catatan Untuk kompatibilitas global, aplikasi harus lebih memilih formulir API Unicode "W" ke formulir "A". GetLocaleInfoA akan membatasi data karakter dan dapat mengakibatkan hasil yang tampak rusak bagi pengguna, terutama dalam aplikasi yang diaktifkan secara global. Untuk API ini, GetLocaleInfoEx lebih disukai karena Unicode dan juga mendukung standar nama lokal modern.

Sintaks

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

Parameter

[in] Locale

Pengidentifikasi lokal untuk mengambil informasi. Anda bisa menggunakan makro MAKELCID untuk membuat pengidentifikasi lokal atau menggunakan salah satu nilai yang telah ditentukan sebelumnya berikut ini.

[in] LCType

Informasi lokal untuk diambil. Untuk definisi terperinci, lihat parameter LCType dari GetLocaleInfoEx.

Catatan Untuk GetLocaleInfo, nilai LOCALE_USE_CP_ACP hanya relevan untuk versi ANSI.

[out, optional] lpLCData

Penunjuk ke buffer tempat fungsi ini mengambil informasi lokal yang diminta. Penunjuk ini tidak digunakan jika cchData diatur ke 0. Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in] cchData

Ukuran, dalam nilai TCHAR, 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.

Nilai kembali

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 untuk versi Unicode fungsi atau 4 untuk versi ANSI. 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

Untuk pengoperasian fungsi ini, lihat Keterangan untuk GetLocaleInfoEx.

Catatan Bahkan ketika parameter LCType ditentukan sebagai LOCALE_FONTSIGNATURE, cchData dan pengembalian fungsi masih dihitung TCHAR. Jumlahnya berbeda untuk versi fungsi ANSI dan Unicode. Ketika aplikasi memanggil versi generik GetLocaleInfo dengan LOCALE_FONTSIGNATURE, cchData dapat ditentukan dengan aman sebagai sizeof(LOCALESIGNATURE) / sizeof(TCHAR).

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

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

String ANSI yang diambil oleh versi ANSI dari fungsi ini diterjemahkan dari Unicode ke ANSI berdasarkan halaman kode ANSI default untuk pengidentifikasi lokal. Namun, jika LOCALE_USE_CP_ACP ditentukan, terjemahan didasarkan pada halaman kode ANSI default sistem.

Ketika versi ANSI dari fungsi ini digunakan dengan pengidentifikasi lokal khusus Unicode, fungsi dapat berhasil karena sistem operasi menggunakan halaman kode sistem. Namun, karakter yang tidak ditentukan di halaman kode sistem muncul dalam string sebagai tanda tanya (?).

Catatan

Header winnls.h mendefinisikan GetLocaleInfo sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


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