OpenFileById 函数 (winbase.h)

打开与指定标识符匹配的文件。

语法

HANDLE OpenFileById(
  [in]           HANDLE                hVolumeHint,
  [in]           LPFILE_ID_DESCRIPTOR  lpFileId,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwFlagsAndAttributes
);

参数

[in] hVolumeHint

存储要打开的文件的卷或共享上任何文件的句柄。

[in] lpFileId

指向标识要打开的文件 的FILE_ID_DESCRIPTOR 的指针。

[in] dwDesiredAccess

对 对象的访问。 访问权限可以是读取和/或写入。

有关详细信息,请参阅 文件安全性和访问权限。 不能请求与具有打开句柄的打开请求中指定的共享模式冲突的访问模式。

如果此参数为零 (0) ,则应用程序可以在不访问设备的情况下查询文件和设备属性。 这对于应用程序确定软盘驱动器的大小及其支持的格式很有用,而无需在驱动器中使用软盘。 它还可用于测试文件或目录是否存在,而无需打开文件或目录进行读取或写入访问。

[in] dwShareMode

对象的共享模式,可以是读取、写入、两者或无。

不能请求与具有打开句柄的打开请求中指定的访问模式冲突的共享模式,因为这将导致以下共享冲突: (ERROR_SHARING_VIOLATION) 。 有关详细信息,请参阅创建和打开文件

如果此参数为零 (0) 并且 OpenFileById 成功,则对象不能共享,并且不能再次打开,直到句柄关闭。 有关详细信息,请参阅本主题的“备注”部分。

共享选项一直有效,直到你关闭对象的句柄。

若要使进程能够在另一个进程打开对象时共享对象,请使用以下一个或多个值的组合来指定他们可以请求打开对象的访问模式。

含义
FILE_SHARE_DELETE
0x00000004
启用对对象的后续打开操作以请求删除访问权限。

否则,如果其他进程请求删除访问权限,则无法打开对象。

如果未指定此标志,但已打开对象进行删除访问,则函数将失败。

FILE_SHARE_READ
0x00000001
对对象启用后续打开操作以请求读取访问权限。

否则,如果其他进程请求读取访问权限,则无法打开对象。

如果未指定此标志,但已打开对象进行读取访问,则函数将失败。

FILE_SHARE_WRITE
0x00000002
启用对对象的后续打开操作以请求写入访问权限。

否则,如果其他进程请求写入访问权限,则无法打开对象。

如果未指定此标志,但已打开对象进行写入访问或具有具有写入访问权限的文件映射,则函数将失败。

[in, optional] lpSecurityAttributes

保留。

[in] dwFlagsAndAttributes

文件标志。

当 OpenFileById 打开文件时,它会将文件标志与现有文件属性合并,并忽略提供的任何文件属性。 此参数可以包括以下标志的任意组合。

含义
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
正在为备份或还原操作打开文件。 当进程具有 SE_BACKUP_NAMESE_RESTORE_NAME 特权时,系统会确保调用进程替代文件安全检查。 有关详细信息,请参阅 更改令牌中的权限

必须设置此标志才能获取目录的句柄。 目录句柄可以传递给某些函数,而不是文件句柄。 有关详细信息,请参阅 目录句柄

FILE_FLAG_NO_BUFFERING
0x20000000
系统打开一个没有系统缓存的文件。 此标志不会影响硬盘缓存。 与 FILE_FLAG_OVERLAPPED 结合使用时,标志可提供最大的异步性能,因为 I/O 不依赖于内存管理器的同步操作。 但是,某些 I/O 操作需要更多时间,因为数据不会保留在缓存中。 此外,仍可能缓存文件元数据。 要将元数据刷新到磁盘,请使用 FlushFileBuffers 函数。

使用 使用 FILE_FLAG_NO_BUFFERING 打开的文件时,应用程序必须满足某些要求:

  • 文件访问必须从文件中的字节偏移量开始,该文件是卷扇区大小的整数倍数。
  • 对于卷扇区大小的整数倍数的字节数,文件访问必须为 。 例如,如果扇区大小为 512 字节,则应用程序可以请求读取和写入 512、1024、1536 或 2048 字节,但不能请求 335、981 或 7171 字节。
  • 读取和写入操作的缓冲区地址应按扇区对齐,这意味着在内存中为卷扇区大小的整数倍的地址上对齐。 可能不会强制实施此要求,具体取决于磁盘。
