Fungsi GetFullPathNameTransactedA (winbase.h)

Artikel
08/27/2023

[Microsoft sangat menyarankan pengembang menggunakan cara alternatif untuk mencapai kebutuhan aplikasi Anda. Banyak skenario yang dikembangkan TxF dapat dicapai melalui teknik yang lebih sederhana dan lebih tersedia. Selain itu, TxF mungkin tidak tersedia di versi Microsoft Windows yang akan datang. Untuk informasi lebih lanjut, dan alternatif TxF, silakan lihat Alternatif untuk menggunakan Transactional NTFS.]

Mengambil jalur lengkap dan nama file dari file yang ditentukan sebagai operasi yang ditransaksikan.

Untuk melakukan operasi ini tanpa transaksi, gunakan fungsi GetFullPathName .

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

Sintaks

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

Parameter

[in] lpFileName

Nama file.

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

File harus berada di komputer lokal; jika tidak, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] nBufferLength

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

[out] lpBuffer

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

[out] lpFilePart

Penunjuk ke buffer yang menerima alamat (di lpBuffer) dari komponen nama file akhir di jalur. Tentukan NULL jika Anda tidak perlu menerima informasi ini.

Jika lpBuffer menunjuk ke direktori dan bukan file, lpFilePart menerima 0 (nol).

[in] hTransaction

Handel ke transaksi. Handel ini dikembalikan oleh fungsi CreateTransaction .

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan 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 ukuran, di 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, hubungi GetLastError.

Keterangan

GetFullPathNameTransacted 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 dan nama file yang dihasilkan valid, atau bahwa mereka melihat file yang ada pada volume terkait.

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

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 "U:\"

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

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

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

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

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

SMB 3.0 tidak mendukung TxF.

Catatan

Header winbase.h mendefinisikan GetFullPathNameTransacted 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 Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll