MsgWaitForMultipleObjects

	DWORD MsgWaitForMultipleObjects(dwCount, lpHandles, bWaitAll, dwMilliseconds, dwWakeMask )
	DWORD dwCount;
	LPHANDLE lpHandles;
	BOOL bWaitAll;
	DWORD dwMilliseconds;
	DWORD dwWakeMask;

The MsgWaitForMultipleObjects function will perform a multiple wait operation on the waitable objects specified by lpHandles, plus the calling thread's input event. The calling thread's input event attains a signaled state when suitable input is available for the thread. The parameter dwWakeMask determines the suitable types of input.

Parameters

dwCount

A count of the number of objects that are to be waited on. The count does not include the calling thread's input object.

lpHandles

An array of object handles. Each handle must have SYNCHRONIZE access to the associated object.

bWaitAll

A flag that supplies the wait type. A value of TRUE indicates a “wait all.” A value of FALSE indicates a “wait any.” In a successful wait all, the wait is not satisfied unless all of the objects attain the signaled state at the same time.

dwMilliseconds

A time-out value that specifies the relative time, in milliseconds, over which the wait is to be completed. A timeout value of 0 specifies that the wait is to timeout immediately. This allows an application to test an object to determine if it is in the signaled state. A timeout value of -1 specifies an infinite timeout period.

dwWakeMask

This value specifies which types of input will set the calling thread's input event to the signalled state. The MsgWaitForMultipleObjects function waits on this event in addition to the list of waitable objects passed in via lpHandles. The same QS_ bits that come back from GetQueueStatus are used for dwWakeMask. If the input event enters the signalled state, the return value will be dwCount (i.e. one plus the index for the last object passed in.)

Return Value

If the function returns the value STATUS_TIME_OUT, the wait was terminated due to timing out.

If the function returns a value in the range 0 to MAXIMUM_WAIT_OBJECTS-1, and the call was a wait for any object, the return value is the object number of the object that satisfied the wait. The objects passed via lpHandles are numbered starting with 0. The calling thread's input object has an object number of dwCount.

If the function returns a value in the range 0 to MAXIMUM_WAIT_OBJECTS-1, and the call was a wait for all objects, the return value only indicates that the call completed successfully.

If the function returns a value in the range STATUS_ABANDONED to STATUS_ABANDONED + (MAXIMUM_WAIT_OBJECTS—1), and the call was a wait for any object, the return value is the object number of the object which satisfied the wait. Again, the objects passed via lpHandles are numbered starting with 0, and the the calling thread's input object has an object number of dwCount.

If the function returns a value in the range STATUS_ABANDONED to STATUS_ABANDONED + (MAXIMUM_WAIT_OBJECTS—1), and the call was a wait for all objects, the return value indicates that the wait was completed successfully and at least one of the objects was abandoned.

Comments

These are the types of objects that are waitable:

process

thread

event

semaphore

mutex

file