WSAWaitForMultipleEvents
The Windows
Sockets WSAWaitForMultipleEvents function returns either when one or all
of the specified event objects are in the signaled state, or when the time-out
interval expires.
DWORD WSAWaitForMultipleEvents(
|
DWORD cEvents, |
|
|
const
WSAEVENT FAR *lphEvents, |
|
|
BOOL fWaitAll, |
|
|
DWORD dwTimeOUT, |
|
|
BOOL fAlertable |
|
|
); |
|
Parameters
cEvents
[in]
Specifies the number of event object handles in the array pointed to by lphEvents.
The maximum number of event object handles is WSA_MAXIMUM_WAIT_EVENTS. One or
more events must be specified.
lphEvents
[in] Points
to an array of event object handles.
fWaitAll
[in]
Specifies the wait type. If TRUE, the function returns when all event objects
in the lphEvents array are signaled at the same time. If FALSE, the
function returns when any one of the event objects is signaled. In the latter
case, the return value indicates the event object whose state caused the
function to return.
dwTimeout
[in]
Specifies the time-out interval, in milliseconds. The function returns if the
interval expires, even if conditions specified by the fWaitAll parameter
are not satisfied. If dwTimeout is zero, the function tests the state of
the specified event objects and returns immediately. If dwTimeout is
WSA_INFINITE, the function's time-out interval never expires.
fAlertable
[in]
Specifies whether the function returns when the system queues an I/O completion
routine for execution by the calling thread. If TRUE, the completion routine is
executed and the function returns. If FALSE, the completion routine is not
executed when the function returns.
Remarks
The WSAWaitForMultipleEvents
function returns either when any one or when all of the specified objects are
in the signaled state, or when the time-out interval elapses. This function is
also used to perform an alertable wait by setting the parameter fAltertable
to be TRUE. This enables the function to return when the system queues an I/O
completion routine to be executed by the calling thread.
When fWaitAll
is TRUE, the function s wait condition is satisfied only when the state of
all objects is signaled at the same time. The function does not modify the state
of the specified objects until all objects are simultaneously signaled.
Applications
that simply need to enter an alertable wait state without waiting for any event
objects to be signalled should use the Win32 sleepEx function.
Return Values
If the function
succeeds, the return value indicates the event object that caused the function
to return.
If the
function fails, the return value is WSA_WAIT_FAILED. To get extended error
information, call WSAGetLastError.
The return
value upon success is one of the following values:
|
Value |
Meaning |
|
WSA_WAIT_EVENT_0
to (WSA_WAIT_EVENT_0 + cEvents - 1) |
If fWaitAll
is TRUE, the return value indicates that the state of all specified event
objects is signaled. If fWaitAll is FALSE, the return value minus
WSA_WAIT_EVENT_0 indicates the lphEvents array index of the object
that satisfied the wait. |
|
WAIT_IO_COMPLETION
|
One or more
I/O completion routines are queued for execution. |
|
WSA_WAIT_TIMEOUT
|
The
time-out interval elapsed and the conditions specified by the fWaitAll
parameter are not satisfied. |
Error Codes
|
WSANOTINITIALISED |
A
successful WSAStartup must occur before using this function. |
|
WSAENETDOWN |
The network
subsystem has failed. |
|
WSAEINPROGRESS |
A blocking
Windows Sockets 1.1 call is in progress, or the service provider is still
processing a callback function. |
|
WSA_NOT_ENOUGH_MEMORY |
Not enough
free memory available to complete the operation. |
|
WSA_INVALID_HANDLE |
One or more
of the values in the lphEvents array is not a valid event object
handle. |
|
WSA_INVALID_PARAMETER |
The cEvents
parameter does not contain a valid handle count. |
See Also