Fungsi OpenFileById (winbase.h)

Artikel
03/08/2023

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.

Nilai	Makna
FILE_SHARE_DELETE 0x00000004	Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses penghapusan. Jika tidak, proses lain tidak dapat membuka objek jika meminta akses penghapusan. Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses penghapusan, fungsi gagal.
FILE_SHARE_READ 0x00000001	Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses baca. Jika tidak, proses lain tidak dapat membuka objek jika meminta akses baca. Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses baca, fungsi gagal.
FILE_SHARE_WRITE 0x00000002	Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses tulis. Jika tidak, proses lain tidak dapat membuka objek jika meminta akses tulis. Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses tulis atau memiliki pemetaan file dengan akses tulis, fungsi gagal.

Nilai

Makna

FILE_SHARE_DELETE
0x00000004

Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses penghapusan.

Jika tidak, proses lain tidak dapat membuka objek jika meminta akses penghapusan.

Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses penghapusan, fungsi gagal.

FILE_SHARE_READ
0x00000001

Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses baca.

Jika tidak, proses lain tidak dapat membuka objek jika meminta akses baca.

Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses baca, fungsi gagal.

FILE_SHARE_WRITE
0x00000002

Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses tulis.

Jika tidak, proses lain tidak dapat membuka objek jika meminta akses tulis.

Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses tulis atau memiliki pemetaan file dengan akses tulis, fungsi gagal.

[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_FLAG_BACKUP_SEMANTICS 0x02000000	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.
FILE_FLAG_NO_BUFFERING 0x20000000	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: Akses file harus dimulai pada offset byte dalam file yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Akses file harus untuk jumlah byte yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Misalnya, jika ukuran sektor adalah 512 byte, aplikasi dapat meminta baca dan tulis 512, 1024, 1536, atau 2048 byte, tetapi tidak 335, 981, atau 7171 byte. Alamat buffer untuk operasi baca dan tulis harus diselaraskan dengan sektor, yang berarti diselaraskan pada alamat dalam memori yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Tergantung pada disk, persyaratan ini mungkin tidak diberlakukan. Salah satu cara untuk menyelaraskan buffer pada kelipatan bilangan bulat dari ukuran sektor volume adalah dengan menggunakan VirtualAlloc untuk mengalokasikan buffer. Ini mengalokasikan memori yang selaras pada alamat yang merupakan kelipatan bilangan bulat dari ukuran halaman memori sistem operasi. Karena ukuran halaman memori dan sektor volume adalah kekuatan 2, memori ini juga diselaraskan pada alamat yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Halaman memori berukuran 4-8 KB; sektor adalah 512 byte (hard disk) atau 2048 byte (CD), dan oleh karena itu, sektor volume tidak pernah bisa lebih besar dari halaman memori. Aplikasi dapat menentukan ukuran sektor volume dengan memanggil fungsi GetDiskFreeSpace .
FILE_FLAG_OPEN_NO_RECALL 0x00100000	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.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	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_FLAG_OVERLAPPED 0x40000000	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_FLAG_RANDOM_ACCESS 0x10000000	File diakses secara acak. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	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.
FILE_FLAG_WRITE_THROUGH 0x80000000	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.