Fungsi GetFullPathNameA (fileapi.h)

Artikel
2024-11-20

Mengambil jalur lengkap dan nama file dari file yang ditentukan.

Untuk melakukan operasi ini sebagai operasi yang ditransaksikan, gunakan fungsi GetFullPathNameTransacted.

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

Catatan Lihat bagian Komentar untuk diskusi tentang penggunaan jalur relatif dengan fungsi GetFullPathName di aplikasi multithreaded atau kode pustaka bersama.

Sintaksis

DWORD GetFullPathNameA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart
);

Parameter

[in] lpFileName

Nama file.

Parameter ini bisa berupa nama file pendek (formulir 8.3) atau panjang. String ini juga dapat menjadi nama berbagi atau volume.

[in] nBufferLength

Ukuran buffer untuk menerima string yang dihentikan null untuk drive dan jalur, dalam TCHAR.

[out] lpBuffer

Penunjuk ke buffer yang menerima string null-terminated untuk drive dan jalur.

[out] lpFilePart

Penunjuk ke buffer yang menerima alamat (dalam lpBuffer) dari komponen nama file akhir di jalur.

Parameter ini dapat null.

Jika lpBuffer mengacu pada direktori dan bukan file, lpFilePart menerima nol.

Mengembalikan nilai

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

Jika buffer lpBuffer terlalu kecil untuk memuat jalur, nilai yang dikembalikan adalah ukurannya, dalam TCHAR, dari buffer 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, panggil GetLastError.

Komentar

GetFullPathName menggabungkan nama drive dan direktori saat ini dengan nama file tertentu untuk menentukan jalur lengkap dan nama file dari file tertentu. Ini juga menghitung alamat bagian nama file dari jalur lengkap dan nama file.

Fungsi ini tidak memverifikasi bahwa jalur yang dihasilkan dan nama file valid, atau bahwa mereka melihat file yang ada pada volume terkait.

Perhatikan bahwa parameter lpFilePart tidak memerlukan ruang buffer string, tetapi hanya cukup untuk satu alamat. Ini karena hanya mengembalikan alamat dalam buffer yang sudah ada untuk lpBuffer.

Nama berbagi dan volume adalah input yang valid untuk lpFileName. Misalnya, daftar identitas berikut jalur dan nama file yang dikembalikan jika test-2 adalah komputer jarak jauh dan U: adalah drive yang dipetakan jaringan yang direktorinya saat ini adalah akar volume:

Jika Anda menentukan "\\test-2\q$\lh" jalur yang dikembalikan adalah "\\test-2\q$\lh"
Jika Anda menentukan "\\?\UNC\test-2\q$\lh" jalur yang dikembalikan adalah "\\?\UNC\test-2\q$\lh"
Jika Anda menentukan "U:" jalur yang dikembalikan adalah direktori saat ini pada drive "U:\"

GetFullPathName tidak mengonversi nama file yang ditentukan, lpFileName. Jika nama file yang ditentukan ada, Anda dapat menggunakan GetLongPathName atau GetShortPathName untuk mengonversi ke nama jalur panjang atau pendek.

Jika nilai pengembalian lebih besar dari atau sama dengan nilai yang ditentukan dalam nBufferLength, 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 Kode Contoh.

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

Jalur relatif yang diteruskan ke fungsi GetFullPathName ditafsirkan relatif terhadap direktori proses saat ini. Status direktori saat ini yang ditulis oleh fungsi SetCurrentDirectory bersifat global untuk proses dan dapat diubah oleh utas apa pun kapan saja. Aplikasi harus menyadari bahwa panggilan berturut-turut ke fungsi GetFullPathName dengan jalur relatif dapat menghasilkan hasil yang berbeda jika direktori saat ini berubah di antara dua panggilan.

Untuk menghindari masalah yang disebabkan oleh hasil yang tidak konsisten, aplikasi multithreaded dan kode pustaka bersama harus menghindari penggunaan jalur relatif. Jika jalur relatif diterima, jalur harus dikonsumsi tepat sekali, baik dengan melewati jalur relatif langsung ke fungsi seperti CreateFile, atau dengan mengonversinya ke jalur absolut dan menggunakan jalur absolut dari titik tersebut ke depan.

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

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Contoh

Contoh C++ berikut menunjukkan penggunaan dasar GetFullPathName, GetLongPathName, dan GetShortPathName. Untuk contoh lain menggunakan alokasi dinamis, lihat GetShortPathName.

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")

void _tmain(int argc, TCHAR *argv[])
{
    DWORD  retval=0;
    BOOL   success; 
    TCHAR  buffer[BUFSIZE]=TEXT(""); 
    TCHAR  buf[BUFSIZE]=TEXT(""); 
    TCHAR** lppPart={NULL};

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
      return;
   }

// Retrieve the full path name for a file. 
// The file does not need to exist.

    retval = GetFullPathName(argv[1],
                 BUFSIZE,
                 buffer,
                 lppPart);
    
    if (retval == 0) 
    {
        // Handle an error condition.
        printf ("GetFullPathName failed (%d)\n", GetLastError());
        return;
    }
    else 
    {
        _tprintf(TEXT("The full path name is:  %s\n"), buffer);
        if (lppPart != NULL && *lppPart != 0)
        {
            _tprintf(TEXT("The final component in the path name is:  %s\n"), *lppPart);
        }
    }


// Create a long directory name for use with the next two examples.

    success = CreateDirectory(LONG_DIR_NAME,
                              NULL);

    if (!success)
    {
        // Handle an error condition.
        printf ("CreateDirectory failed (%d)\n", GetLastError());
        return;
    }


// Retrieve the short path name.  

    retval = GetShortPathName(LONG_DIR_NAME,
                  buf,
                  BUFSIZE);

    if (retval == 0) 
    {
        // Handle an error condition.
         printf ("GetShortPathName failed (%d)\n", GetLastError());
         return;
    }
    else _tprintf(TEXT("The short name for %s is %s\n"), 
                  LONG_DIR_NAME, buf);


// Retrieve the long path name.  

    retval = GetLongPathName(buf,
              buffer,
              BUFSIZE);

    if (retval == 0) 
    {
        // Handle an error condition.
         printf ("GetLongPathName failed (%d)\n", GetLastError());
         return;
    }
    else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);

// Clean up the directory.

    success = RemoveDirectory(LONG_DIR_NAME);
    if (!success)
    {
        // Handle an error condition.
        printf ("RemoveDirectory failed (%d)\n", GetLastError());
        return;
    }
}

Nota

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

Syarat	Nilai
klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	fileapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

File Management Functions

GetFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

SearchPath

Bagikan melalui