SetFileInformationByHandle 函式 (fileapi.h)

發行項
03/14/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 通訊協定	Yes
SMB 3.0 透明容錯移轉 (TFO)	請參閱批註
具有向外延展檔案共用的 SMB 3.0 (SO)	請參閱批註
叢集共用磁片區檔案系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	Yes

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。