WaitForMultipleObjectsEx

DWORD WaitForMultipleObjectsEx(cObjects, lphObjects, fWaitAll, dwTimeout, fAlertable)
DWORD cObjects;	/* number of objects to wait for	*/
LPHANDLE lphObjects;	/* address of object handle array	*/
BOOL fWaitAll;	/* wait for all or wait for one	*/
DWORD dwTimeout;	/* timeout time in milliseconds	*/
BOOL fAlertable;	/* return on I/O completion?	*/

The WaitForMultipleObjectsEx function waits for several objects to attain the signaled state or until an I/O callback function is called.

This function is available only in Win32/NT.

Parameters

cObjects

Specifies the number of objects to be waited on.

lphObjects

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

fWaitAll

Specifies the wait type. A value of TRUE indicates “wait all” (the wait is not satisified until all the objects reach the signaled state). A value of FALSE indicates “wait any” (the wait is satisfied when a single object reaches the signaled state.

dwTimeout

Specifies the number of milliseconds the function will wait for the objects. If dwTimeout is zero, the function tests the objects and returns immediately. If dwTimeout is INFINITE, the function will not return until the wait is satisfied.

fAlertable

Specifies whether the function may terminate early due to an I/O completion callback. If fAlertable is TRUE and the thread that called the WaitForSingleObjectEx function is the same thread that called the extended I/O function, then the wait can return due to any one of the wait termination conditions or because an I/O completion callback terminated the wait early (in this case, the return value is WAIT_IO_COMPLETION).

If fAlertable is FALSE, the function will not return when an I/O completion callback occurs.

Return Value

The following list shows the possible return values:

Value

Meaning

WAIT_TIMEOUT
	The wait was terminated because the timeout time was reached.
0 to MAXIMUM_WAIT_OBJECTS – 1
	In the case of wait for any object, the object number which satisfied the wait. In the case of wait for all objects, the value indicates only that the wait was completed successfully.
WAIT_ABANDONED_0 to WAIT_ABANDONED_0 + (MAXIMUM_WAIT_OBJECTS – 1)
	In the case of wait for any object, the object number which satisfied the event, and that the object which satisfied the event was a mutex object and was abandoned. In the case of wait for all objects, the value indicates that the wait was completed successfully and at least one of the objects was a mutex object and was abandoned.
WAIT_IO_COMPLETION
	The wait terminated due to one or more I/O completion callbacks. (fAlertable must be TRUE and the thread that called the WaitForSingleObjectEx function must be the same thread that called the extended I/O function).
0xFFFFFFFF
	An error occurred. Use the GetLastError function to obtain extended error information.

Comments

If fAlertable is FALSE, this function will not return until the specified time interval has passed, the specified objects enter the signaled state, or the objects are abandoned. If fAlertable is TRUE, the function may also return when an I/O completion callback occurs (the return value is WAIT_IO_COMPLETION).

The WaitForMultipleObjectsEx function can wait for the following objects:

change notification

console input

event

file

mutex

process

thread

semaphore

For console input handles, the wait will be satisfied when at least one character is in the buffer.