CfOpenFileWithOplock 函式 (cfapi.h)

針對一般和佔位符檔案開啟異步不透明句柄，) 檔案或佔位符檔案 (，並根據開啟旗標設定適當的 oplock。

語法

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

參數

[in] FilePath

要開啟之檔案或目錄的完整路徑。

[in] Flags

用來指定開啟檔案許可權的旗標。 旗標 可以設定為下列值的組合：

• 如果指定 CF_OPEN_FILE_FLAG_EXCLUSIVE，API 會傳回共用無句柄，並要求 RH (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) 檔案上的 oplock;否則會開啟共用句柄，並要求 R (OPLOCK_LEVEL_CACHE_READ) 。

  1. 如果指定 CF_OPEN_FILE_FLAG_EXCLUSIVE ，則開啟為「共用無」，且會取得 (OPLOCK_LEVEL_CACHE_READ |OPLOCK_LEVEL_CACHE_HANDLE) oplock。
     • 針對任何FILE_EXECUTE開啟的一般 CreateFile 呼叫 |FILE_READ_DATA |FILE_WRITE_DATA |FILE_APPEND_DATA |DELETE (或兩者皆GENERIC_READ |GENERIC_WRITE) 会因为共享冲突而中断作业。 oplock 擁有者將會完成並認可。
  2. 如果未指定 CF_OPEN_FILE_FLAG_EXCLUSIVE ，則開啟為「全部共用」，並取得OPLOCK_LEVEL_CACHE_READ oplock。
     • 一般的 CreateFile 呼叫不會中斷 oplock。
     • 如果一般 CreateFile 指定與 Cf 句柄存取 (衝突的共用模式，例如，如果一般 CreateFile 未指定FILE_SHARE_READ) ，則一般的 CreateFile 將會失敗並ERROR_SHARING_VIOLATION。
     • 除非其他呼叫端發出衝突的 I/O，例如寫入，否則 oplock 不會中斷。 發生這種情況時，只會諮詢 oplock 中斷。

• 如果指定 了CF_OPEN_FILE_FLAG_WRITE_ACCESS，API 會嘗試以 FILE_READ_DATA/FILE_LIST_DIRECTORY 開啟檔案或目錄，並 FILE_WRITE_DATA/FILE_ADD_FILE 存取;否則 API 會嘗試以 FILE_READ_DATA/FILE_LIST_DIRECTORY開啟檔案或目錄。

• 如果指定 CF_OPEN_FILE_FLAG_DELETE_ACCESS，API 會嘗試開啟具有 DELETE 存取權的檔案或目錄;否則會正常開啟檔案。

• 如果指定CF_OPEN_FILE_FLAG_FOREGROUND，CfOpenFileWithOplock 不會要求 oplock。 當呼叫端做為前景應用程式時，應該使用此功能。 亦即，他們不小心此 API 所建立的檔案句柄是否造成其他呼叫端的共享違規，而且不小心中斷任何可能已經在檔案上的作業鎖定。 因此，他們會開啟句柄，而不要求 oplock。

  注意

  開啟檔案句柄時，預設 背景 行為會要求 oplock，以便在已經有 oplock 時呼叫失敗，而且如果需要避免稍後發生共用違規，可以告知他們關閉其句柄。

  除非呼叫端指定對 CfOpenFileWithOplock的CF_OPEN_FILE_FLAG_EXCLUSIVE，否則它們取得的 oplock 只會OPLOCK_LEVEL_CACHE_READ，而不是 (OPLOCK_LEVEL_CACHE_READ |OPLOCK_LEVEL_CACHE_HANDLE) ，因此背景應用程式通常不會有共用違規保護。

[out] ProtectedHandle

剛開啟之檔案或目錄的不透明句柄。 請注意，這不是一般的 Win32 句柄，因此無法直接搭配非 CfApi Win32 API 使用。

傳回值

如果函式成功，則會傳 S_OK回 。 否則，它會傳回 HRESULT 錯誤碼。

備註

當 oplock 中斷時，API 會清空所有作用中要求，然後關閉基礎 Win32 句柄，以代表呼叫端自動處理中斷通知。

這旨在移除與 oplock 使用量相關的複雜度。 呼叫端必須使用 CfCloseHandle 關閉 CfOpenFileWithOplock 所傳回的句柄。

背景應用程式通常想要以透明方式在檔案上運作。 特別是，他們想要避免對其他 (前景) 開啟者造成共享違規。 若要這樣做，他們需要 (OPLOCK_LEVEL_CACHE_READ |OPLOCK_LEVEL_CACHE_HANDLE) oplock，例如搭配 CfOpenFileWithOplock 使用 CF_OPEN_FILE_FLAG_EXCLUSIVE來授與。 如果後續還有另一個開啟者，其要求的共用/存取模式與背景應用程式的 衝突，則背景應用程式的 oplock 會中斷。 這會提示背景應用程式關閉其檔案句柄 (，使它變成無效 –實際基礎句柄已關閉) 。 背景應用程式關閉其句柄之後，另一個開啟者的開啟會繼續進行，而不會發生共享違規。 這全都是因為 oplock 的OPLOCK_LEVEL_CACHE_HANDLE部分而運作。 若沒有CF_OPEN_FILE_FLAG_EXCLUSIVE，oplock 僅具有OPLOCK_LEVEL_CACHE_READ保護，因此不會發生所述的共用違規保護。

規格需求

另請參閱

CfCloseHandle

CreateFile