ReadFile

ReadFile

파일로부터 데이터를 읽어냅니다.파일 포인터의 현재 위치가, 독해의 개시 위치가 됩니다.동기 독해 조작에서는, 독해 조작이 종료하면, 파일 핸들이 오버랩 속성 지정으로 작성되어 있지 않은 한, 파일 포인터의 위치는 실제로 읽어내진 데이터의 아르바이트수만큼 진행됩니다.비동기 독해 조작에서는, 어플리케이션측에서 파일 포인터를 조정할 필요가 있습니다.

BOOL ReadFile(
    HANDLE   hFile,                // 파일 핸들
    LPCVOID  pBuffer,              // 버퍼 주소
    DWORD    nNumberOfBytesToRead, // 사이즈
    LPDWORD  pNumberOfBytesRead,   // 실제의 사이즈를 격납하는 변수
    LPOVERLAPPED  pOverlapped      // OVERLAPPED구조체
);

KERNEL32.DLL

인수

hFile

독해처의 파일의 핸들을 지정합니다.파일 핸들은 CreateFile 함수로 취득할 수 있습니다.이 핸들은, GENERIC_READ 액세스를 가지고 있지 않으면 안됩니다.

Windows NT/2000/XP： CreateFile 함수로 FILE_FLAG_OVERLAPPED 플래그를 지정해 오픈된 모든 종류의 핸들, 또는, socket 함수 혹은 accept 함수로부터 돌려주어진 소켓 핸들을, 비동기 독해 조작으로 hFile 파라미터로 지정할 수 있습니다.

Windows 95/98/Me： CreateFile 함수로 FILE_FLAG_OVERLAPPED 플래그를 지정해 오픈된 커뮤니케이션 자원의 핸들, 또는, socket 함수 혹은 accept 함수로부터 돌려주어진 소켓 핸들을, 비동기 독해 조작으로 hFile 파라미터로 지정할 수 있습니다.메일 슬롯이나 이름 파이프, 디스크 파일로부터의 비동기 독해 조작을 행할 수 없습니다.

pBuffer

파일로부터 읽어낸 데이터를 격납하기 위한 버퍼의 주소를 지정합니다.

nNumberOfBytesToRead

읽어내는 아르바이트수를 지정합니다.

pNumberOfBytesRead

실제로 읽어내진 아르바이트수를 격납하기 위한 변수의 주소를 지정합니다.

Windows NT/2000/XP： pOverlapped 파라미터에 유효한 주소를 지정했을 경우는 0 (NULL) (을)를 지정할 수 있습니다.비동기 독해 조작의 경우는, GetOverlappedResult 함수를 호출하는 것으로 읽어내진 아르바이트수를 취득할 수 있습니다. hFile 파라미터가 I/O 완료 포토와 관련지을 수 있고 있는 경우는, GetQueuedCompletionStatus 함수를 호출하는 것으로 읽어내진 아르바이트수를 취득할 수 있습니다.

Windows 95/98/Me： 이 파라미터에 0 (NULL) (을)를 지정할 수 없습니다.

pOverlapped

유효한 OVERLAPPED 구조체의 주소 또는 0 (NULL) (을)를 지정합니다.

hFile 파라미터의 핸들이 FILE_FLAG_OVERLAPPED 플래그를 가지지 않을 때, 한편, 이 파라미터에 0 (NULL) (을)를 지정했을 때는, 파일 포인터의 현재 위치로부터 파일이 동기적으로 읽어내집니다.독해가 완료하면, 제어가 돌아갑니다.

hFile 파라미터의 핸들이 FILE_FLAG_OVERLAPPED 플래그를 가질 때, 한편, 이 파라미터로 유효한 OVERLAPPED 구조체의 주소를 지정했을 때는, OVERLAPPED 구조체로 지정된 오프셋으로부터 파일이 비동기적으로 읽어내집니다.제어는 곧바로 돌아갑니다만, 독해가 완료하고 있다고는 할 수 없습니다.독해가 종료하고 있지 않는 경우는, ReadFile 함수는 실패해, GetLastError 함수는 997 (ERROR_IO_PENDING) (을)를 돌려줍니다.그 후, 독해가 완료하면, OVERLAPPED 구조체로 지정된 이벤트가 시그널 상태가 됩니다.

Windows NT/2000/XP： hFile 파라미터의 핸들이 FILE_FLAG_OVERLAPPED 플래그를 가지지 않을 때, 한편, 이 파라미터로 유효한 OVERLAPPED 구조체의 주소를 지정했을 때는, OVERLAPPED 구조체로 지정한 오프셋으로부터 파일이 동기적으로 읽어내집니다.독해가 완료하면, 제어가 돌아갑니다.

Windows 95/98/Me： 파일, 디스크, 파이프, 메일 슬롯에의 조작을 행하는 경우, 이 파라미터는 0 (NULL) (이)가 아니면 안됩니다. 0 (NULL) 이외의 값을 지정하면 호출은 실패합니다.다만, 시리얼 포트 및 패러렐 포토의 비동기 입출력은 서포트됩니다.

반환값

성공하면 0 이외의 값이 돌아갑니다.

실패하면 0 하지만 돌아갑니다.확장 에러 정보를 취득하려면 , GetLastError 함수를 사용합니다.

반환값이 0 이외로, 한편, 실제로 읽어내진 아르바이트수가 0 의 경우, 독해 조작의 시점에서 파일 포인터가 파일의 종단을 넘고 있던 것을 나타내 보입니다.다만, 파일이 FILE_FLAG_OVERLAPPED 플래그 첨부로 오픈되고 있어 pOverlapped 파라미터에 0 (NULL) 이외의 값을 지정해 있었을 경우에는, 파일 포인터가 파일의 종단을 넘고 있으면, 반환값은 0 (이)가 되어, GetLastError 함수는 38 (ERROR_HANDLE_EOF) (을)를 돌려줍니다.

해설

다른 프로세스에 의해서 락 되고 있는 영역을 읽어내려고 하면, 이 함수는 실패합니다.

독해 조작이 종료하지 않는 한, pBuffer 파라미터로 지정된 버퍼의 내용을 변경 해서는 안됩니다.

미처리의 비동기 I/O 하지만 대량으로 남아 있을 때, ReadFile 함수가 실패해 GetLastError 함수가 1784 (ERROR_INVALID_USER_BUFFER) 또는 8 (ERROR_NOT_ENOUGH_MEMORY) (을)를 돌려주는 일이 있습니다.

대응 정보

Windows 95 이후 / Windows NT 3.1 이후