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 |删除 (或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，以便如果已有 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
Library CldApi.lib
DLL CldApi.dll

另请参阅

CfCloseHandle

CreateFile