|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| Yes
| Win32s
| No
| Import Library
| kernel32.lib
| Header File
| winbase.h
| Unicode
| No
| Platform Notes
| None
|
|
|
WaitForSingleObjectEx
The WaitForSingleObjectEx function returns when one of the following occurs:
- The specified object is in the signaled state.
- An I/O completion routine or asynchronous procedure call (APC) is queued to
the thread.
- The time-out interval elapses.
DWORD WaitForSingleObjectEx(
HANDLE hHandle,
| // handle of object to wait for
| DWORD dwMilliseconds,
| // time-out interval in milliseconds
| BOOL bAlertable
| // return to execute I/O completion routine if TRUE
| );
|
|
Parameters
hHandle
Identifies the object. For a list of the object types whose handles can be
specified, see the following Remarks section.
Windows NT: The handle must have SYNCHRONIZE access. For more information, see Access Masks and Access Rights.
dwMilliseconds
Specifies the time-out interval, in milliseconds. The function returns if the
interval elapses, even if the object's state is nonsignaled and no completion
routines or APCs are queued. If dwMilliseconds is zero, the function tests the object's state and checks for queued
completion routines or APCs and then returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.
bAlertable
Specifies whether the function returns when the system queues an I/O
completion routine or APC. If TRUE, the function returns and the completion routine or
APC function is executed. If FALSE, the function does not return, and the
completion routine or APC function is not executed.
A completion routine is queued when the ReadFileEx or WriteFileEx function in which it was specified has completed. The wait function returns
and the completion routine is called only if bAlertable is TRUE, and the calling thread is the thread that initiated the read or
write operation. An APC is queued when you call QueueUserAPC.
Return Values
If the function succeeds, the return value indicates the event that caused the
function to return.
If the function fails, the return value is 0xFFFFFFFF. To get extended error
information, call GetLastError.
The successful return value is one of the following:
Value
| Meaning
| WAIT_OBJECT_0
| The state of the specified object is signaled.
| WAIT_ABANDONED
| The specified object is a mutex object that was not released by the thread
that owned the mutex object before the owning thread terminated. Ownership of the
mutex object is granted to the calling thread, and the mutex is set to
nonsignaled.
| WAIT_IO_COMPLETION
| One or more I/O completion routines are queued for execution.
| WAIT_TIMEOUT
| The time-out interval elapsed, and the object's state is nonsignaled.
|
Remarks
The WaitForSingleObjectEx function 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.
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. For example, the count of a semaphore
object is decreased by one.
The WaitForSingleObjectEx function can wait for the following objects:
Object
| Description
| Change notification
| The FindFirstChangeNotification function returns the handle. A change notification object's state is signaled
when a specified type of change occurs within a specified directory or
directory tree.
| Console input
| The handle is returned by the CreateFile function when the CONIN$ value is specified, or by the GetStdHandle function. The object's state is signaled when there is unread input in the
console's input buffer, and it is nonsignaled when the input buffer is empty.
| Event
| The CreateEvent or OpenEvent function returns the handle. An event object's state is set explicitly to
signaled by the SetEvent or PulseEvent function. A manual-reset event object's state must be reset explicitly to
nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the
object's state to nonsignaled before returning. Event objects are also used in
overlapped operations, in which the state is set by the system.
| Mutex
| The CreateMutex or OpenMutex function returns the handle. A mutex object's state is signaled when it is
not owned by any thread. The wait function requests ownership of the mutex for
the calling thread, changing the mutex's state to nonsignaled when ownership is
granted.
| Process
| The CreateProcess or OpenProcess function returns the handle. A process object's state is signaled when the
process terminates.
| Semaphore
| The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between
zero and some maximum value. Its state is signaled when its count is greater than
zero and nonsignaled when its count is zero. If the current state is signaled,
the wait function decreases the count by one.
| Thread
| The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. A thread object's state is signaled when the
thread terminates.
| Timer
| The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the
SetWaitableTimer function. The state of an active timer is signaled when it reaches its due
time. You can deactivate the timer by calling the CancelWaitableTimer function. The state of an active timer is signaled when it reaches its due
time. You can deactivate the timer by calling the CancelWaitableTimer function.
|
In some circumstances, you can specify a handle of a file, named pipe, or
communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.
You have to be careful when using the wait functions and DDE. If a thread
creates any windows, it must process messages. DDE sends messages to all windows in
the system. If you have a thread that uses a wait function with no time-out
interval, the system will deadlock. Therefore, if you have a thread that creates
windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObjectEx.
See Also
CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ReadFileEx, ResetEvent, SetEvent, SetWaitableTimer, WriteFileEx
| Last news from Greatis Software |
 |
|
Nostalgia .Net |
|
.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More » |
| Recommended software for developers |
 |
|
Ultimate Pack |
|
Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More » |
 |
|
Form Designer .Net |
|
Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More » |
 |
|
Print Suite .Net |
|
Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More » |
 |
|
Gradient Controls .Net |
|
Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More » |
 |
|
Greatis iGrid |
|
iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More » |
All the contacts and projectsDmitry Vasiliev (just.dmitry)
Related LinksSoftware for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET More Online Helps Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages
|
