Fungsi DownlevelGetStringScripts

Artikel
12/21/2023

Menyediakan daftar skrip yang digunakan dalam string Unicode yang ditentukan.

Catatan

Fungsi ini hanya digunakan oleh aplikasi yang berjalan pada sistem operasi Pra-Windows Vista. Penggunaannya memerlukan paket unduhan. Aplikasi yang hanya berjalan di Windows Vista dan yang lebih baru harus memanggil GetStringScripts.

Sintaks

int DownlevelGetStringScripts(
  _In_  DWORD   dwFlags,
  _In_  LPCWSTR lpString,
  _In_  int     cchString,
  _Out_ LPWSTR  lpScripts,
  _In_  int     cchScripts
);

Parameter

dwFlags [in]

Bendera yang menentukan opsi untuk pengambilan skrip.

Value	Makna
GSS_ALLOW_INHERITED_COMMON	Ambil informasi skrip "Qaii" (DIWARISKAN) dan "Zyyy" (COMMON). Nilai 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, fungsi ini mengabaikan karakter yang diwariskan atau umum dalam string Unicode input. Jika GSS_ALLOW_INHERITED_COMMON tidak diatur, "Qaii" atau "Zyyy" tidak akan 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, "Qaii" dan/atau "Zyyy" muncul dalam string skrip. Lihat bagian Keterangan.

lpString [in]

Arahkan ke string Unicode untuk dianalisis.

cchString [in]

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

lpScripts [out]

Pointer ke buffer di mana fungsi ini mengambil string null-terminated 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 dapat berisi NULL jika cchScript diatur ke 0. Dalam hal ini, fungsi mengembalikan ukuran yang diperlukan untuk buffer skrip.

cchScripts [in]

Ukuran, dalam karakter, untuk 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.

Nilai hasil

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, nilai yang dikembalikan adalah ukuran yang diperlukan, dalam karakter termasuk karakter null yang mengakhiri, untuk buffer skrip. Jumlah skrip seperti yang dijelaskan di atas.

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_BADDB. Fungsi tidak dapat mengakses data. Situasi ini biasanya tidak boleh terjadi, dan biasanya menunjukkan instalasi 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 https://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

Latn;

Latin

Microsoft.com

GSS_ALLOW_INHERITED_COMMON

Latn; Zyyy;

Latin + Umum

${ROWSPAN2}$Ni ño${REMOVE}$

004E 0069 0241 006F

${ROWSPAN2}$GSS_ALLOW_INHERITED_COMMON${REMOVE}$

${ROWSPAN2}$Latn;${REMOVE}$

${ROWSPAN2}$Latin${REMOVE}$

Menggunakan HURUF LATIN KECIL N DENGAN TILDE

${ROWSPAN2}$Ni ño${REMOVE}$

004E 0069 006E 0303 006F

${ROWSPAN2}$GSS_ALLOW_INHERITED_COMMON${REMOVE}$

${ROWSPAN2}$Latn; Qaii;${REMOVE}$

${ROWSPAN2}$Latin + Inherited${REMOVE}$

Menggunakan MENGGABUNGKAN TILDE

${ROWSPAN2}$Sp ооf${REMOVE}$

0053 0070 043e 043e 0066

${ROWSPAN2}$0${REMOVE}$

${ROWSPAN2}$Latn; Cyrl;${REMOVE}$

${ROWSPAN2}$Latin + Sirilik${REMOVE}$

Menggunakan CYRILLIC SMALL LETTER O



U+f000

Zzzz;

Tidak ditetapkan



U+f000

GSS_ALLOW_INHERITED_COMMON

Zzzz;

Tidak ditetapkan

File header dan DLL yang diperlukan adalah bagian dari unduhan "API Mitigasi Nama Domain Internasional Microsoft (IDN) yang tersedia dari archive.org.

Persyaratan

Persyaratan	Value
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Redistribusi	API Mitigasi Nama Domain Internasional Microsoft (IDN) pada Windows XP (SP2 atau yang lebih baru), Windows Server 2003 (SP1 atau yang lebih baru), atau Windows Vista
Header	Idndl.h
DLL	Idndl.dll