WaitForMultipleObjects

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function returns when one of the following occurs:

• Either any one of the specified objects are in the signaled state.
• The time-out interval elapses.

  DWORD WaitForMultipleObjects(
  DWORD
  nCount
  ,
  CONST HANDLE *
  lpHandles
  ,
  BOOL
  fWaitAll
  ,
  DWORD
  dwMilliseconds
  );
  

  Parameters

  nCount

  Specifies the number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

  lpHandles

  Pointer to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.

  fWaitAll

  Specifies the wait type. This parameter must be set to FALSE. This causes function to return when the state of any one of the objects set to is signaled. The return value indicates the object whose state caused the function to return.

  dwMilliseconds

  Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the bWaitAllparameter are not met. If dwMillisecondsis zero, the function tests the states of the specified objects and returns immediately. If dwMillisecondsis INFINITE, the function's time-out interval never elapses.

  Return Values

  If the function succeeds, the return value indicates the event that caused the function to return. This value can be one of the following.

  WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount–1)

  The return value minus WAIT_OBJECT_0 indicates the lpHandlesarray index of the object that satisfied the wait. If more than one object became signaled during the call, this is the array index of the signaled object with the smallest index value of all the signaled objects.

  WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount–1)

  The return value minus WAIT_ABANDONED_0 indicates the lpHandlesarray index of an abandoned mutex object that satisfied the wait.

  WAIT_TIMEOUT

  The time-out interval elapsed and the condition specified by the fWaitAllparameter are not satisfied.

  WAIT_FAILED indicates failure. To get extended error information, call GetLastError.

  Remarks

  Windows CE versions 1.0 through 2.12 does not support waiting for semaphores, change notification objects, input, and timers. Windows 3.0 and later supports waiting for semaphores.

  For Windows CE versions 1.0 and 1.01, this function cannot wait on process or thread handles.

  The WaitForMultipleObjectsfunction determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the criteria to be met.

  The time-out value needs to be a positive number between 0 and 0x7FFFFFFF. The maximum time-out value not equal to infinity is 0x7FFFFFFF. The infinite time-out value is 0xFFFFFFFF. Any time-out value between 0x7FFFFFFF and 0xFFFFFFFF—that is, values from 0xF0000000 through 0xFFFFFFFE—is equivalent to 0x7FFFFFFF. If you need a bigger time-out value than the maximum of 0x7FFFFFFF, use the value for infinity (0xFFFFFFFF).

  Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. When fWaitAllis FALSE, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the objects not selected are unaffected.

  The WaitForMultipleObjectsfunction can specify handles of any of the following object types in the lpHandlesarray:

  • Event
  • Mutex
  • Process
  • Thread
  • Semaphore

    Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. Two examples of code that indirectly creates windows are DDE and COM CoInitialize. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjectsor MsgWaitForMultipleObjectsEx, rather than WaitForMultipleObjects.

    Requirements

    Runs on	Versions	Defined in	Include	Link to
    Windows CE OS	1.01 and later	Winbase.h		Nk.lib

    Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

    See Also

    CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateThread, PulseEvent, ResetEvent, SetEvent, WaitForSingleObject

    
    

    ---

    Last updated on Friday, May 26, 2006

    © 2004 Microsoft Corporation. All rights reserved.