SetFileInformationByHandle 함수(fileapi.h)

아티클
08/23/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의 크기(바이트)입니다.

반환 값

성공하면 0이 아닌 값을 반환하고 그렇지 않으면 0을 반환합니다.

확장 오류 정보를 가져오려면 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에 사용할 파일 핸들을 만들 때 적절한 액세스 플래그를 지정해야 합니다. 예를 들어 애플리케이션이 DeleteFile 멤버가 TRUE로 설정된 FILE_DISPOSITION_INFO 사용하는 경우 파일은 CreateFile 함수 호출에서 요청된 DELETE 액세스 권한이 필요합니다. 이 예제를 보려면 예제 코드 섹션을 참조하세요. 파일 권한에 대한 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

핸들에 바인딩된 트랜잭션이 있는 경우 변경된 내용은 정보 클래스 FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo, FileDispositionInfo에 대해 트랜잭션됩니다. FileDispositionInfo를 지정하면 DeleteFile 작업이 요청된 경우에만 삭제 작업이 트랜잭션됩니다. 이 경우 핸들을 닫기 전에 트랜잭션이 커밋되지 않으면 삭제가 발생하지 않습니다. TxF에 대한 자세한 내용은 TxFS(트랜잭션 NTFS)를 참조하세요.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	주석 참조
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	주석 참조
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	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.