Fungsi SetFilePointer (fileapi.h)
Memindahkan penunjuk file dari file yang ditentukan.
Fungsi ini menyimpan penunjuk file dalam dua nilai LONG . Untuk bekerja dengan penunjuk file yang lebih besar dari satu nilai LONG , lebih mudah untuk menggunakan fungsi SetFilePointerEx .
Sintaks
DWORD SetFilePointer(
[in] HANDLE hFile,
[in] LONG lDistanceToMove,
[in, out, optional] PLONG lpDistanceToMoveHigh,
[in] DWORD dwMoveMethod
);
Parameter
[in] hFile
Handel ke file.
Handel file harus dibuat dengan hak akses GENERIC_READ atau GENERIC_WRITE . Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.
[in] lDistanceToMove
Urutan rendah 32-bit dari nilai yang ditandatangani yang menentukan jumlah byte untuk memindahkan penunjuk file.
Jika lpDistanceToMoveHigh bukan NULL, lpDistanceToMoveHigh dan lDistanceToMove membentuk nilai bertanda tangan 64-bit tunggal yang menentukan jarak untuk bergerak.
Jika lpDistanceToMoveHigh adalah NULL, lDistanceToMove adalah nilai bertanda tangan 32-bit. Nilai positif untuk lDistanceToMove memindahkan penunjuk file ke depan dalam file, dan nilai negatif memindahkan penunjuk file kembali.
[in, out, optional] lpDistanceToMoveHigh
Penunjuk ke urutan tinggi 32-bit dari jarak 64-bit yang ditandatangani untuk bergerak.
Jika Anda tidak memerlukan urutan tinggi 32-bit, pointer ini harus diatur ke NULL.
Ketika tidak NULL, parameter ini juga menerima DWORD urutan tinggi dari nilai baru penunjuk file. Untuk informasi selengkapnya, lihat bagian Keterangan dalam topik ini.
[in] dwMoveMethod
Titik awal untuk pemindahan penunjuk file.
Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Titik awal adalah nol atau awal file. |
|
Titik awal adalah nilai pointer file saat ini. |
|
Titik awal adalah posisi akhir file saat ini. |
Nilai kembali
Jika fungsi berhasil dan lpDistanceToMoveHigh adalah NULL, nilai yang dikembalikan adalah DWORD berurutan rendah dari penunjuk file baru. Catatan Jika fungsi mengembalikan nilai selain INVALID_SET_FILE_POINTER, panggilan ke SetFilePointer telah berhasil. Anda tidak perlu memanggil GetLastError.
Jika fungsi berhasil dan lpDistanceToMoveHigh bukan NULL, nilai yang dikembalikan adalah DWORD berurutan rendah dari pointer file baru dan lpDistanceToMoveHigh berisi DWORD urutan tinggi dari penunjuk file baru.
Jika fungsi gagal, nilai yang dikembalikan adalah INVALID_SET_FILE_POINTER. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Jika penunjuk file baru adalah nilai negatif, fungsi gagal, penunjuk file tidak dipindahkan, dan kode yang dikembalikan oleh GetLastErrorERROR_NEGATIVE_SEEK.
Jika lpDistanceToMoveHigh adalah NULL dan posisi file baru tidak cocok dalam nilai 32-bit, fungsi gagal dan mengembalikan INVALID_SET_FILE_POINTER.
Keterangan
Penunjuk file yang diidentifikasi oleh nilai parameter hFile tidak digunakan untuk operasi baca dan tulis yang tumpang tindih.
Parameter hFile harus merujuk ke file yang disimpan di perangkat pencarian; misalnya, volume disk. Memanggil fungsi SetFilePointer dengan handel ke perangkat yang tidak mencari seperti pipa atau perangkat komunikasi tidak didukung, meskipun fungsi SetFilePointer mungkin tidak mengembalikan kesalahan. Perilaku fungsi SetFilePointer dalam hal ini tidak ditentukan.
Untuk menentukan offset untuk operasi yang tumpang tindih
- Gunakan anggota Offset dan OffsetHigh dari struktur YANG TUMPANG TINDIH .
Untuk menentukan jenis file untuk hFile
- Gunakan fungsi GetFileType .
Berhati-hatilah saat Anda mengatur penunjuk file dalam aplikasi multithreaded. Anda harus menyinkronkan akses ke sumber daya bersama. Misalnya, aplikasi dengan utas yang berbagi handel file, memperbarui penunjuk file, dan membaca dari file harus melindungi urutan ini dengan menggunakan objek bagian penting atau objek mutex. Untuk informasi selengkapnya, lihat Objek Bagian Penting dan Objek Mutex.
Jika handel hFile dibuka dengan set bendera FILE_FLAG_NO_BUFFERING , aplikasi hanya dapat memindahkan penunjuk file ke posisi yang selaras dengan sektor. Posisi yang selaras dengan sektor adalah posisi yang merupakan kelipatan bilangan bulur dari ukuran sektor volume. Aplikasi dapat memperoleh ukuran sektor volume dengan memanggil fungsi GetDiskFreeSpace .
Jika aplikasi memanggil SetFilePointer dengan jarak untuk memindahkan nilai yang menghasilkan posisi yang tidak selaras dengan sektor dan handel yang dibuka dengan FILE_FLAG_NO_BUFFERING, fungsi gagal, dan GetLastError mengembalikan ERROR_INVALID_PARAMETER.
Ini bukan kesalahan untuk mengatur penunjuk file ke posisi di luar akhir file. Ukuran file tidak meningkat sampai Anda memanggil fungsi SetEndOfFile, WriteFile, atau WriteFileEx . Operasi tulis meningkatkan ukuran file ke posisi penunjuk file ditambah ukuran buffer yang ditulis, yang menghasilkan byte intervensi menjadi nol diinisialisasi.
Jika nilai yang dikembalikan INVALID_SET_FILE_POINTER dan jika lpDistanceToMoveHighnon-NULL, aplikasi harus memanggil GetLastError untuk menentukan apakah fungsi telah berhasil atau gagal. Contoh kode berikut menunjukkan skenario tersebut.
// Case One: calling the function with lpDistanceToMoveHigh == NULL
// Try to move hFile file pointer some distance
DWORD dwPtr = SetFilePointer( hFile,
lDistance,
NULL,
FILE_BEGIN );
if (dwPtr == INVALID_SET_FILE_POINTER) // Test for failure
{
// Obtain the error code.
DWORD dwError = GetLastError() ;
// Deal with failure
// . . .
} // End of error handler
//
// Case Two: calling the function with lpDistanceToMoveHigh != NULL
// Try to move hFile file pointer a huge distance
DWORD dwPtrLow = SetFilePointer( hFile,
lDistLow,
&lDistHigh,
FILE_BEGIN );
// Test for failure
if ( dwPtrLow == INVALID_SET_FILE_POINTER &&
GetLastError() != NO_ERROR )
{
// Deal with failure
// . . .
} // End of error handler
Meskipun parameter lpDistanceToMoveHigh digunakan untuk memanipulasi file besar, nilai parameter harus diatur saat memindahkan file dengan ukuran apa pun. Jika diatur ke NULL, maka lDistanceToMove memiliki nilai maksimum 2^31–2, atau 2 gigabyte kurang 2, karena semua nilai penunjuk file adalah nilai yang ditandatangani. Oleh karena itu, jika bahkan ada kesempatan kecil bagi file untuk meningkatkan ke ukuran itu, yang terbaik adalah memperlakukan file sebagai file besar dan bekerja dengan penunjuk file 64-bit. Dengan kompresi file pada sistem file NTFS, dan file jarang, dimungkinkan untuk memiliki file yang besar bahkan jika volume yang mendasar tidak terlalu besar.
Jika lpDistanceToMoveHigh bukan NULL, maka lpDistanceToMoveHigh dan lDistanceToMove membentuk nilai bertanda tangan 64-bit tunggal. Parameter lDistanceToMove diperlakukan sebagai nilai 32 bit urutan rendah, dan lpDistanceToMoveHigh sebagai urutan tinggi 32 bit, yang berarti bahwa lpDistanceToMoveHigh adalah ekstensi tanda dari lDistanceToMove.
Untuk memindahkan penunjuk file dari nol ke 2 gigabyte, lpDistanceToMoveHigh harus diatur ke NULL atau ekstensi tanda lDistanceToMove. Untuk memindahkan pointer lebih dari 2 gigabyte, gunakan lpDistanceToMoveHigh dan lDistanceToMove sebagai kuantitas 64-bit tunggal. Misalnya, untuk bergerak dalam rentang dari 2 gigabyte hingga 4 gigabyte mengatur konten lpDistanceToMoveHigh ke nol, atau ke –1 untuk ekstensi tanda negatif lDistanceToMove.
Untuk bekerja dengan penunjuk file 64-bit, Anda dapat mendeklarasikan LONG, memperlakukannya sebagai bagian atas dari penunjuk file 64-bit, dan meneruskan alamatnya di lpDistanceToMoveHigh. Ini berarti Bahwa Anda harus memperlakukan dua variabel yang berbeda sebagai unit logis, yang dapat menyebabkan kesalahan. Yang terbaik adalah menggunakan struktur LARGE_INTEGER untuk membuat nilai 64-bit dan meneruskan dua nilai 32-bit dengan menggunakan elemen yang sesuai dari serikat.
Selain itu, yang terbaik adalah menggunakan fungsi untuk menyembunyikan antarmuka ke SetFilePointer. Contoh kode berikut menunjukkan skenario tersebut.
__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
LARGE_INTEGER li;
li.QuadPart = distance;
li.LowPart = SetFilePointer (hf,
li.LowPart,
&li.HighPart,
MoveMethod);
if (li.LowPart == INVALID_SET_FILE_POINTER && GetLastError()
!= NO_ERROR)
{
li.QuadPart = -1;
}
return li.QuadPart;
}
Anda bisa menggunakan SetFilePointer untuk menentukan panjang file. Untuk melakukan ini, gunakan FILE_END untuk dwMoveMethod dan cari lokasi nol. Offset file yang dikembalikan adalah panjang file. Namun, praktik ini dapat memiliki efek samping yang tidak diinginkan, misalnya, kegagalan untuk menyimpan penunjuk file saat ini sehingga program dapat kembali ke lokasi tersebut. Sebaiknya gunakan GetFileSize sebagai gantinya.
Anda juga bisa menggunakan fungsi SetFilePointer untuk mengkueri posisi penunjuk file saat ini. Untuk melakukan ini, tentukan metode pemindahan FILE_CURRENT dan jarak nol.
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) | Ya |
| SMB 3.0 dengan Scale-out File Shares (SO) | Ya |
| Sistem File Volume Bersama Kluster (CsvFS) | Ya |
| Sistem File Tangguh (ReFS) | Ya |
Contoh
Untuk contoh kode menambahkan file, lihat Menambahkan Satu File ke File Lain.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | fileapi.h (sertakan Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk