Fungsi GetStringScripts (winnls.h)

Artikel
08/27/2023

Menyediakan daftar skrip yang digunakan dalam string Unicode yang ditentukan.

Sintaks

int GetStringScripts(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpString,
  [in]            int     cchString,
  [out, optional] LPWSTR  lpScripts,
  [in]            int     cchScripts
);

Parameter

[in] dwFlags

Bendera yang menentukan opsi untuk pengambilan skrip.

Nilai	Makna
GSS_ALLOW_INHERITED_COMMON	Ambil informasi skrip "Qaii" (DIWARISKAN) dan "Zyyy" (UMUM). Bendera ini tidak memengaruhi pemrosesan karakter yang tidak ditetapkan. Karakter dalam string input ini selalu menyebabkan "Zzzz" (skrip UNASSIGNED) muncul dalam string skrip.

Catatan Secara default, GetStringScripts mengabaikan karakter yang diwariskan atau umum dalam string input yang ditunjukkan oleh lpString. Jika GSS_ALLOW_INHERITED_COMMON tidak diatur, baik "Qaii" maupun "Zyyy" tidak muncul dalam string skrip, bahkan jika string input berisi karakter tersebut. Jika GSS_ALLOW_INHERITED_COMMON diatur, dan jika string input berisi karakter yang diwariskan dan/atau umum, masing-masing "Qaii" dan/atau "Zyyy", muncul dalam string skrip. Lihat bagian Keterangan.

[in] lpString

Arahkan ke string Unicode untuk dianalisis.

[in] cchString

Ukuran, dalam karakter, dari string Unicode yang ditunjukkan oleh lpString. Aplikasi mengatur parameter ini ke -1 jika string Unicode dihentikan null. Jika aplikasi mengatur parameter ini ke 0, fungsi mengambil string Unicode null (L"\0") dalam lpScripts dan mengembalikan 1.

[out, optional] lpScripts

Pointer ke buffer di mana fungsi ini mengambil string yang dihentikan null yang mewakili daftar skrip, menggunakan notasi 4 karakter yang digunakan dalam ISO 15924. Setiap nama skrip terdiri dari empat karakter Latin, dan nama diambil dalam urutan alfabet. Setiap nama, termasuk yang terakhir, diikuti oleh titik koma.

Atau, parameter ini berisi NULL jika cchScripts diatur ke 0. Dalam hal ini, fungsi mengembalikan ukuran yang diperlukan untuk buffer skrip.

[in] cchScripts

Ukuran, dalam karakter, dari buffer skrip yang ditunjukkan oleh lpScripts.

Atau, aplikasi dapat mengatur parameter ini ke 0. Dalam hal ini, fungsi mengambil NULL dalam lpScripts dan mengembalikan ukuran yang diperlukan untuk buffer skrip.

Mengembalikan nilai

Mengembalikan jumlah karakter yang diambil dalam buffer output, termasuk karakter null yang mengakhiri, jika berhasil dan cchScripts diatur ke nilai bukan nol. Fungsi mengembalikan 1 untuk menunjukkan bahwa tidak ada skrip yang ditemukan, misalnya, ketika string input hanya berisi karakter COMMON atau INHERITED dan GSS_ALLOW_INHERITED_COMMON tidak diatur. Mengingat bahwa setiap skrip yang ditemukan menambahkan lima karakter (empat karakter + pemisah), operasi matematika sederhana menyediakan jumlah skrip sebagai (return_code - 1) / 5.

Jika fungsi berhasil dan nilai cchScripts adalah 0, fungsi mengembalikan ukuran yang diperlukan, dalam karakter termasuk karakter null yang mengakhiri, untuk buffer skrip. Jumlah skrip seperti yang dijelaskan di atas.

Fungsi ini mengembalikan 0 jika tidak berhasil. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

ERROR_BADDB. Fungsi tidak dapat mengakses data. Situasi ini biasanya tidak boleh terjadi, dan biasanya menunjukkan penginstalan yang buruk, masalah disk, atau sejenisnya.
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 berguna sebagai bagian dari strategi untuk mengurangi masalah keamanan yang terkait dengan nama domain internasional (IDN).

Penentuan skrip didasarkan pada nilai skrip yang diterbitkan oleh Unicode Consortium di http://www.unicode.org/Public/4.1.0/ucd/Scripts.txt, kecuali bahwa karakter yang tidak ditetapkan memiliki nilai "Zzzz" (UNASSIGNED) alih-alih "Zyyy" (COMMON).

Berikut adalah beberapa contoh perilaku fungsi ini:

Input string		dwFlags	lpScripts	Skrip
Microsoft.com		0	Latn;	Latin
Microsoft.com		GSS_ALLOW_INHERITED_COMMON	Latn; Zyyy;	Latin + Umum
Niño	004E 0069 0241 006F	GSS_ALLOW_INHERITED_COMMON	Latn;	Latin
Niño	Menggunakan HURUF LATIN KECIL N DENGAN TILDE	GSS_ALLOW_INHERITED_COMMON	Latn;	Latin
Niño	004E 0069 006E 0303 006F	GSS_ALLOW_INHERITED_COMMON	Latn; Qaii;	Latin + Diwariskan
Niño	Menggunakan MENGGABUNGKAN TILDE	GSS_ALLOW_INHERITED_COMMON	Latn; Qaii;	Latin + Diwariskan
Spооf	0053 0070 043e 043e 0066	0	Latn; Siri;	Latin + Sirilik
Spооf	Menggunakan CYRILLIC SMALL LETTER O	0	Latn; Siri;	Latin + Sirilik
	U+f000	0	Zzzz;	Tidak ditetapkan
	U+f000	GSS_ALLOW_INHERITED_COMMON	Zzzz;	Tidak ditetapkan

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