WSAWaitForMultipleEvents

WSAWaitForMultipleEvents 함수는 지정된 이벤트 객체의 한 개 또는 모두가 신호받은 상태였을 때나, 타임아웃 간격으로 지정한 시간이 지났을 때까지 기다렸다 반환되는 함수입니다.

DWORD WSAWaitForMultipleEvents(
        DWORD                          
cEvents,
        const WSAEVENT FAR*  
 lphEvents,
        BOOL                             
fWaitAll,
        DWORD                         
 dwTimeOUT,
        BOOL                            
 fAlertable
);

 

Parameters

cEvents
[입력] lphEvent 매개변수로 포인트되는 배열에 있는 이벤트 객체 핸들의 갯수를 명시합니다. 이벤트 객체 핸들의 최대 갯수는 WSA_MAXIMUM_WAIT_EVENTS입니다. 한 개 또는 그 이상의 이벤트는 반드시 명시되어야 합니다.

lphEvents
[입력] 이벤트 객체 핸들의 배열에 대한 포인터

fWaitAll
[입력] 기다림의 형태를 명시하는 매개변수로, 이값이 TRUE 라면, 이 함수는 lphEvent 배열에 있는 모든 이벤트 객체가 같은 시간에 신호를 받을 때 반환됩니다. 반면, FALSE 라면, 이벤트 객체중에 하나가 신호를 받을 때 반환 됩니다. 후자의 경우, 함수의 반환값은 이벤트 객체(함수의 반환으로 일어난 상태)를 의미합니다.

dwTimeout
[입력] 타임아웃 간격을 명시하는 매개변수로 m/sec 단위(1/1000초)입니다. 지정된 시간이 다 지나게 되면, fWaitAll 매개변수에 의해 지정된 상태(이벤트 객체가 신호를 받아야 하는 조건)가 만족되지 않더라도 함수는 반환되게 됩니다.

fAlertable
[입력] 시스템이 함수를 호출하는 쓰레드의 실행에 대한 I/O 완료루틴(completion routine)을 큐(queue) 시켰을 때 함수가 반환될지 어떤지를 명시하는 매개변수로, 이값이 TRUE 일 경우 완료루틴은 실행되고, 함수는 반환됩니다. FALSE 라면, 완료루틴은 함수가 반환될 때 실행되지 않습니다.

 

Remarks

WSAWaitForMultipleEvents 함수는 명시된 객체들 중 한 개 또는 모두가 신호받은 상태(signaled state)가 되었을 때나, 타임아웃 간격으로 지정한 시간을 모두 소비했을 때 호출 되는 함수입니다. 이 함수는 또한 fAlertable 매개변수를 TRUE 로 설정하여 알람대기(alertable wait) 기능을 수행 하는데 사용합니다. 이러한 기능은 시스템이 호출 쓰레드에서 수행되는 완료루틴(completion routine)을 큐(queue) 했을 때 함수가 반환 되도록 하는데 사용될 수 있습니다.

fWaitAll 매개변수가 TRUE라면, 함수의 대기상태(wait condition)은 같은시기에 모든 객체의 상태가 신호를 받았을 때만, 만족됩니다. 이 함수는 모든 객체가 동시에 신호받을 때 까지 명시된 객체의 상태를 갱신하지 않습니다.

신호받는 이벤트 객체가 필요없는 간단한 알람 대기 상태를 구현하고자 하고자 한다면, Win32 API인 SleepEx 함수를 사용하면 됩니다.

 

Return Values

함수가 성공적으로 수행된다면, 반환값은 아래의 표에 나열한 값중 하나를 가지게 됩니다. 함수가 실패한다면, 함수는 WSA_WAIT_FAILED를 반환합니다. 또한 WSAGetLastError 함수를 호출하여 특정한 에러코드를 얻어낼 수 있습니다.

함수를 성공적으로 수행하고 반환되는 값을 아래에 나열 해 보았습니다.

Value Meaning
WSA_WAIT_EVENT_0 부터 (WSA_WAIT_EVENT_0 + cEvents - 1)
의 수치를 가질 경우
fWaitAll 매개변수가 TRUE라면, 반환값은 모든 명시된 이벤트 객체가 신호받았다는 것을 나타냅니다. fWaitAll 이 FALSE 라면, 반환값은 대기 상태가 완료된 이벤트 객체 배열의 인덱스를 가리킵니다.
WAIT_IO_COMPLETION 한 개 또는 그 이상의 I/O 완료루틴(completion routine)이 수행을 위하여 큐(queue) 되었습니다.
WSA_WAIT_TIMEOUT fWaitAll 매개변수로 지정된 조건이 만족되지 않은 상태에서 타임아웃으로 대기상태가 종료 되었습니다.

 

Error Codes

WSANOTINITIALISED

이 함수를 사용하기 전에 성공적인 WSAStartup 함수의 호출이 없었습니다.

WSAENETDOWN 네트웍 서브시스템에 에러가 발생했습니다.
WSAEINPROGRESS 블럭킹 윈속 v1.1 이 현재 진행 중이거나, 서비스 프로바이더가 콜백 함수를 여전히 처리하고 있습니다.
WSA_NOT_ENOUGH_MEMORY 메모리가 부족합니다.
WSA_INVALID_HANDLE 한 개 또는 그 이상의 lphEvents 배열요소가 올바른 이벤트 객체 핸들이 아닙니다.
WSA_INVALID_PARAMETER cEvent 매개변수가 올바른 핸들의 갯수를 가지고 있지 않습니다.

 

QuickInfo

Windows NT : 사용가능
Windows : 사용가능
Windows CE : 지원하지 않습니다.
Header :
          Win16/32 : winsock.h
          Win32-II : winsock2.h
Import Library :
          Win16 : winsock.lib
          Win32 : wsock32.lib
          Win32-II : ws2_32.lib

See Also

overview, WSACloseEvent, WSACreateEvent