Fungsi UrlEscapeW (shlwapi.h)
Mengonversi karakter atau pasangan pengganti dalam URL yang mungkin diubah selama transportasi di internet (karakter "tidak aman") ke dalam urutan escape yang sesuai. Pasangan pengganti adalah karakter antara U+10000 hingga U+10FFFF (dalam UTF-32) atau antara DC00 hingga DFFF (dalam UTF-16).
Sintaks
LWSTDAPI UrlEscapeW(
[in] PCWSTR pszUrl,
[out] PWSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
Parameter
[in] pszUrl
Jenis: PCTSTR
String panjang maksimum yang dihentikan null INTERNET_MAX_URL_LENGTH yang berisi URL lengkap atau parsial, yang sesuai untuk nilai dalam dwFlags.
[out] pszEscaped
Jenis: PTSTR
Buffer yang menerima string yang dikonversi, dengan karakter yang tidak aman dikonversi ke urutan escape mereka.
[in, out] pcchEscaped
Jenis: DWORD*
Penunjuk ke nilai DWORD yang, pada entri, berisi jumlah karakter dalam buffer pszEscaped . Sebelum memanggil UrlEscape, aplikasi panggilan harus mengatur nilai yang direferensikan oleh pcchEscaped ke ukuran buffer. Ketika fungsi ini berhasil dikembalikan, nilai menerima jumlah karakter yang ditulis ke buffer, tidak termasuk karakter NULL yang mengakhiri.
Jika kode kesalahan E_POINTER dikembalikan, buffer terlalu kecil untuk menahan hasilnya, dan nilai yang direferensikan oleh pcchEscaped diatur ke jumlah karakter yang diperlukan dalam buffer. Jika ada kesalahan lain yang dikembalikan, nilai yang direferensikan oleh pcchEscaped tidak terdefinisi.
dwFlags
Jenis: DWORD
Bendera yang menunjukkan bagian URL mana yang disediakan dalam pszURL dan karakter mana dalam string tersebut yang harus dikonversi ke urutan escape mereka. Bendera berikut ditentukan.
URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
Hanya digunakan bersama dengan URL_ESCAPE_SPACES_ONLY untuk mencegah konversi karakter dalam kueri (bagian URL mengikuti karakter # atau ? pertama yang ditemui dalam string). Bendera ini tidak boleh digunakan sendiri, atau dikombinasikan dengan URL_ESCAPE_SEGMENT_ONLY.
URL_BROWSER_MODE
Didefinisikan sama dengan URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Konversi hanya karakter spasi ke urutan escape-nya, termasuk karakter spasi tersebut di bagian kueri URL. Karakter tidak aman lainnya tidak dikonversi ke urutan escape-nya. Bendera ini mengasumsikan bahwa pszURL tidak berisi URL lengkap. Ini hanya mengharapkan bagian yang mengikuti spesifikasi server.
Gabungkan bendera ini dengan URL_DONT_ESCAPE_EXTRA_INFO untuk mencegah konversi karakter spasi di bagian kueri URL.
Bendera ini tidak dapat digabungkan dengan URL_ESCAPE_PERCENT atau URL_ESCAPE_SEGMENT_ONLY.
URL_ESCAPE_PERCENT (0x00001000)
Konversikan karakter % apa pun yang ditemukan di bagian segmen URL (bagian tersebut berada di antara spesifikasi server dan karakter # atau ? pertama). Secara default, karakter % tidak dikonversi ke urutan escape-nya. Karakter lain yang tidak aman di segmen juga dikonversi secara normal.
Menggabungkan bendera ini dengan URL_ESCAPE_SEGMENT_ONLY menyertakan karakter % tersebut dalam bagian kueri URL. Namun, karena bendera URL_ESCAPE_SEGMENT_ONLY menyebabkan seluruh string dianggap sebagai segmen, # atau ? karakter juga dikonversi.
Bendera ini tidak dapat digabungkan dengan URL_ESCAPE_SPACES_ONLY.
URL_ESCAPE_SEGMENT_ONLY (0x00002000)
Menunjukkan bahwa pszURL hanya berisi bagian URL yang mengikuti komponen server tetapi sebelum kueri. Semua karakter yang tidak aman dalam string dikonversi. Jika URL lengkap disediakan saat bendera ini diatur, semua karakter yang tidak aman di seluruh string akan dikonversi, termasuk # dan ? Karakter.
Gabungkan bendera ini dengan URL_ESCAPE_PERCENT untuk menyertakan karakter tersebut dalam konversi.
Bendera ini tidak dapat digabungkan dengan URL_ESCAPE_SPACES_ONLY atau URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 dan yang lebih baru. Persen-encode semua karakter non-ASCII sebagai setara UTF-8 mereka.
URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
Windows 8 dan yang lebih baru. Persen-enkode semua karakter ASCII di luar set yang tidak dilayani dari URI RFC 3986 (a-zA-Z0-9-.~_).
Nilai kembali
Jenis: HRESULT
Mengembalikan S_OK jika berhasil. Jika buffer pcchEscaped terlalu kecil untuk memuat hasilnya, E_POINTER dikembalikan, dan nilai yang ditunjukkan oleh pcchEscaped diatur ke ukuran buffer yang diperlukan. Jika tidak, nilai kesalahan standar dikembalikan.
Keterangan
Untuk keperluan dokumen ini, URL umum dibagi menjadi tiga bagian: server, segmen, dan kueri. Contohnya:
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
Bagian server adalah "http://microsoft.com/". Garis miring berikutnya dianggap sebagai bagian dari bagian server.
Bagian segmen adalah bagian mana pun dari jalur yang ditemukan mengikuti bagian server, tetapi sebelum # pertama atau ? karakter, dalam hal ini hanya "test.asp".
Bagian kueri adalah sisa jalur dari # pertama atau ? karakter (inklusif) sampai akhir. Dalam contoh, itu adalah "?url=/example/abc.asp?frame=true#fragment".
Karakter yang tidak aman adalah karakter yang mungkin diubah selama transportasi melalui Internet. Fungsi ini mengonversi karakter yang tidak aman menjadi urutan escape "%xy" yang setara. Tabel berikut ini memperlihatkan karakter yang tidak aman dan urutan escape-nya.
| Karakter | Urutan Escape |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
Penggunaan bendera URL_ESCAPE_SEGMENT_ONLY juga menyebabkan konversi # (%23), ? Karakter (%3F), dan / (%2F).
Secara default, UrlEscape mengabaikan teks apa pun setelah # atau ? Karakter. Bendera URL_ESCAPE_SEGMENT_ONLY mengambil alih perilaku ini dengan menganggap seluruh string sebagai segmen. Bendera URL_ESCAPE_SPACES_ONLY mengambil alih perilaku ini, tetapi hanya untuk karakter spasi.
Contoh
Contoh berikut menunjukkan efek berbagai bendera pada URL. CONTOH URL tidak valid tetapi dilebih-lebihkan untuk tujuan demonstrasi.
// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query
// components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result = test%2Ft%e%3Cs%20t.asp
Catatan
Header shlwapi.h mendefinisikan UrlEscape sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional, Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | shlwapi.h |
| Pustaka | Shlwapi.lib |
| DLL | Shlwapi.dll (versi 5.0 atau yang lebih baru) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk