Fungsi IdnToAscii (winnls.h)
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.
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 |
|---|---|
|
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.
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). |
|
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. |
|
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). |
|
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 |