通过

CfOpenFileWithOplock 函数 （cfapi.h）

打开文件或目录（对于普通文件和占位符文件）的异步不透明句柄，并根据打开的标志设置适当的作锁。

语法

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。 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，例如，将 CF_OPEN_FILE_FLAG_EXCLUSIVE 与 CfOpenFileWithOplock 一起使用来授予该作锁。 如果另一个打开程序随后出现其请求的共享/访问模式与后台应用的冲突，则后台应用的 oplock 中断。 这会提示后台应用关闭其文件句柄（对于 Cf 句柄，导致它变得无效 - 实际基础句柄已关闭）。 后台应用关闭其句柄后，另一个打开者的打开会继续，而不会遇到共享冲突。 这一切都是因为 oplock 的OPLOCK_LEVEL_CACHE_HANDLE部分。 如果没有CF_OPEN_FILE_FLAG_EXCLUSIVE，oplock 仅具有OPLOCK_LEVEL_CACHE_READ保护，因此所述的共享冲突保护不会发生。

要求

要求 价值
最低支持的客户端 Windows 10 版本 1709 [仅限桌面应用]
支持的最低服务器 Windows Server 2016 [仅限桌面应用]
目标平台 Windows操作系统
标头 cfapi.h
图书馆 CldApi.lib
DLL CldApi.dll

另请参阅

CfCloseHandle

CreateFile