ReadFileEx 함수(fileapi.h)

아티클
08/23/2023

지정된 파일 또는 I/O(입력/출력) 디바이스에서 데이터를 읽습니다. 읽기가 완료 또는 취소되고 호출 스레드가 경고 대기 상태에 있을 때 완료 상태를 비동기적으로 보고하고, 지정된 완료 루틴을 호출합니다.

파일 또는 디바이스에서 데이터를 동기적으로 읽으려면 ReadFile 함수를 사용합니다.

구문

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [in, out]       LPOVERLAPPED                    lpOverlapped,
  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

매개 변수

[in] hFile

파일 또는 I/O 디바이스에 대한 핸들(예: 파일, 파일 스트림, 물리적 디스크, 볼륨, 콘솔 버퍼, 테이프 드라이브, 소켓, 통신 리소스, mailslot 또는 파이프).

이 매개 변수는 CreateFile 함수에서 FILE_FLAG_OVERLAPPED 플래그로 연 핸들 또는 소켓 또는 accept 함수에서 반환된 소켓 핸들일 수 있습니다.

또한 이 핸들에는 GENERIC_READ 액세스 권한이 있어야 합니다. 액세스 권한에 대한 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

[out, optional] lpBuffer

파일 또는 디바이스에서 읽은 데이터를 수신하는 버퍼에 대한 포인터입니다.

이 버퍼는 읽기 작업 기간 동안 유효한 상태를 유지해야 합니다. 애플리케이션은 읽기 작업이 완료될 때까지 이 버퍼를 사용하면 안 됩니다.

[in] nNumberOfBytesToRead

읽을 바이트 수입니다.

[in, out] lpOverlapped

비동기(겹치는) 파일 읽기 작업 중에 사용할 데이터를 제공하는 OVERLAPPED 데이터 구조에 대한 포인터입니다.

바이트 오프셋을 지원하는 파일의 경우 파일에서 읽기를 시작할 바이트 오프셋을 지정해야 합니다. OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버를 설정하여 이 오프셋을 지정합니다. 바이트 오프셋을 지원하지 않는 파일 또는 디바이스의 경우 Offset 및 OffsetHigh 는 무시됩니다.

ReadFileEx 함수는 OVERLAPPED 구조체의 hEvent 멤버를 무시합니다. 애플리케이션은 ReadFileEx 호출의 컨텍스트에서 자체 용도로 해당 멤버를 자유롭게 사용할 수 있습니다. ReadFileEx 는 lpCompletionRoutine이 가리키는 완료 루틴을 호출하거나 큐에 대기하여 읽기 작업의 완료를 알리므로 이벤트 핸들이 필요하지 않습니다.

ReadFileEx 함수는 OVERLAPPED 구조체의 내부 및 InternalHigh 멤버를 사용합니다. 애플리케이션에서 이러한 멤버를 설정해서는 안 됩니다.

OVERLAPPED 데이터 구조는 읽기 작업 기간 동안 유효한 상태를 유지해야 합니다. 읽기 작업이 완료 보류 중인 동안 scope 벗어날 수 있는 변수가 되어서는 안 됩니다.

[in] lpCompletionRoutine

읽기 작업이 완료되고 호출 스레드가 경고 가능한 대기 상태에 있을 때 호출할 완료 루틴에 대한 포인터입니다. 완료 루틴에 대한 자세한 내용은 FileIOCompletionRoutine을 참조하세요.

반환 값

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

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

함수가 성공하면 호출 스레드에 파일의 겹치는 읽기 작업인 보류 중인 비동기 I/O 작업이 있습니다. 이 I/O 작업이 완료되고 호출 스레드가 경고 가능한 대기 상태로 차단되면 시스템은 lpCompletionRoutine이 가리키는 함수를 호출하고 대기 상태는 WAIT_IO_COMPLETION 반환 코드로 완료됩니다.

함수가 성공하고 파일 읽기 작업이 완료되었지만 호출 스레드가 경고 가능한 대기 상태가 아닌 경우 시스템은 완료 루틴 호출을 큐에 대기하고 호출 스레드가 경고 가능한 대기 상태가 될 때까지 호출을 유지합니다. 경고 대기 및 겹치는 입력/출력 작업에 대한 자세한 내용은 동기화 정보를 참조하세요.

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

설명

ReadFileEx를 사용하는 경우 함수가 "성공"을 반환하여 "성공"이지만 알고 싶은 결과가 있는 조건에 대해 검사 경우에도 GetLastError를 검사 합니다. 예를 들어 ReadFileEx 를 호출할 때 버퍼 오버플로는 TRUE를 반환하지만 GetLastError 는 ERROR_MORE_DATA 오버플로를 보고합니다. 함수 호출에 성공하고 경고 조건이 없는 경우 GetLastError 는 ERROR_SUCCESS 반환합니다.

미해결 비동기 I/O 요청이 너무 많은 경우 ReadFileEx 함수가 실패할 수 있습니다. 이러한 오류가 발생할 경우 GetLastError 는 ERROR_INVALID_USER_BUFFER 반환하거나 ERROR_NOT_ENOUGH_MEMORY 수 있습니다.

보류 중인 모든 비동기 I/O 작업을 취소하려면 다음 중 하나를 사용합니다.

CancelIo - 이 함수는 지정된 파일 핸들에 대해 호출 스레드에서 실행한 작업만 취소합니다.
CancelIoEx - 이 함수는 지정된 파일 핸들에 대해 스레드에서 실행한 모든 작업을 취소합니다.

보류 중인 동기 I/O 작업을 취소하려면 CancelSynchronousIo를 사용하세요.

취소된 I/O 작업은 오류 ERROR_OPERATION_ABORTED 완료됩니다.

hFile에 지정된 파일의 일부가 다른 프로세스에 의해 잠겨 있고 ReadFileEx 호출에 지정된 읽기 작업이 잠긴 부분과 겹치면 ReadFileEx 호출이 실패합니다.

버퍼가 너무 작은 mailslot에서 데이터를 읽으려고 하면 ReadFileEx 는 FALSE를 반환하고 GetLastError 는 ERROR_INSUFFICIENT_BUFFER 반환합니다.

읽기 작업이 버퍼를 사용하는 동안 입력 버퍼에 액세스하면 해당 버퍼로 읽은 데이터가 손상될 수 있습니다. 애플리케이션은 읽기 작업이 완료될 때까지 읽기 작업에서 사용하는 입력 버퍼를 읽거나, 쓰거나, 재할당하거나, 해제해서는 안 됩니다.

애플리케이션은 MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx 및 SleepEx 함수를 사용하여 경고 대기 상태를 입력합니다. 경고 대기 및 겹치는 입력/출력에 대한 자세한 내용은 동기화 정보를 참조하세요.

FILE_FLAG_NO_BUFFERING 사용하여 CreateFile에서 열린 파일을 성공적으로 사용하기 위한 엄격한 요구 사항이 있습니다. 자세한 내용은 파일 버퍼링을 참조하세요.

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

거래된 작업

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

예제

예를 들어 완료 루틴을 사용하여 명명된 파이프 서버를 참조하세요.

요구 사항

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