Fungsi CfOpenFileWithOplock (cfapi.h)

Membuka handel buram asinkron ke file atau direktori (untuk file normal dan tempat penampung) dan menyiapkan oplock yang tepat berdasarkan bendera terbuka.

Sintaksis

HRESULT CfOpenFileWithOplock(
  [in]  LPCWSTR            FilePath,
  [in]  CF_OPEN_FILE_FLAGS Flags,
  [out] PHANDLE            ProtectedHandle
);

Parameter-parameternya

[in] FilePath

Jalur yang sepenuhnya memenuhi syarat ke file atau direktori yang akan dibuka.

[in] Flags

Bendera untuk menentukan izin saat membuka file. Bendera dapat diatur ke kombinasi nilai berikut:

• Jika CF_OPEN_FILE_FLAG_EXCLUSIVE ditentukan, API mengembalikan handel share-none dan meminta RH (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock pada file; jika tidak, handel share-all dibuka dan R (OPLOCK_LEVEL_CACHE_READ) diminta.

  1. Jika CF_OPEN_FILE_FLAG_EXCLUSIVE ditentukan, yang terbuka adalah "share none" dan mendapatkan (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
     • Panggilan CreateFile normal yang terbuka untuk salah satu FILE_EXECUTE | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (atau salah satu/kedua GENERIC_READ | GENERIC_WRITE) akan merusak oplock karena konflik berbagi. Pemilik oplock akan menyelesaikan dan mengakui.
  2. Jika CF_OPEN_FILE_FLAG_EXCLUSIVE tidak ditentukan, yang terbuka adalah "bagikan semua" dan mendapatkan oplock OPLOCK_LEVEL_CACHE_READ.
     • Panggilan CreateFile normal tidak akan merusak oplock.
     • Jika CreateFile normal menentukan mode berbagi yang bertentangan dengan akses handel Cf (misalnya, jika CreateFile normal tidak menentukan FILE_SHARE_READ), CreateFile normal akan gagal dengan ERROR_SHARING_VIOLATION.
     • Oplock tidak pecah sampai pemanggil lain mengeluarkan I/O yang bertentangan, seperti tulis. Ketika itu terjadi, hentian oplock hanyalah saran.

• Jika CF_OPEN_FILE_FLAG_WRITE_ACCESS ditentukan, API mencoba membuka file atau direktori dengan/FILE_READ_DATA FILE_LIST_DIRECTORY dan FILE_WRITE_DATA/ aksesFILE_ADD_FILE; jika tidak, API mencoba membuka file atau direktori dengan FILE_READ_DATA/FILE_LIST_DIRECTORY.

• Jika CF_OPEN_FILE_FLAG_DELETE_ACCESS ditentukan, API mencoba membuka file atau direktori dengan akses DELETE ; jika tidak, file akan terbuka secara normal.

• Jika CF_OPEN_FILE_FLAG_FOREGROUND ditentukan, CfOpenFileWithOplock tidak meminta oplock. Ini harus digunakan ketika pemanggil bertindak sebagai aplikasi latar depan. yaitu, mereka tidak peduli apakah handel file yang dibuat oleh API ini menyebabkan pelanggaran berbagi untuk penelepon lain, dan mereka tidak peduli tentang melanggar oplock apa pun yang mungkin sudah ada di file. Jadi, mereka membuka handel tanpa meminta oplock.

  Nota

  Perilaku latar belakang default meminta oplock saat membuka handel file sehingga panggilan mereka gagal jika sudah ada oplock, dan mereka dapat diberitahu untuk menutup handel mereka jika mereka perlu keluar dari jalan untuk menghindari menyebabkan pelanggaran berbagi nanti.

  Kecuali pemanggil menentukan CF_OPEN_FILE_FLAG_EXCLUSIVE ke CfOpenFileWithOplock, oplock yang mereka dapatkan hanya akan OPLOCK_LEVEL_CACHE_READ, bukan (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), sehingga tidak akan ada perlindungan pelanggaran berbagi yang mungkin diinginkan aplikasi latar belakang.

[out] ProtectedHandle

Handel buram ke file atau direktori yang baru saja dibuka. Perhatikan bahwa ini bukan handel Win32 normal dan karenanya tidak dapat digunakan dengan API non-CfApi Win32 secara langsung.

Mengembalikan nilai

Jika fungsi ini berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT.

Komentar

Ketika oplock rusak, API akan menangani pemberitahuan pemutusan secara otomatis atas nama pemanggil dengan menguras semua permintaan aktif dan kemudian menutup handel Win32 yang mendasarinya.

Ini bertujuan untuk menghapus kompleksitas yang terkait dengan penggunaan oplock. Pemanggil harus menutup handel yang dikembalikan oleh CfOpenFileWithOplock dengan CfCloseHandle.

Aplikasi latar belakang biasanya ingin beroperasi secara transparan pada file. Secara khusus, mereka ingin menghindari menyebabkan pelanggaran berbagi kepada pembuka (latar depan) lainnya. Untuk melakukannya, mereka mengambil (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, seperti akan diberikan dengan menggunakan CF_OPEN_FILE_FLAG_EXCLUSIVE dengan CfOpenFileWithOplock. Jika pembuka lain kemudian datang bersama yang mode berbagi/akses yang diminta bertentangan dengan aplikasi latar belakang, maka oplock aplikasi latar belakang akan berhenti. Ini meminta aplikasi latar belakang untuk menutup handel filenya (untuk handel Cf, yang menyebabkannya menjadi tidak valid - handel yang mendasar sebenarnya telah ditutup). Setelah aplikasi latar belakang menutup handelnya, pembuka lainnya terbuka melanjutkan tanpa mengalami pelanggaran berbagi. Ini semua berfungsi karena bagian yang OPLOCK_LEVEL_CACHE_HANDLE dari oplock. Tanpa CF_OPEN_FILE_FLAG_EXCLUSIVE, oplock hanya memiliki perlindungan OPLOCK_LEVEL_CACHE_READ, sehingga perlindungan pelanggaran berbagi yang dijelaskan tidak terjadi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10, versi 1709 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2016 [hanya aplikasi desktop]
Platform Target	Windows
Header	cfapi.h
Perpustakaan	CldApi.lib
DLL	CldApi.dll

Lihat juga

CfCloseHandle

CreateFile