Fungsi GetShortPathNameW (fileapi.h)

Artikel
02/28/2024

Mengambil bentuk jalur pendek dari jalur yang ditentukan.

Untuk informasi selengkapnya tentang nama file dan jalur, lihat Menamai File, Jalur, dan Namespace.

Sintaks

DWORD GetShortPathNameW(
  [in]  LPCWSTR lpszLongPath,
  [out] LPWSTR  lpszShortPath,
  [in]  DWORD   cchBuffer
);

Parameter

[in] lpszLongPath

String jalur.

Secara default, namanya terbatas pada MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

Tip

Dimulai dengan Windows 10, Versi 1607, Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa menambahkan sebelumnya "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" di Penamaan File, Jalur, dan Namespace untuk detailnya.

[out] lpszShortPath

Pointer ke buffer untuk menerima bentuk pendek null-dihentikan dari jalur yang ditentukan lpszLongPath .

Meneruskan NULL untuk parameter ini dan nol untuk cchBuffer akan selalu mengembalikan ukuran buffer yang diperlukan untuk lpszLongPath tertentu.

[in] cchBuffer

Ukuran buffer yang dituju lpszShortPath , dalam TCHAR.

Atur parameter ini ke nol jika lpszShortPath diatur ke NULL.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah panjangnya, dalam TCHAR, dari string yang disalin ke lpszShortPath, tidak termasuk karakter null yang mengakhiri.

Jika buffer lpszShortPath terlalu kecil untuk memuat jalur, nilai yang dikembalikan adalah ukuran buffer, dalam TCHAR, yang diperlukan untuk menahan jalur dan karakter null yang mengakhiri.

Jika fungsi gagal karena alasan lain, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jalur yang ditentukan parameter lpszLongPath tidak harus jalur penuh atau panjang. Bentuk pendek bisa lebih panjang dari jalur yang ditentukan.

Jika nilai yang dikembalikan lebih besar dari nilai yang ditentukan dalam parameter cchBuffer , Anda dapat memanggil fungsi lagi dengan buffer yang cukup besar untuk menahan jalur. Untuk contoh kasus ini selain menggunakan buffer panjang nol untuk alokasi dinamis, lihat bagian Contoh Kode.

Catatan Meskipun nilai yang dikembalikan dalam kasus ini adalah panjang yang mencakup karakter null yang mengakhiri, nilai pengembalian pada keberhasilan tidak menyertakan karakter null yang mengakhiri dalam hitungan.

Jika jalur yang ditentukan sudah dalam bentuk pendek dan konversi tidak diperlukan, fungsi hanya menyalin jalur yang ditentukan ke buffer yang ditentukan oleh parameter lpszShortPath .

Anda dapat mengatur parameter lpszShortPath ke nilai yang sama dengan parameter lpszLongPath ; dengan kata lain, Anda dapat mengatur buffer output untuk jalur pendek ke alamat string jalur input. Selalu pastikan bahwa parameter cchBuffer secara akurat mewakili ukuran total, dalam TCHAR, dari buffer ini.

Anda dapat memperoleh nama panjang file dari nama pendek dengan memanggil fungsi GetLongPathName . Atau, di mana GetLongPathName tidak tersedia, Anda dapat memanggil FindFirstFile pada setiap komponen jalur untuk mendapatkan nama panjang yang sesuai.

Dimungkinkan untuk memiliki akses ke file atau direktori tetapi tidak memiliki akses ke beberapa direktori induk file atau direktori tersebut. Akibatnya, GetShortPathName mungkin gagal ketika tidak dapat mengkueri direktori induk komponen jalur untuk menentukan nama pendek untuk komponen tersebut. Pemeriksaan ini dapat dilewati untuk komponen direktori yang sudah memenuhi persyaratan nama pendek. Untuk informasi selengkapnya, lihat bagian Nama Pendek vs. Panjang dari Penamaan File, Jalur, dan Namespace.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Tidak
SMB 3.0 dengan Berbagi File Peluasan Skala (SO)	Tidak
Sistem File Volume Bersama Kluster (CsvFS)	Tidak
Sistem File Tangguh (ReFS)	Ya

SMB 3.0 tidak mendukung nama pendek pada berbagi dengan kemampuan ketersediaan berkelanjutan.

Sistem File Tangguh (ReFS) tidak mendukung nama pendek. Jika Anda memanggil GetShortPathName di jalur yang tidak memiliki nama pendek pada disk, panggilan akan berhasil, tetapi akan mengembalikan jalur nama panjang sebagai gantinya. Hasil ini juga dimungkinkan dengan volume NTFS karena tidak ada jaminan bahwa nama pendek akan ada untuk nama panjang tertentu.

Contoh

Untuk contoh yang menggunakan GetShortPathName, lihat bagian Contoh Kode untuk GetFullPathName.

Contoh C++ berikut menunjukkan cara menggunakan buffer output yang dialokasikan secara dinamis.

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll