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、FileRenameInfoFileAllocationInfoFileEndOfFileInfoFileDispositionInfo進行變更。 如果指定 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。

另請參閱

CreateFile

檔案管理功能

檔案安全性和存取權限

一般存取權限

GetFileInformationByHandle

GetFileInformationByHandleEx