Fungsi UrlCanonicalizeW (shlwapi.h)

Artikel
08/26/2023

Mengonversi string URL menjadi bentuk kanonis.

Sintaks

LWSTDAPI UrlCanonicalizeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszCanonicalized,
  [in, out] DWORD  *pcchCanonicalized,
            DWORD  dwFlags
);

Parameter

[in] pszUrl

Jenis: PCTSTR

Penunjuk ke string yang dihentikan null dengan panjang maksimum INTERNET_MAX_URL_LENGTH yang berisi string URL. Jika string tidak merujuk ke file, string harus menyertakan skema yang valid seperti "http://".

[out] pszCanonicalized

Jenis: PTSTR

Penunjuk ke buffer yang, ketika fungsi ini berhasil dikembalikan, menerima URL yang dikonversi sebagai string yang dihentikan null.

[in, out] pcchCanonicalized

Jenis: DWORD*

Penunjuk ke nilai yang, pada entri, diatur ke jumlah karakter dalam buffer pszCanonicalized .

dwFlags

Jenis: DWORD

Bendera yang menentukan bagaimana URL dikonversi ke bentuk kanonis. Bendera berikut dapat digabungkan.

URL_UNESCAPE (0x10000000)

Batalkan escape urutan escape apa pun yang dimuat URL, dengan dua pengecualian. Urutan escape untuk "?" dan "#" tidak lolos. Jika salah satu bendera URL_ESCAPE_XXX juga diatur, kedua URL pertama kali tidak lolos, lalu digabungkan, lalu lolos.

URL_ESCAPE_UNSAFE (0x20000000)

Ganti karakter yang tidak aman dengan urutan escape-nya. Karakter yang tidak aman adalah karakter yang mungkin diubah selama transportasi melalui Internet, dan menyertakan karakter (<, >, ", #, {, }, |, , ^, [, ], dan '). Bendera ini berlaku untuk semua URL, termasuk URL buram.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Gabungkan URL dengan protokol pluggable yang ditentukan klien, sesuai dengan spesifikasi W3C. Bendera ini tidak berlaku untuk protokol standar seperti ftp, http, gopher, dan sebagainya. Jika bendera ini diatur, UrlCombine tidak menyederhanakan URL, jadi tidak perlu juga mengatur URL_DONT_SIMPLIFY.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Ganti hanya spasi dengan urutan escape. Bendera ini lebih diutamakan daripada URL_ESCAPE_UNSAFE, tetapi tidak berlaku untuk URL buram.

URL_DONT_SIMPLIFY (0x08000000)

Perlakukan "/./" dan "/.. /" dalam string URL sebagai karakter harfiah, tidak sesingkat navigasi. Lihat Keterangan untuk diskusi lebih lanjut.

URL_NO_META (0x08000000)

Didefinisikan sama dengan URL_DONT_SIMPLIFY.

URL_ESCAPE_PERCENT (0x00001000)

Konversikan kemunculan "%" ke urutan escape-nya.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 dan yang lebih baru. Pengodean persen semua karakter non-ASCII sebagai setara UTF-8 mereka.

Mengembalikan nilai

Jenis: HRESULT

Jika fungsi ini berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.

Keterangan

Fungsi ini melakukan tugas-tugas seperti mengganti karakter yang tidak aman dengan urutan escape-nya dan menciutkan urutan seperti ".....".

Jika string URL berisi "/.. /" atau "/./", UrlCanonicalize memperlakukan karakter sebagai menunjukkan navigasi dalam hierarki URL. Fungsi ini menyederhanakan URL sebelum menggabungkannya. Misalnya "/hello/cruel/.. /world" disederhanakan ke "/hello/world". Pengecualian untuk perilaku default ini terjadi dalam kasus ini:

Jika bendera URL_DONT_SIMPLIFY diatur dalam dwFlags, fungsi tidak menyederhanakan URL. Dalam hal ini, "/hello/cruel/.. Dunia dibiarkan apa adanya.
Jika "/.. /" atau "/./" adalah segmen pertama di jalur (misalnya, "http://domain/../path1/path2/file.htm"), UrlCanonicalize menghasilkan jalur persis seperti input.

Catatan

Header shlwapi.h mendefinisikan UrlCanonicalize sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor 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

Menangani Pencari Sumber Daya Seragam

Bagikan melalui