Fungsi GetStringTypeExW (stringapiset.h)

Artikel
03/08/2023

Mengambil informasi jenis karakter untuk karakter dalam string sumber yang ditentukan. Untuk setiap karakter dalam string, fungsi mengatur satu atau beberapa bit dalam elemen 16-bit yang sesuai dari array output. Setiap bit mengidentifikasi jenis karakter tertentu, misalnya, huruf, digit, atau tidak keduanya.

Hati Menggunakan fungsi GetStringTypeEx salah dapat membahayakan keamanan aplikasi Anda. Untuk menghindari luapan buffer, aplikasi harus mengatur ukuran buffer output dengan benar. Untuk informasi keamanan selengkapnya, lihat Pertimbangan Keamanan: Antarmuka Pengguna Windows.

Catatan Tidak seperti kerabat dekatnya GetStringTypeA dan GetStringTypeW, fungsi ini menunjukkan perilaku ANSI atau Unicode yang sesuai melalui penggunaan sakelar UNICODE #define. Ini adalah fungsi yang direkomendasikan untuk pengambilan jenis karakter.

Sintaks

BOOL GetStringTypeExW(
  [in]  LCID                          Locale,
  [in]  DWORD                         dwInfoType,
  [in]  _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]  int                           cchSrc,
  [out] LPWORD                        lpCharType
);

Parameter

[in] Locale

Pengidentifikasi lokal yang menentukan lokal. Nilai ini secara unik mendefinisikan halaman kode ANSI. Anda dapat menggunakan makro MAKELCID untuk membuat pengidentifikasi lokal atau menggunakan salah satu nilai yang telah ditentukan sebelumnya berikut ini.

Windows Vista dan yang lebih baru: Pengidentifikasi lokal kustom berikut ini juga didukung.

[in] dwInfoType

Bendera yang menentukan informasi jenis karakter yang akan diambil. Untuk kemungkinan nilai bendera, lihat parameter dwInfoType dari GetStringTypeW. Untuk informasi mendetail tentang bit jenis karakter, lihat Keterangan untuk GetStringTypeW.

[in] lpSrcStr

Arahkan ke string untuk mengambil jenis karakter. String diasumsikan null-dihentikan jika cchSrc diatur ke nilai negatif apa pun.

[in] cchSrc

Ukuran, dalam karakter, dari string yang ditunjukkan oleh lpSrcStr. Ukurannya mengacu pada byte untuk versi ANSI dari fungsi atau karakter lebar untuk versi Unicode. Jika ukuran menyertakan karakter null yang mengakhiri, fungsi mengambil informasi jenis karakter untuk karakter tersebut. Jika aplikasi mengatur ukuran ke bilangan bulat negatif, string sumber diasumsikan dihentikan null dan fungsi menghitung ukuran secara otomatis dengan karakter tambahan untuk penghentian null.

[out] lpCharType

Penunjuk ke array nilai 16-bit. Panjang array ini harus cukup besar untuk menerima satu nilai 16-bit untuk setiap karakter dalam string sumber. Jika cchSrc bukan angka negatif, lpCharType harus menjadi array kata dengan elemen cchSrc . Jika cchSrc diatur ke angka negatif, lpCharType adalah array kata dengan elemen lpSrcStr + 1. Saat fungsi kembali, array ini berisi satu kata yang sesuai dengan setiap karakter dalam string sumber.

Menampilkan nilai

Mengembalikan nilai bukan nol jika berhasil, atau 0 sebaliknya. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

ERROR_INVALID_FLAGS. Nilai yang disediakan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Untuk gambaran umum penggunaan fungsi string, lihat String.

Menggunakan halaman kode ANSI untuk lokal yang disediakan, fungsi ini menerjemahkan string sumber dari ANSI ke Unicode. Kemudian menganalisis setiap karakter Unicode untuk informasi jenis karakter.

Versi ANSI dari fungsi ini mengonversi string sumber ke Unicode dan memanggil fungsi GetStringTypeW yang sesuai. Dengan demikian kata-kata dalam buffer output tidak sesuai dengan string ANSI asli tetapi setara dengan Unicode-nya. Konversi dari ANSI ke Unicode dapat mengakibatkan perubahan panjang string, misalnya, sepasang karakter ANSI dapat memetakan ke satu karakter Unicode. Oleh karena itu, korespondensi antara kata-kata dalam buffer output dan karakter dalam string ANSI asli tidak satu-ke-satu dalam semua kasus, misalnya, string multibyte. Dengan demikian, versi ANSI dari fungsi ini terbatas untuk string multi-karakter. Versi Unicode dari fungsi direkomendasikan sebagai gantinya.

Fungsi ini menghindari batasan yang disebabkan oleh perbedaan parameter antara GetStringTypeA dan GetStringTypeW. Karena perbedaan parameter, aplikasi tidak dapat secara otomatis memanggil versi ANSI atau Unicode yang tepat dari fungsi GetStringType* melalui penggunaan sakelar UNICODE #define. Di sisi lain, GetStringTypeEx, berperilaku benar sehubungan dengan sakelar itu. Dengan demikian, ini adalah fungsi yang direkomendasikan.

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 (?).

Nilai parameter lpSrcStr dan lpCharType tidak boleh sama. Jika sama, fungsi gagal dengan ERROR_INVALID_PARAMETER.

Parameter Lokal hanya digunakan untuk melakukan konversi string ke Unicode. Ini tidak ada hubungannya dengan nilai CTYPE* yang disediakan oleh aplikasi. Nilai-nilai ini hanya ditentukan oleh titik kode Unicode, dan tidak bervariasi berdasarkan lokal. Misalnya, huruf Yunani ditentukan sebagai C1_ALPHA untuk nilai Lokal apa pun.

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	stringapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

GetStringTypeW

Dukungan Bahasa Nasional

Fungsi Dukungan Bahasa Nasional

Bagikan melalui