Fungsi OpenFileById (winbase.h)
Membuka file yang cocok dengan pengidentifikasi yang ditentukan.
Sintaks
HANDLE OpenFileById(
[in] HANDLE hVolumeHint,
[in] LPFILE_ID_DESCRIPTOR lpFileId,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwFlagsAndAttributes
);
Parameter
[in] hVolumeHint
Handel ke file apa pun pada volume atau berbagi tempat file yang akan dibuka disimpan.
[in] lpFileId
Penunjuk ke FILE_ID_DESCRIPTOR yang mengidentifikasi file yang akan dibuka.
[in] dwDesiredAccess
Akses ke objek . Akses dapat dibaca, ditulis, atau keduanya.
Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses. Anda tidak dapat meminta mode akses yang berkonflik dengan mode berbagi yang ditentukan dalam permintaan terbuka yang memiliki handel terbuka.
Jika parameter ini nol (0), aplikasi dapat mengkueri atribut file dan perangkat tanpa mengakses perangkat. Ini berguna bagi aplikasi untuk menentukan ukuran drive disket dan format yang didukungnya tanpa memerlukan floppy dalam drive. Ini juga dapat digunakan untuk menguji keberadaan file atau direktori tanpa membukanya untuk akses baca atau tulis.
[in] dwShareMode
Mode berbagi objek, yang dapat dibaca, ditulis, keduanya, atau tidak ada.
Anda tidak dapat meminta mode berbagi yang berkonflik dengan mode akses yang ditentukan dalam permintaan terbuka yang memiliki handel terbuka, karena itu akan mengakibatkan pelanggaran berbagi berikut: (ERROR_SHARING_VIOLATION). Untuk informasi selengkapnya, lihat Membuat dan Membuka File.
Jika parameter ini nol (0) dan OpenFileById berhasil, objek tidak dapat dibagikan dan tidak dapat dibuka lagi sampai handel ditutup. Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.
Opsi berbagi tetap berlaku hingga Anda menutup handel ke objek.
Untuk mengaktifkan proses berbagi objek saat proses lain membuka objek, gunakan kombinasi satu atau beberapa nilai berikut untuk menentukan mode akses yang dapat mereka minta untuk membuka objek.
[in, optional] lpSecurityAttributes
Dicadangkan.
[in] dwFlagsAndAttributes
Bendera file.
Saat OpenFileById membuka file, openFileById menggabungkan bendera file dengan atribut file yang ada, dan mengabaikan atribut file yang disediakan. Parameter ini dapat mencakup kombinasi bendera berikut.
Nilai | Makna |
---|---|
|
File sedang dibuka untuk operasi pencadangan atau pemulihan. Sistem memastikan bahwa proses panggilan mengambil alih pemeriksaan keamanan file ketika proses memiliki hak istimewa SE_BACKUP_NAME dan SE_RESTORE_NAME . Untuk informasi selengkapnya, lihat Mengubah Hak Istimewa dalam Token.
Anda harus mengatur bendera ini untuk mendapatkan handel ke direktori. Handel direktori dapat diteruskan ke beberapa fungsi alih-alih handel file. Untuk informasi selengkapnya, lihat Handel Direktori. |
|
Sistem membuka file tanpa penembolokan sistem. Bendera ini tidak mempengaruhi penembolokan hard disk. Ketika dikombinasikan dengan FILE_FLAG_OVERLAPPED, bendera memberikan performa asinkron maksimum, karena I/O tidak bergantung pada operasi sinkron manajer memori. Namun, beberapa operasi I/O membutuhkan lebih banyak waktu, karena data tidak ditahan di cache. Selain itu, metadata file mungkin masih di-cache. Untuk menghapus metadata ke disk, gunakan fungsi FlushFileBuffers .
Aplikasi harus memenuhi persyaratan tertentu saat bekerja dengan file yang dibuka dengan FILE_FLAG_NO_BUFFERING:
Aplikasi dapat menentukan ukuran sektor volume dengan memanggil fungsi GetDiskFreeSpace . |
|
Data file diminta, tetapi harus terus berada di penyimpanan jarak jauh. Ini tidak boleh diangkut kembali ke penyimpanan lokal. Bendera ini untuk digunakan oleh sistem penyimpanan jarak jauh. |
|
Ketika bendera ini digunakan, pemrosesan titik pemilah ulang normal tidak terjadi, dan OpenFileById mencoba membuka titik pemilah ulang. Ketika file dibuka, handel file dikembalikan, apakah filter yang mengontrol titik pemilah ulang beroperasi atau tidak. Bendera ini tidak dapat digunakan dengan bendera CREATE_ALWAYS . Jika file bukan titik pemilah ulang, maka bendera ini diabaikan. |
|
File sedang dibuka atau dibuat untuk I/O asinkron. Ketika operasi selesai, peristiwa yang ditentukan untuk panggilan dalam struktur TUMPANG TINDIH diatur ke status tersinyal. Operasi yang membutuhkan banyak waktu untuk memproses pengembalian ERROR_IO_PENDING.
Jika bendera ini ditentukan, file dapat digunakan untuk operasi baca dan tulis secara bersamaan. Sistem tidak mempertahankan penunjuk file, oleh karena itu Anda harus meneruskan posisi file ke fungsi baca dan tulis dalam struktur yang TUMPANG TINDIH atau memperbarui penunjuk file. Jika bendera ini tidak ditentukan, maka operasi I/O diserialisasikan, bahkan jika panggilan ke fungsi baca dan tulis menentukan struktur yang TUMPANG TINDIH . |
|
File diakses secara acak. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file. |
|
File diakses secara berurutan dari awal hingga akhir. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file. Jika aplikasi memindahkan penunjuk file untuk akses acak, penembolokan optimal mungkin tidak terjadi. Namun, operasi yang benar masih dijamin.
Menentukan bendera ini dapat meningkatkan performa untuk aplikasi yang membaca file besar menggunakan akses berurutan. Perolehan performa bisa lebih terlihat untuk aplikasi yang membaca file besar sebagian besar secara berurutan, tetapi kadang-kadang melewati rentang kecil byte. |
|
Sistem menulis melalui cache perantara apa pun dan langsung masuk ke disk.
Jika FILE_FLAG_NO_BUFFERING tidak juga ditentukan, sehingga penembolokan sistem berlaku, maka data ditulis ke cache sistem, tetapi dibersihkan ke disk tanpa penundaan. Jika FILE_FLAG_NO_BUFFERING juga ditentukan, sehingga penembolokan sistem tidak berlaku, maka data segera dibersihkan ke disk tanpa melalui cache sistem. Sistem operasi juga meminta penulisan melalui cache hard disk ke media persisten. Namun, tidak semua perangkat keras mendukung kemampuan write-through ini. |
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah handel terbuka ke file tertentu.
Jika fungsi gagal, nilai yang dikembalikan INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Keterangan
Gunakan fungsi CloseHandle untuk menutup handel objek yang dikembalikan OpenFileById .
Jika Anda memanggil OpenFileById pada file yang menunggu penghapusan sebagai akibat dari panggilan sebelumnya ke DeleteFile, fungsi gagal. Sistem operasi menunda penghapusan file hingga semua handel ke file ditutup. GetLastError mengembalikan ERROR_ACCESS_DENIED.
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) | Ya |
Sistem File Tangguh (ReFS) | Ya |
Persyaratan
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; FileExtd.lib di Windows Server 2003 dan Windows XP |
DLL | Kernel32.dll |
Redistribusi | Windows SDK di Windows Server 2003 dan Windows XP. |