WaitForMultipleObjectsEx

【勇芳软件工作室】汉化HomePreviousNext

当发生以下其中一种情况时,WaitForMultipleObjectsEx函数返回:

*任何一个或所有指定的对象都处于信号状态。

* I / O完成例程或异步过程调用(APC)排队等待线程。

*经过了超时间隔。

DWORD WaitForMultipleObjectsEx(

DWORD 【NCOUNT】,//句柄数组中的句柄数
CONST HANDLE *【lpHandles】,//指向对象句柄数组
BOOL 【bWaitAll】,// wait flag
DWORD 【dwMilliseconds】,//超时间隔(以毫秒为单位)
BOOL 【bAlertable】// alertable等待标志
); 

参数

【NCOUNT】

指定在【lpHandles】指向的数组中等待的对象句柄数。对象句柄的最大数量为MAXIMUM_WAIT_OBJECTS。

【lpHandles】

指向一组对象句柄。有关可以指定句柄的对象类型的列表,请参阅以下备注部分。该数组可以包含不同类型对象的句柄。

Windows NT:句柄必须具有SYNCHRONIZE访问权限。有关详细信息,请参阅访问掩码和访问权限.

【bWaitAll】

指定等待类型。如果为TRUE,则当【lpHandles】数组中的所有对象的状态都设置为发出信号时,该函数将返回。如果FALSE,则当任何一个对象的状态设置为发信号时,该函数返回。在后一种情况下,返回值表示状态导致函数返回的对象。

【dwMilliseconds】

指定超时间隔(以毫秒为单位)。即使不满足【bWaitAll】参数指定的条件,并且没有完成例程或APC排队,该函数将返回间隔。如果【dwMilliseconds】为零,则该函数测试指定对象的状态,并检查排队的完成例程或APC,然后立即返回。如果【dwMilliseconds】为INFINITE,则该函数的超时间隔从不会过去。

【bAlertable】

指定当系统对I / O完成例程或APC进行排队时函数是否返回。如果为TRUE,函数返回,执行完成例程或APC功能。如果为FALSE,则该函数不返回,并且不执行完成例程或APC功能。

当指定完毕的ReadFileExWriteFileEx功能完成后,完成例程将排队。等待函数返回,只有【bAlertable】为TRUE并且调用线程是启动读或写操作的线程时才调用完成例程。当您致电QueueUserAPC时,APC排队等候。

返回值

如果函数成功,则返回值表示导致函数返回的事件。

如果函数失败,返回值为0xFFFFFFFF。要获取扩展错误信息,请调用GetLastError.

成功的返回值是以下值之一:

含义
WAIT_OBJECT_0至(WAIT_OBJECT_0 + 【NCOUNT】 - 1)如果【bWaitAll】为TRUE,则返回值表示指示了所有指定对象的状态。

如果【bWaitAll】为FALSE,则返回值减WAIT_OBJECT_0表示满足等待的对象的【lpHandles】数组索引。如果在通话过程中发出了多个对象信号,这是所有信号对象的索引值最小的信号对象的数组索引。

WAIT_ABANDONED_0至(WAIT_ABANDONED_0 + 【NCOUNT】 - 1)如果【bWaitAll】为TRUE,则返回值表示指示了所有指定对象的状态,并且至少一个对象是放弃的互斥对象。

如果【bWaitAll】为FALSE,则返回值减WAIT_ABANDONED_0表示满足等待的已放弃互斥体对象的【lpHandles】数组索引。

WAIT_IO_COMPLETION一个或多个I / O完成例程排队等待执行。
WAIT_TIMEOUT经过的超时间隔,【bWaitAll】参数指定的条件不满足,并且没有完成例程排队。

备注

WaitForMultipleObjectsEx功能确定是否满足等待条件。如果没有满足条件,则调用线程进入有效的等待状态,在等待满足条件的同时使用很少的处理器时间。

【bWaitAll】为TRUE时,只有当所有对象的状态都被设置为发信号时,功能的等待操作才会完成。在所有对象的状态都被设置为发出信号之前,该函数不会修改指定对象的状态。例如,可以用信号通知互斥体,但是直到其他对象的状态也被设置为发信号时线程才会获得所有权。在此期间,其他线程可能会获得互斥体的所有权,从而将其状态设置为非指定状态。

在返回之前,wait函数修改某些类型的同步对象的状态。修改仅针对信号状态导致功能返回的对象或对象。例如,信号量对象的计数减1。

WaitForMultipleObjectsEx函数可以在【lpHandles】数组中指定以下任何对象类型的句柄:

目的描述
更改通知enFindFirstChangeNotification函数返回句柄。当在指定的目录或目录树中发生指定类型的更改时,发出更改通知对象的状态。
控制台输入当指定CONIN $值时,该句柄由CreateFile函数返回,或者由GetStdHandle函数返回。当控制台的输入缓冲区中有未读的输入时,对象的状态发出信号,当输入缓冲区为空时,该状态为非信号。
事件CreateEventOpenEvent函数返回句柄。事件对象的状态被明确设置为由SetEventPulseEvent函数发出信号。手动复位事件对象的状态必须显式重置为ResetEvent功能的非指定状态。对于自动重置事件对象,等待功能在返回之前将对象的状态重置为非指定状态。事件对象也用于重叠操作,其中状态由系统设置。
互斥CreateMutexOpenMutex函数返回句柄。当互斥体对象的状态不被任何线程所拥有时发出。等待函数请求调用线程的互斥体的所有权,在授予所有权时将互斥体的状态更改为非指定状态。
处理CreateProcessOpenProcess函数返回句柄。进程对象的状态在进程终止时发出信号。
信号CreateSemaphoreOpenSemaphore函数返回句柄。信号量对象维持零和某个最大值之间的计数。当它的计数大于零时,它的状态被发出信号,当它的计数为零时,它的信号是非信号的。如果发出当前状态,则等待功能将计数减1。
线CreateProcessCreateThreadCreateRemoteThread函数返回句柄。当线程终止时,会发出线程对象的状态。
计时器CreateWaitableTimerOpenWaitableTimer函数返回句柄。通过调用SetWaitableTimer函数激活定时器。有效定时器的状态在达到适当的时间时发出信号。您可以通过调用CancelWaitableTimer功能来停用定时器。有效定时器的状态在达到适当的时间时发出信号。您可以通过调用CancelWaitableTimer功能来停用定时器。

在某些情况下,您可以在【lpHandles】中将文件的句柄(称为管道或通讯设备)指定为同步对象。但是,不鼓励用于此目的。

使用等待功能和DDE时必须要小心。如果一个线程创建任何窗口,它必须处理消息。DDE向系统中的所有窗口发送消息。如果您的线程使用等待功能,没有超时间隔,系统将会死锁。因此,如果您有一个创建窗口的线程,请使用MsgWaitForMultipleObjectsMsgWaitForMultipleObjectsEx而不是WaitForMultipleObjectsEx.

也可以看看

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateWaitableTimer, CreateThread, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ReadFileEx, ResetEvent, SetEvent, SetWaitableTimer, WriteFileEx