CoWaitForMultipleHandles function
Waits for specified handles to be signaled or for a specified timeout period to elapse.
Syntax
HRESULT CoWaitForMultipleHandles( __in DWORD dwFlags, __in DWORD dwTimeout, __in ULONG cHandles, __in LPHANDLE pHandles, __out LPDWORD lpdwindex );
Parameters
- dwFlags [in]
-
The wait options. Possible values are taken from the COWAIT_FLAGS enumeration.
- dwTimeout [in]
-
The timeout period, in milliseconds.
- cHandles [in]
-
The number of elements in the pHandles array.
- pHandles [in]
-
An array of handles.
- lpdwindex [out]
-
A pointer to a variable that, when the returned status is S_OK, receives a value indicating the event that caused the function to return. This value is usually the index into pHandles for the handle that was signaled.
If pHandles includes one or more handles to mutex objects, a value between WAIT_ABANDONED_0 and (WAIT_ABANDONED_0 + nCount– 1) indicates the index into pHandles for the mutex that was abandoned.
If the COWAIT_ALERTABLE flag is set in dwFlags, a value of WAIT_IO_COMPLETION indicates the wait was ended by one or more user-mode asynchronous procedure calls (APC) queued to the thread.
See WaitForMultipleObjectsEx for more information.
Return value
This function can return the following values.
Note The return value of CoWaitForMultipleHandles can be nondeterministic if the COWAIT_ALERTABLE flag is set in dwFlags, or if pHandles includes one or more handles to mutex objects. The recommended workaround is to call SetLastError(ERROR_SUCCESS) before CoWaitForMultipleHandles.
| Return code | Description |
|---|---|
|
The required handle or handles were signaled. |
|
pHandles was NULL, lpdwindex was NULL, or dwFlags was not a value from the COWAIT_FLAGS enumeration. |
|
The value of pHandles was 0. |
|
The timeout period elapsed before the required handle or handles were signaled. |
Remarks
Depending on which flags are set in the dwFlags parameter, CoWaitForMultipleHandles blocks the calling thread until one of the following events occurs:
- One or all of the handles is signaled. In the case of mutex objects, this condition is also satisfied by a mutex being abandoned.
- An asynchronous procedure call (APC) has been queued to the calling thread with a call to the QueueUserAPC function.
- The timeout period expires.
If the caller resides in a single-thread apartment, CoWaitForMultipleHandles enters the COM modal loop, and the thread's message loop will continue to dispatch messages using the thread's message filter. If no message filter is registered for the thread, the default COM message processing is used.
If the calling thread resides in a multithread apartment (MTA), CoWaitForMultipleHandles calls the WaitForMultipleObjectsEx function.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
Send comments about this topic to Microsoft
Build date: 9/8/2011
From an STA the COM modal loop uses MsgWaitForMultipleObjectsEx.
http://blogs.msdn.com/cbrumme/archive/2004/02/02/66219.aspx
Quoted from the blog entry:
"When you perform a pumping wait, at some level you need to call MsgWaitForMultipleObjectsEx, or a similar Msg* based variant. But the semantics of a WAIT_ALL on an OS MsgWaitForMultipleObjectsEx call is rather surprising and not what you want at all. It waits for all the handles to be signaled AND for a message to arrive at the message queue. In other words, all your handles could be signaled and the application will keep blocking until you nudge the mouse! Ugh."
- 3/11/2007
- SteveJS