在卷扇区大小的整数倍数上对齐缓冲区的一种方法是使用 VirtualAlloc 分配缓冲区。 它分配在地址上对齐的内存,这些地址是操作系统内存页大小的整数倍数。 由于内存页和卷扇区大小均为 2 的幂,因此此内存也与卷扇区大小的整数倍数的地址对齐。 内存页大小为 4-8 KB;扇区 (硬盘) 为 512 字节, (CD) 为 2048 字节,因此卷扇区永远不能大于内存页。

应用程序可以通过调用 GetDiskFreeSpace 函数来确定卷扇区大小。

FILE_FLAG_OPEN_NO_RECALL
0x00100000
请求文件数据,但它应继续位于远程存储中。 不应将其传输回本地存储。 此标志供远程存储系统使用。
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
使用此标志时,不会进行正常的 重新分析点 处理, 并且 OpenFileById 会尝试打开重新分析点。 打开文件时,无论控制重分析点的筛选器是否正常运行,都返回文件句柄。 此标志不能与 CREATE_ALWAYS 标志一起使用。 如果文件不是重分析点,则忽略此标志。
FILE_FLAG_OVERLAPPED
0x40000000
文件是针对异步 I/O 打开或创建的。 操作完成后,在 OVERLAPPED 结构中为调用指定的事件将设置为信号状态。 处理需要大量时间的操作会返回 ERROR_IO_PENDING

如果指定了此标志,则文件可用于同时读取和写入操作。 系统不维护文件指针,因此必须将文件位置传递给 OVERLAPPED 结构中的读取和写入函数或更新文件指针。

如果未指定此标志,则 I/O 操作将序列化,即使对读取和写入函数的调用指定 了 OVERLAPPED 结构也是如此。

FILE_FLAG_RANDOM_ACCESS
0x10000000
随机访问文件。 系统可将此选项用作优化文件缓存的提示。
FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
从开头到末尾顺序访问文件。 系统可将此选项用作优化文件缓存的提示。 如果应用程序移动文件指针进行随机访问,则可能不会进行最佳缓存。 但是,仍能保证正确的操作。

指定此标志可以提高使用顺序访问读取大型文件的应用程序的性能。 对于主要按顺序读取大型文件,但偶尔跳过较小字节范围的应用程序,性能提升可能更为明显。

FILE_FLAG_WRITE_THROUGH
0x80000000
系统通过任何中间缓存进行写入,并直接进入磁盘。

如果未同时指定 FILE_FLAG_NO_BUFFERING ,则系统缓存生效,则数据将写入系统缓存,但会立即刷新到磁盘。

如果还指定 了FILE_FLAG_NO_BUFFERING ,则系统缓存无效,则数据会立即刷新到磁盘,而无需通过系统缓存。 操作系统还会请求通过硬盘缓存写入永久性媒体。 但是,并非所有硬件都支持这种写通功能。

返回值

如果函数成功,则返回值为指定文件的打开句柄。

如果函数失败,则返回值为 INVALID_HANDLE_VALUE。 要获得更多的错误信息,请调用 GetLastError。

注解

使用 CloseHandle 函数关闭 OpenFileById 返回的对象句柄。

如果对由于上次调用 DeleteFile 而挂起删除的文件调用 OpenFileById,则函数将失败。 操作系统会延迟文件删除,直到文件的所有句柄关闭。 GetLastError 返回 ERROR_ACCESS_DENIED

在 Windows 8 和 Windows Server 2012 中,此函数由以下技术支持。

技术 支持
服务器消息块 (SMB) 3.0 协议
SMB 3.0 透明故障转移 (TFO)
具有横向扩展文件共享的 SMB 3.0 (SO)
群集共享卷文件系统 (CSV)
弹性文件系统 (ReFS)

要求

   
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Kernel32.lib;Windows Server 2003 和 Windows XP 上的 FileExtd.lib
DLL Kernel32.dll
可再发行组件 Windows Server 2003 和 Windows XP 上的 Windows SDK。

另请参阅

ACCESS_MASK

CloseHandle

CreateFile

DeleteFile

FILE_ID_DESCRIPTOR

文件管理函数

GetFileInformationByHandleEx

GetOverlappedResult

OVERLAPPED

OpenFile

ReadFile

WriteFile