Fungsi LockFileEx (fileapi.h)

Artikel
08/23/2023

Mengunci file yang ditentukan untuk akses eksklusif oleh proses panggilan. Fungsi ini dapat beroperasi baik secara sinkron atau asinkron dan dapat meminta kunci eksklusif atau bersama.

Sintaks

BOOL LockFileEx(
  [in]      HANDLE       hFile,
  [in]      DWORD        dwFlags,
            DWORD        dwReserved,
  [in]      DWORD        nNumberOfBytesToLockLow,
  [in]      DWORD        nNumberOfBytesToLockHigh,
  [in, out] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hFile

Handel ke file. Handel harus dibuat dengan hak akses GENERIC_READ atau GENERIC_WRITE . Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

[in] dwFlags

Parameter ini mungkin satu atau beberapa nilai berikut.

Nilai	Makna
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	Fungsi ini meminta kunci eksklusif. Jika tidak, ia meminta kunci bersama.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	Fungsi segera kembali jika tidak dapat memperoleh kunci yang diminta. Jika tidak, itu menunggu.

dwReserved

Parameter yang dicadangkan; harus diatur ke nol.

[in] nNumberOfBytesToLockLow

Panjang 32 bit urutan rendah dari rentang byte untuk dikunci.

[in] nNumberOfBytesToLockHigh

Panjang 32 bit urutan tinggi dari rentang byte untuk dikunci.

[in, out] lpOverlapped

Penunjuk ke struktur TUMPANG TINDIH yang digunakan fungsi dengan permintaan penguncian. Struktur ini, yang diperlukan, berisi offset file dari awal rentang kunci. Anda harus menginisialisasi anggota hEvent ke handel atau nol yang valid.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE). Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Mengunci wilayah file digunakan untuk memperoleh akses bersama atau eksklusif ke wilayah yang ditentukan menggunakan handel file ini. Jika handel file diwariskan oleh proses yang dibuat oleh proses penguncian, proses anak tidak diberikan akses ke wilayah terkunci. Jika proses penguncian membuka file untuk kedua kalinya, proses penguncian tidak dapat mengakses wilayah yang ditentukan melalui handel kedua ini hingga membuka kunci wilayah.

Mengunci sebagian file untuk akses eksklusif menolak semua proses lain baik akses baca maupun tulis ke wilayah file yang ditentukan. Mengunci wilayah yang melampaui posisi akhir file saat ini bukanlah kesalahan.

Mengunci sebagian file untuk akses bersama menolak semua proses menulis akses ke wilayah file yang ditentukan, termasuk proses yang pertama kali mengunci wilayah. Semua proses dapat membaca wilayah terkunci.

Mengunci wilayah file tidak mencegah pembacaan atau penulisan dari tampilan file yang dipetakan.

Fungsi LockFileEx beroperasi secara asinkron jika handel file dibuka untuk I/O asinkron, kecuali bendera LOCKFILE_FAIL_IMMEDIATELY ditentukan. Jika kunci eksklusif diminta untuk rentang file yang sudah memiliki kunci bersama atau eksklusif, fungsi mengembalikan kesalahan ERROR_IO_PENDING. Sistem akan memberi sinyal peristiwa yang ditentukan dalam struktur TUMPANG TINDIH setelah kunci diberikan. Untuk menentukan kapan kunci telah diberikan, gunakan fungsi GetOverlappedResult atau salah satu fungsi tunggu. Untuk informasi selengkapnya, lihat I/O Sinkron dan Asinkron.

Jika handel file tidak dibuka untuk I/O asinkron dan kunci tidak tersedia, panggilan ini menunggu hingga kunci diberikan atau terjadi kesalahan, kecuali bendera LOCKFILE_FAIL_IMMEDIATELY ditentukan.

Kunci eksklusif tidak dapat tumpang tindih dengan wilayah terkunci yang ada dari suatu file. Kunci bersama dapat tumpang tindih dengan wilayah terkunci yang menyediakan kunci yang disimpan di wilayah tersebut adalah kunci bersama. Kunci bersama dapat tumpang tindih dengan kunci eksklusif jika kedua kunci dibuat menggunakan handel file yang sama. Ketika kunci bersama tumpang tindih dengan kunci eksklusif, satu-satunya akses yang mungkin adalah baca oleh pemilik kunci. Jika rentang yang sama dikunci dengan kunci eksklusif dan bersama, dua operasi buka kunci diperlukan untuk membuka kunci wilayah; operasi buka kunci pertama membuka kunci eksklusif, operasi buka kunci kedua membuka kunci bersama.

Jika proses berakhir dengan sebagian file terkunci atau menutup file yang memiliki kunci yang luar biasa, kunci akan dibuka oleh sistem operasi. Namun, waktu yang diperlukan sistem operasi untuk membuka kunci ini tergantung pada sumber daya sistem yang tersedia. Oleh karena itu, disarankan agar proses Anda secara eksplisit membuka kunci semua file yang telah dikuncinya saat dihentikan. Jika ini tidak dilakukan, akses ke file-file ini dapat ditolak jika sistem operasi belum membukanya.

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 Berbagi File Peluasan Skala (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

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