setFileInformationByHandle 函数 (fileapi.h)

设置指定文件的文件信息。

若要使用文件句柄检索文件信息,请参阅 GetFileInformationByHandleGetFileInformationByHandleEx

语法

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

FILE_BASIC_INFO

FileRenameInfo

3

FILE_RENAME_INFO

FileDispositionInfo

4

FILE_DISPOSITION_INFO

FileAllocationInfo

5

FILE_ALLOCATION_INFO

FileEndOfFileInfo

6

FILE_END_OF_FILE_INFO

FileIoPriorityHintInfo

12

FILE_IO_PRIORITY_HINT_INFO

 

创建用于 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。

请参阅

CreateFile

文件管理函数

文件安全和访问权限

通用访问权限

GetFileInformationByHandle

GetFileInformationByHandleEx