Fungsi PathCchCanonicalizeEx (pathcch.h)

Artikel
08/25/2023

Menyederhanakan jalur dengan menghapus elemen navigasi seperti "." dan ".." untuk menghasilkan jalur langsung yang terbentuk dengan baik.

Fungsi ini berbeda dari PathCchCanonicalize karena memungkinkan jalur akhir yang lebih lama untuk dibangun.

Fungsi ini berbeda dari PathAllocCanonicalize karena pemanggil harus mendeklarasikan ukuran string yang dikembalikan, yang disimpan pada tumpukan.

Fungsi ini berbeda dari PathCanonicalize karena menerima jalur dengan awalan "\", "\?" dan "\?\UNC".

Catatan Fungsi ini, PathCchCanonicalize, atau PathAllocCanonicalize harus digunakan sebagai pengganti PathCanonicalize untuk mencegah kemungkinan buffer diserbu.

Sintaks

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

Parameter

[out] pszPathOut

Penunjuk ke buffer yang, ketika fungsi ini berhasil dikembalikan, menerima string jalur yang diedit.

[in] cchPathOut

Ukuran buffer yang diacu oleh pszPathOut, dalam karakter.

[in] pszPathIn

Penunjuk ke string jalur asli. Jika nilai ini ADALAH NULL, menunjuk ke string kosong, atau menghasilkan string kosong setelah elemen "." dan ".." dihapus, satu garis miring terbalik disalin ke buffer yang diacu oleh pszPathOut.

[in] dwFlags

Satu atau beberapa bendera berikut:

Nilai	Makna
PATHCCH_NONE 0x0000000	Jangan izinkan pembangunan jalur \\?\ (yaitu, jalur panjang) lebih panjang dari MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Izinkan pembangunan jalur \\?\ lebih panjang dari MAX_PATH . Perhatikan bahwa cchPathOut harus lebih besar dari MAX_PATH . Jika tidak, bendera ini diabaikan.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Memaksa API untuk memperlakukan pemanggil selama jalur panjang diaktifkan, terlepas dari status nama panjang proses yang diaktifkan. Opsi ini hanya dapat digunakan ketika PATHCCH_ALLOW_LONG_PATHS ditentukan, dan tidak dapat digunakan dengan PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS. Catatan Nilai ini tersedia mulai dari Windows 10 versi 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 0x00000004	Memaksa API untuk memperlakukan pemanggil selama jalur panjang dinonaktifkan, terlepas dari status yang diaktifkan nama panjang proses. Opsi ini hanya dapat digunakan ketika PATHCCH_ALLOW_LONG_PATHS ditentukan, dan tidak dapat digunakan dengan PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS. Catatan Nilai ini tersedia mulai dari Windows 10 versi 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 0x00000008	Menonaktifkan normalisasi segmen jalur yang mencakup penghapusan titik dan spasi berikutnya. Ini memungkinkan akses ke jalur yang akan diblokir oleh normalisasi jalur win32. Catatan Nilai ini tersedia mulai dari Windows 10 versi 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH 0x00000010	Mengonversi jalur input ke dalam formulir jalur perangkat DOS panjang yang diperluas (dengan awalan \\?\) jika belum dalam formulir tersebut. Ini memungkinkan akses ke jalur yang sebaliknya tidak dapat diatasi karena aturan normalisasi Win32 (yang dapat menghapus titik dan spasi berikutnya) dan batasan panjang jalur. Opsi ini menyiratkan perilaku PATHCCH_DO_NOT_NORMALIZE_SEGMENTS yang sama. Catatan Nilai ini tersedia mulai dari Windows 10 versi 1703.
PATHCCH_ENSURE_TRAILING_SLASH 0x00000020	Saat menggabungkan atau menormalkan jalur, pastikan ada garis miring terbelakang di belakang. Catatan Nilai ini tersedia mulai dari Windows 10 versi 1703.

Mengembalikan nilai

Jika fungsi ini berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode HRESULT akan dikembalikan, termasuk tetapi tidak terbatas pada yang berikut ini.

Menampilkan kode	Deskripsi
E_INVALIDARG	Nilai cchPathOut lebih besar dari PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG	Segmen jalur memiliki lebih dari PATHCCH_MAX_CCH karakter, atau, jika bendera PATHCCH_ALLOW_LONG_PATHS tidak diatur, melebihi batas panjang segmen jalur standar 256 karakter.
E_OUTOFMEMORY	Fungsi tidak dapat mengalokasikan buffer dengan ukuran yang diperlukan.

Keterangan

Fungsi ini merespons string "." dan ".." yang disematkan di jalur. String ".." menunjukkan untuk menghapus segmen jalur sebelumnya segera. String "." menunjukkan untuk melewati segmen jalur berikutnya. Perhatikan bahwa segmen akar jalur tidak dapat dihapus. Jika ada lebih banyak string ".." daripada segmen jalur, fungsi mengembalikan S_OK dan buffer yang diacu oleh pszPathOut berisi garis miring terbalik tunggal, "\".

Semua titik berikutnya dihapus dari jalur, kecuali jika didahului oleh karakter kartubebas "". Dalam hal ini, satu periode dipertahankan setelah karakter '', tetapi semua periode berikutnya dihapus.

Jika jalur yang dihasilkan adalah drive akar ("x:"), garis miring terbelakang ditambahkan ("x:\").

Fungsi ini tidak mengonversi garis miring ke depan (/) menjadi garis miring belakang (\). Dengan input yang tidak tepercaya, fungsi ini dengan sendirinya, tidak dapat digunakan untuk mengonversi jalur menjadi formulir yang dapat dibandingkan dengan jalur lain untuk sub-jalur atau identitas. Penelepon yang membutuhkan kemampuan tersebut harus mengonversi maju ke garis miring kembali sebelum menggunakan fungsi ini.

Contoh berikut menunjukkan efek string ini.

String asli	String kanonis
C:\name_1\.\name_2\.. \name_3	C:\name_1\name_3
C:\name_1\.. \name_2\.\name_3	C:\name_2\name_3
C:\name_1\name_2\.\name_3\.. \name_4	C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\.. \name_4\..	C:\name_1\name_2
C:\name_1\*...	C:\name_1\*.
C:\..	C:\

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	pathcch.h
Pustaka	Pathcch.lib

Lihat juga

PathCchCanonicalize

Bagikan melalui