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)	請參閱批註
叢集共用磁片區檔案系統 (CsvFS)	是
彈性檔案系統 (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)
程式庫	Kernel32.lib;Windows Server 2003 和 Windows XP 上的 FileExtd.lib
DLL	Kernel32.dll
可轉散發套件	Windows Server 2003 和 Windows XP 上的 Windows SDK。