Fungsi IdnToAscii (winnls.h)

Artikel
08/27/2023

Mengonversi nama domain internasional (IDN) atau label internasional lainnya menjadi representasi Unicode (karakter lebar) dari string ASCII yang mewakili nama dalam sintaks pengodean transfer Punycode.

Hati Fungsi ini mengimplementasikan algoritma standar RFC 3490: Internationalizing Domain Names in Applications (IDNA) untuk mengonversi IDN ke Punycode. Standar memperkenalkan beberapa masalah keamanan. Salah satu masalahnya adalah bahwa glyph yang mewakili karakter tertentu dari skrip yang berbeda mungkin tampak serupa atau bahkan identik. Misalnya, dalam banyak font, huruf kecil Sirilik A ("а") tidak dapat dibedakan dari huruf kecil Latin A ("a"). Tidak ada cara untuk memberi tahu secara visual bahwa "example.com" dan "exа mple.com" adalah dua nama domain yang berbeda, satu dengan huruf kecil Latin A dalam nama, yang lain dengan huruf kecil Sirilik A. Untuk informasi selengkapnya tentang masalah keamanan terkait IDN, lihat Menangani Nama Domain Internasional (IDN).

Sintaks

int IdnToAscii(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpASCIICharStr,
  [in]            int     cchASCIIChar
);

Parameter

[in] dwFlags

Bendera yang menentukan opsi konversi. Tabel berikut ini mencantumkan nilai yang mungkin.

Nilai	Makna
IDN_ALLOW_UNASSIGNED	Catatan Aplikasi dapat mengatur nilai ini jika hanya menggunakan string kueri untuk pencarian normal, seperti dalam operasi perbandingan. Namun, aplikasi tidak boleh menetapkan nilai ini untuk string tersimpan, yang merupakan string yang disiapkan untuk penyimpanan. Izinkan titik kode yang tidak ditetapkan disertakan dalam string input. Defaultnya adalah tidak mengizinkan titik kode yang tidak ditetapkan, dan gagal dengan kode kesalahan ERROR_INVALID_NAME yang diperluas. Bendera ini memungkinkan fungsi untuk memproses karakter yang saat ini tidak legal dalam IDN, tetapi mungkin legal dalam versi standar IDNA yang lebih baru. Jika aplikasi Anda mengodekan titik kode yang tidak ditetapkan sebagai Punycode, nama domain yang dihasilkan harus ilegal. Keamanan dapat disusupi jika versi IDNA yang lebih baru membuat nama-nama ini legal atau jika aplikasi memfilter karakter ilegal untuk mencoba membuat nama domain hukum. Untuk informasi selengkapnya, lihat Menangani Nama Domain Internasional (IDN).
IDN_USE_STD3_ASCII_RULES	Filter karakter ASCII yang tidak diperbolehkan dalam nama STD3. Satu-satunya karakter ASCII yang diizinkan dalam string Unicode input adalah huruf, digit, dan tanda hubung minus. String tidak dapat dimulai atau diakhir dengan tanda hubung-minus. Fungsi gagal jika string Unicode input berisi karakter ASCII, seperti "[", "]", atau "/", yang tidak dapat terjadi dalam nama domain. Catatan Beberapa jaringan lokal dapat memperbolehkan beberapa karakter ini dalam nama komputer. Fungsi gagal jika string Unicode input berisi karakter kontrol (U+0001 hingga U+0020) atau karakter "hapus" (U+007F). Dalam kedua kasus, bendera ini tidak berpengaruh pada karakter non-ASCII yang diizinkan dalam string Unicode.
IDN_EMAIL_ADDRESS	Dimulai dengan Windows 8: Aktifkan fallback algoritmik EAI untuk bagian lokal alamat email (seperti <local>@microsoft.com). Defaultnya adalah agar fungsi ini gagal ketika alamat email memiliki alamat atau sintaksis yang tidak valid. Aplikasi dapat mengatur bendera ini untuk mengaktifkan Email Address Internationalization (EAI) untuk mengembalikan alamat fallback yang dapat ditemukan, jika memungkinkan. Untuk informasi selengkapnya, lihat Piagam IETF Email Address Internationalization (eai).
IDN_RAW_PUNYCODE	Dimulai dengan Windows 8: Nonaktifkan validasi dan pemetaan Punycode.

[in] lpUnicodeCharStr

Arahkan ke string Unicode yang mewakili IDN atau label internasional lainnya.

[in] cchUnicodeChar

Jumlah karakter dalam string Unicode input yang ditunjukkan oleh lpUnicodeCharStr.

[out, optional] lpASCIICharStr

Penunjuk ke buffer yang menerima string Unicode yang hanya terdiri dari karakter dalam set karakter ASCII. Saat dikembalikan dari fungsi ini, buffer berisi string ASCII yang setara dengan string yang disediakan dalam lpUnicodeCharStr di bawah Punycode. Atau, fungsi dapat mengambil NULL untuk parameter ini, jika cchASCIIChar diatur ke 0. Dalam hal ini, fungsi mengembalikan ukuran yang diperlukan untuk buffer ini.

[in] cchASCIIChar

Ukuran buffer yang ditunjukkan oleh lpASCIICharStr. Aplikasi dapat mengatur parameter ke 0 untuk mengambil NULL di lpASCIICharStr.

Mengembalikan nilai

Mengembalikan jumlah karakter yang diambil dalam lpASCIICharStr jika berhasil. String yang diambil dihentikan null hanya jika string Unicode input dihentikan null.

Jika fungsi berhasil dan nilai cchASCIIChar adalah 0, fungsi mengembalikan ukuran yang diperlukan, dalam karakter termasuk karakter null yang mengakhiri jika merupakan bagian dari buffer input.

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 disediakan untuk bendera tidak valid.
ERROR_INVALID_NAME. Nama yang tidak valid diberikan ke fungsi. Perhatikan bahwa kode kesalahan ini menangkap semua kesalahan sintaks.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.
ERROR_NO_UNICODE_TRANSLATION. Unicode tidak valid ditemukan dalam string.

Keterangan

Fungsi ini tidak menghentikan string output null jika panjang string input ditentukan secara eksplisit tanpa mengakhiri karakter null. Untuk menghentikan string output null untuk fungsi ini, aplikasi harus menyediakan -1 untuk parameter cchUnicodeChar atau secara eksplisit menghitung karakter null yang mengakhiri untuk string input.

Perhatikan bahwa fungsi selalu gagal jika string input berisi karakter kontrol (U+0001 hingga U+0020) atau karakter "hapus" (U+007F). Karena karakter U+0000 hanya dapat muncul sebagai karakter null yang mengakhiri, fungsi selalu gagal jika U+0000 muncul di tempat lain dalam string input.

Windows XP, Windows Server 2003:

Tidak lagi didukung.

File header dan DLL yang diperlukan adalah bagian dari API Mitigasi Nama Domain Internasional Microsoft (IDN), yang tidak lagi tersedia untuk diunduh.

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	Normaliz.lib
DLL	Normaliz.dll
Redistribusi	API Mitigasi Nama Domain Internasional Microsoft (IDN) diWindows XP dengan SP2 dan yang lebih baru, Windows Server 2003 dengan SP1