setFileInformationByHandle 函数 (fileapi.h)

项目
08/23/2023

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

若要使用文件句柄检索文件信息，请参阅 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	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。