Fungsi SetFileInformationByHandle (fileapi.h)

Artikel
03/14/2023

Menyetel informasi file untuk file yang ditentukan.

Untuk mengambil informasi file menggunakan handel file, lihat GetFileInformationByHandle atau GetFileInformationByHandleEx.

Sintaks

BOOL SetFileInformationByHandle(
  [in] HANDLE                    hFile,
  [in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
  [in] LPVOID                    lpFileInformation,
  [in] DWORD                     dwBufferSize
);

Parameter

[in] hFile

Handel ke file untuk mengubah informasi.

Handel ini harus dibuka dengan izin yang sesuai untuk perubahan yang diminta. Untuk informasi selengkapnya, lihat bagian Keterangan dan Contoh Kode.

Handel ini seharusnya bukan handel pipa.

[in] FileInformationClass

Nilai enumerasi FILE_INFO_BY_HANDLE_CLASS yang menentukan jenis informasi yang akan diubah.

Untuk tabel nilai yang valid, lihat bagian Keterangan.

[in] lpFileInformation

Penunjuk ke buffer yang berisi informasi yang akan diubah untuk kelas informasi file yang ditentukan. Struktur yang dituju parameter ini sesuai dengan kelas yang ditentukan oleh FileInformationClass.

Untuk tabel jenis struktur yang valid, lihat bagian Keterangan.

[in] dwBufferSize

Ukuran lpFileInformation, dalam byte.

Nilai kembali

Mengembalikan bukan nol jika berhasil atau nol sebaliknya.

Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Kelas informasi file tertentu berperilaku sedikit berbeda pada rilis sistem operasi yang berbeda. Kelas-kelas ini didukung oleh driver yang mendasar, dan informasi apa pun yang mereka kembalikan dapat berubah di antara rilis sistem operasi.

Tabel berikut ini memperlihatkan kelas informasi file yang valid dan jenis struktur data terkait untuk digunakan dengan fungsi ini.

Nilai FileInformationClass	Jenis 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

Anda harus menentukan bendera akses yang sesuai saat membuat handel file untuk digunakan dengan SetFileInformationByHandle. Misalnya, jika aplikasi menggunakan FILE_DISPOSITION_INFO dengan anggota DeleteFile diatur ke TRUE, file akan memerlukan akses DELETE yang diminta dalam panggilan ke fungsi CreateFile . Untuk melihat contoh ini, lihat bagian Contoh Kode. Untuk informasi selengkapnya tentang izin file, lihat Keamanan File dan Hak Akses.

Jika ada transaksi yang terikat pada handel, maka perubahan yang dilakukan akan ditransaksikan untuk kelas informasi FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo, dan FileDispositionInfo. Jika FileDispositionInfo ditentukan, hanya operasi penghapusan yang ditransaksikan jika operasi DeleteFile diminta. Dalam hal ini, jika transaksi tidak dilakukan sebelum handel ditutup, penghapusan tidak akan terjadi. Untuk informasi selengkapnya tentang TxF, lihat Transactional NTFS (TxF).

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Lihat komentar
SMB 3.0 dengan Scale-out File Shares (SO)	Lihat komentar
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

SMB 3.0 tidak mendukung penggantian nama aliran data alternatif pada berbagi file dengan kemampuan ketersediaan berkelanjutan.

Contoh

Contoh C++ berikut menunjukkan cara membuat file dan menandainya untuk dihapus saat handel ditutup.

//...
  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() );
 }
//...

Persyaratan


Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib; FileExtd.lib di Windows Server 2003 dan Windows XP
DLL	Kernel32.dll
Redistribusi	Windows SDK di Windows Server 2003 dan Windows XP.