Функция SetFileInformationByHandle (fileapi.h)

Задает сведения о файле для указанного файла.

Сведения о файле с помощью дескриптора файла см. в разделе 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.

Комментарии

Некоторые классы сведений о файлах ведут себя немного иначе в разных выпусках операционной системы. Эти классы поддерживаются базовыми драйверами, и любая информация, которую они возвращают, может изменяться в разных выпусках операционной системы.

В следующей таблице показаны допустимые классы сведений о файлах и соответствующие типы структуры данных для использования с этой функцией.

При создании дескриптора файла для использования с 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 не поддерживает переименование альтернативных потоков данных в общих папках с возможностью непрерывной доступности.

Примеры

В следующем примере 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() );
 }
//...

Требования

См. также раздел

CreateFile

Функции управления файлами

Безопасность файлов и права доступа

Универсальные права доступа

GetFileInformationByHandle

GetFileInformationByHandleEx