OVERLAPPED 구조체(minwinbase.h)

아티클
08/24/2023

비동기(또는 겹치는) 입력 및 출력(I/O)에 사용되는 정보를 포함합니다.

구문

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYSTRUCTNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;

멤버

Internal

I/O 요청에 대한 상태 코드입니다. 요청이 실행되면 시스템은 이 멤버를 STATUS_PENDING 설정하여 작업이 아직 시작되지 않았음을 나타냅니다. 요청이 완료되면 시스템은 이 멤버를 완료된 요청에 대한 상태 코드로 설정합니다.

내부 멤버는 원래 시스템 사용을 위해 예약되었으며 해당 동작이 변경되었을 수 있습니다.

InternalHigh

I/O 요청에 대해 전송된 바이트 수입니다. 요청이 오류 없이 완료된 경우 시스템은 이 멤버를 설정합니다.

InternalHigh 멤버는 원래 시스템 사용을 위해 예약되었으며 해당 동작이 변경되었을 수 있습니다.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

사용자가 지정한 대로 I/O 요청을 시작할 파일 위치의 하위 부분입니다.

이 멤버는 파일과 같은 오프셋(파일 포인터 메커니즘이라고도 함)의 개념을 지원하는 검색 디바이스에서 I/O 요청을 수행하는 경우에만 0이 아닌 것입니다. 그렇지 않으면 이 멤버는 0이어야 합니다.

자세한 내용은 참조 주의합니다.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

사용자가 지정한 대로 I/O 요청을 시작할 파일 위치의 상위 부분입니다.

자세한 내용은 참조 주의합니다.

DUMMYUNIONNAME.Pointer

시스템 사용을 위해 예약됨; 를 0으로 초기화한 후에는 를 사용하지 마세요.

hEvent

작업이 완료될 때 시스템에서 신호를 받는 상태로 설정되는 이벤트에 대한 핸들입니다. 사용자는 이 구조를 겹치는 함수에 전달하기 전에 CreateEvent 함수를 사용하여 이 멤버를 0 또는 유효한 이벤트 핸들로 초기화해야 합니다. 그런 다음 이 이벤트를 사용하여 디바이스에 대한 동시 I/O 요청을 동기화할 수 있습니다. 자세한 내용은 참조 주의합니다.

ReadFile 및 WriteFile과 같은 함수는 I/O 작업을 시작하기 전에 이 핸들을 서명되지 않은 상태로 설정합니다. 작업이 완료되면 핸들이 신호됨 상태로 설정됩니다.

GetOverlappedResult 및 동기화 대기 함수와 같은 함수는 자동 재설정 이벤트를 서명되지 않은 상태로 다시 설정합니다. 따라서 수동 재설정 이벤트를 사용해야 합니다. 자동 재설정 이벤트를 사용하는 경우 작업이 완료되기를 기다린 다음 bWait 매개 변수가 TRUE로 설정된 GetOverlappedResult를 호출하면 애플리케이션이 응답을 중지할 수 있습니다.

설명

이 구조체의 사용되지 않는 멤버는 함수 호출에서 구조체를 사용하려면 항상 0으로 초기화해야 합니다. 그렇지 않으면 함수가 실패하고 ERROR_INVALID_PARAMETER 반환할 수 있습니다.

Offset 및 OffsetHigh 멤버는 함께 64비트 파일 위치를 나타냅니다. 파일 또는 파일과 유사한 디바이스의 시작부터 바이트 오프셋이며 사용자가 지정합니다. 시스템에서 이러한 값을 수정하지 않습니다. 호출 프로세스는 READFile 또는 WriteFile(및 관련) 함수와 같은 오프셋을 사용하는 함수에 OVERLAPPED 구조를 전달하기 전에 이 멤버를 설정해야 합니다.

HasOverlappedIoCompleted 매크로를 사용하여 GetOverlappedResult가 애플리케이션에 너무 번거로울 경우 비동기 I/O 작업이 완료되었는지 여부를 검사 수 있습니다.

CancelIo 함수를 사용하여 비동기 I/O 작업을 취소할 수 있습니다.

일반적인 실수는 이전 비동기 작업이 완료되기 전에 OVERLAPPED 구조를 다시 사용하는 것입니다. 각 요청에 대해 별도의 구조를 사용해야 합니다. 또한 데이터를 처리하는 각 스레드에 대한 이벤트 개체를 만들어야 합니다. 배열에 이벤트 핸들을 저장하는 경우 WaitForMultipleObjects 함수를 사용하여 모든 이벤트가 신호를 받을 때까지 쉽게 기다릴 수 있습니다.

비동기 I/O 사용의 추가 정보 및 잠재적인 문제는 CreateFile, ReadFile, WriteFile 및 관련 함수를 참조하세요.

일반적인 동기화 개요 및 개념적 OVERLAPPED 사용 정보는 동기화 및 겹치는 입력 및 출력 및 관련 topics 참조하세요.

동기 및 비동기 I/O에 대한 파일 I/O 지향 개요는 동기 및 비동기 I/O를 참조하세요.

예제

예를 들어 겹치는 I/O를 사용하는 명명된 파이프 서버를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
머리글	minwinbase.h(Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2의 Windows.h 포함)