|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| Yes
| Win32s
| No
| Import Library
| kernel32.lib
| Header File
| winbase.h
| Unicode
| No
| Platform Notes
| None
|
|
|
WaitForSingleObject
The WaitForSingleObject function returns when one of the following occurs:
- The specified object is in the signaled state.
- The time-out interval elapses.
DWORD WaitForSingleObject(
HANDLE hHandle,
| // handle of object to wait for
| DWORD dwMilliseconds
| // time-out interval in milliseconds
| );
|
|
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. If dwMilliseconds is zero, the function tests the object's state and returns immediately. If dwMilliseconds is 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.
If the function fails, the return value is WAIT_FAILED. To get extended error
information, call GetLastError.
The return value on success is one of the following values:
Value
| Meaning
| 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_OBJECT_0
| The state of the specified object is signaled.
| WAIT_TIMEOUT
| The time-out interval elapsed, and the object's state is nonsignaled.
|
Remarks
The WaitForSingleObject function checks the current state of the specified object. If the object's
state is nonsignaled, the calling thread enters an efficient wait state. The
thread consumes very little processor time while waiting for the object state to
become signaled or the time-out interval to elapse.
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 WaitForSingleObject 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 WaitForSingleObject.
See Also
CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, ResetEvent, SetEvent, SetWaitableTimer
| 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
|
