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.
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.
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. |
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.
ReadFileEx, SleepEx, WaitForMultipleObjects, WaitForSingleObjectEx, WriteFileEx