setFileInformationByHandle 函数 (fileapi.h)
设置指定文件的文件信息。
若要使用文件句柄检索文件信息,请参阅 GetFileInformationByHandle 或 GetFileInformationByHandleEx。
语法
BOOL SetFileInformationByHandle(
[in] HANDLE hFile,
[in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
[in] LPVOID lpFileInformation,
[in] DWORD dwBufferSize
);
参数
[in] hFile
要更改其信息的文件的句柄。
必须使用请求的更改的适当权限打开此句柄。 有关详细信息,请参阅备注和示例代码部分。
此句柄不应是管道句柄。
[in] FileInformationClass
一个FILE_INFO_BY_HANDLE_CLASS枚举值,该值指定要更改的信息的类型。
有关有效值的表,请参阅“备注”部分。
[in] lpFileInformation
指向缓冲区的指针,该缓冲区包含指定文件信息类要更改的信息。 此参数指向的结构对应于 FileInformationClass 指定的类。
有关有效结构类型的表,请参阅“备注”部分。
[in] dwBufferSize
lpFileInformation 的大小(以字节为单位)。
返回值
如果成功,则返回非零值,否则返回零。
要获得更多的错误信息,请调用 GetLastError。
注解
某些文件信息类在不同操作系统版本中的行为略有不同。 基础驱动程序支持这些类,它们返回的任何信息都可能会在操作系统版本之间发生更改。
下表显示了用于此函数的有效文件信息类及其相应的数据结构类型。
FileInformationClass 值 | lpFileInformation 类型 |
---|---|
FileBasicInfo
0 |
|
FileRenameInfo
3 |
|
FileDispositionInfo
4 |
|
FileAllocationInfo
5 |
|
FileEndOfFileInfo
6 |
|
FileIoPriorityHintInfo
12 |
创建用于 SetFileInformationByHandle 的文件句柄时,必须指定适当的访问标志。 例如,如果应用程序使用 FILE_DISPOSITION_INFO,且 DeleteFile 成员设置为 TRUE,则该文件将需要在调用 CreateFile 函数时请求的 DELETE 访问权限。 若要查看此示例,请参阅示例代码部分。 有关文件权限的详细信息,请参阅 文件安全和访问权限。
如果存在绑定到句柄的事务,则将为信息类 FileBasicInfo、FileRenameInfo、FileAllocationInfo、FileEndOfFileInfo 和 FileDispositionInfo 事务处理所做的更改。 如果指定 了 FileDispositionInfo ,则仅当请求 DeleteFile 操作时,才会处理删除操作。 在这种情况下,如果在关闭句柄之前未提交事务,则不会进行删除。 有关 TxF 的详细信息,请参阅 事务 NTFS (TxF) 。
在 Windows 8 和 Windows Server 2012 中,此函数由以下技术支持。
技术 | 支持 |
---|---|
服务器消息块 (SMB) 3.0 协议 | 是 |
SMB 3.0 透明故障转移 (TFO) | 查看注释 |
具有横向扩展文件共享的 SMB 3.0 (SO) | 查看注释 |
群集共享卷文件系统 (CSV) | 是 |
弹性文件系统 (ReFS) | 是 |
SMB 3.0 不支持重命名具有连续可用性功能的文件共享上的备用数据流。
示例
下面的 C++ 示例演示如何创建文件,并在关闭句柄时将其标记为删除。
//...
HANDLE hFile = CreateFile( TEXT("tempfile"),
GENERIC_READ | GENERIC_WRITE | DELETE,
0 /* exclusive access */,
NULL,
CREATE_ALWAYS,
0,
NULL);
if (hFile != INVALID_HANDLE_VALUE)
{
FILE_DISPOSITION_INFO fdi;
fdi.DeleteFile = TRUE; // marking for deletion
BOOL fResult = SetFileInformationByHandle( hFile,
FileDispositionInfo,
&fdi,
sizeof(FILE_DISPOSITION_INFO) );
if (fResult)
{
// File will be deleted upon CloseHandle.
_tprintf( TEXT("SetFileInformationByHandle marked tempfile for deletion\n") );
// ...
// Now use the file for whatever temp data storage you need,
// it will automatically be deleted upon CloseHandle or
// application termination.
// ...
}
else
{
_tprintf( TEXT("error %lu: SetFileInformationByHandle could not mark tempfile for deletion\n"),
GetLastError() );
}
CloseHandle(hFile);
// At this point, the file is closed and deleted by the system.
}
else
{
_tprintf( TEXT("error %lu: could not create tempfile\n"),
GetLastError() );
}
//...
要求
最低受支持的客户端 | Windows Vista [桌面应用 | UWP 应用] |
最低受支持的服务器 | Windows Server 2008 [桌面应用 | UWP 应用] |
目标平台 | Windows |
标头 | fileapi.h (包括 Windows.h) |
Library | Kernel32.lib;Windows Server 2003 和 Windows XP 上的 FileExtd.lib |
DLL | Kernel32.dll |
可再发行组件 | Windows Server 2003 和 Windows XP 上的 Windows SDK。 |