ReadFileScatter 함수(fileapi.h)

아티클
01/10/2024

파일에서 데이터를 읽고 버퍼 배열에 저장합니다.

함수는 OVERLAPPED 구조체로 지정된 위치에서 파일에서 데이터를 읽기 시작합니다. ReadFileScatter 함수는 비동기적으로 작동합니다.

구문

BOOL ReadFileScatter(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToRead,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

매개 변수

[in] hFile

읽을 파일에 대한 핸들입니다.

파일 핸들은 GENERIC_READ 오른쪽 및 FILE_FLAG_OVERLAPPED 및 FILE_FLAG_NO_BUFFERING 플래그를 사용하여 만들어야 합니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

[in] aSegmentArray

데이터를 수신하는 FILE_SEGMENT_ELEMENT 구조 버퍼 배열에 대한 포인터입니다. 이 공용 구조체에 대한 설명은 비고를 참조하세요.

각 요소는 데이터의 한 페이지를 나타냅니다.

참고

시스템 페이지의 크기를 확인하려면 GetSystemInfo를 사용합니다.

배열에는 nNumberOfBytesToRead 데이터 바이트를 나타내는 데 충분한 요소가 포함되어야 합니다. 예를 들어 읽을 40KB가 있고 페이지 크기가 4KB인 경우 배열에는 10개 요소가 있어야 합니다.

각 버퍼는 시스템 메모리 페이지의 크기 이상이어야 하며 시스템 메모리 페이지 크기 경계에 맞춰야 합니다. 시스템은 각 버퍼에 하나의 시스템 메모리 데이터 페이지를 읽습니다.

함수는 데이터를 버퍼에 순차적으로 저장합니다. 예를 들어 데이터를 첫 번째 버퍼에 저장한 다음 두 번째 버퍼에 저장한 다음 각 버퍼가 채워지고 모든 데이터가 저장되거나 nNumberOfBytesToRead 바이트가 읽혀질 때까지 저장됩니다.

[in] nNumberOfBytesToRead

파일에서 읽을 총 바이트 수입니다. aSegmentArray의 각 요소에는 이 합계의 한 페이지 청크가 포함됩니다. FILE_FLAG_NO_BUFFERING 파일을 열어야 하므로 바이트 수는 파일이 있는 파일 시스템의 섹터 크기의 배수여야 합니다.

lpReserved

이 매개 변수는 나중에 사용하도록 예약되어 있으며 NULL이어야 합니다.

[in, out] lpOverlapped

OVERLAPPED 데이터 구조에 대한 포인터입니다.

ReadFileScatter 함수에는 유효한 OVERLAPPED 구조체가 필요합니다. lpOverlapped 매개 변수는 NULL일 수 없습니다.

ReadFileScatter 함수는 OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버에 의해 지정된 위치에서 파일에서 데이터를 읽기 시작합니다.

ReadFileScatter 함수는 읽기 작업이 완료되기 전에 반환할 수 있습니다. 이 시나리오에서 ReadFileScatter 함수는 값 0을 반환하고 GetLastError 함수는 ERROR_IO_PENDING 값을 반환합니다. ReadFileScatter의 이 비동기 작업을 사용하면 읽기 작업이 완료되는 동안 호출 프로세스를 계속할 수 있습니다. GetOverlappedResult, HasOverlappedIoCompleted 또는 GetQueuedCompletionStatus 함수를 호출하여 읽기 작업 완료에 대한 정보를 가져올 수 있습니다. 자세한 내용은 동기 및 비동기 I/O를 참조하세요.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError 함수를 호출합니다.

ReadFileScatter가 EOF(파일 끝)를 지나 읽으려고 하면 해당 작업에 대한 GetOverlappedResult 호출은 FALSE를 반환하고 GetLastError는 ERROR_HANDLE_EOF 반환합니다.

읽기 작업이 완료되기 전에 함수가 반환되면 함수는 0을 반환하고 GetLastError 는 ERROR_IO_PENDING 반환합니다.

설명

이 함수는 Itanium 기반 시스템의 WOW64에서 32비트 애플리케이션에 대해 지원되지 않습니다.

FILE_SEGMENT_ELEMENT 구조체는 다음과 같이 정의됩니다.

typedef union _FILE_SEGMENT_ELEMENT {
    PVOID64 Buffer;
    ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

버퍼 멤버에 포인터를 할당하면 코드가 32비트로 컴파일되는 경우 값이 로그 확장됩니다. 이렇게 하면 4기가바이트 튜닝으로 구성되거나 64비트 Windows의 WOW64에서 실행되는 시스템에서 실행되는 큰 주소 인식 애플리케이션이 중단됩니다. 따라서 버퍼에 포인터를 할당할 때 PtrToPtr64 매크로를 사용합니다.

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

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

거래된 작업

파일 핸들에 바인딩된 트랜잭션이 있는 경우 함수는 파일의 트랜잭션된 뷰에서 데이터를 반환합니다. 트랜잭션된 읽기 핸들은 핸들이 지속되는 동안 파일의 동일한 뷰를 표시하도록 보장됩니다.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll