Функция 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, файлу потребуется доступ DELETE , запрошенный в вызове функции CreateFile . Пример см. в разделе Пример кода. Дополнительные сведения о разрешениях на доступ к файлам см. в разделе Безопасность файлов и права доступа.

Если к дескрипторе привязана транзакция, то внесенные изменения будут выполняться для классов сведений FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo и FileDispositionInfo. Если указан параметр FileDispositionInfo , операция удаления выполняется только в том случае, если была запрошена операция DeleteFile . В этом случае, если транзакция не зафиксирована до закрытия дескриптора, удаление не произойдет. Дополнительные сведения о TxF см. в разделе Transactional NTFS (TxF).

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (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
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib; ФайлExtd.lib в Windows Server 2003 и Windows XP
DLL	Kernel32.dll
Распространяемые компоненты	Windows SDK в Windows Server 2003 и Windows XP.