WaitForSingleObject Function

Declare Function WaitForSingleObject Lib "kernel32.dll" (ByVal hHandle As Long, ByVal dwMilliseconds As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

WaitForSingleObject halts program execution temporarily, until either a specified object enters a signaled state or a specified timeout period elapses. This function allows a program to wait until something else has happened before execution continues.

Return Value

The function returns one of the following flags:

WAIT_ABANDONED: The mutex specified by hHandle was not released by its owning thread before that thread terminated. The mutex is now owned by the calling thread and is in a nonsignaled state.
WAIT_FAILED: The function failed. Use GetLastError to get the error code.
WAIT_OBJECT_0: The object specified by hHandle is in a signaled state.
WAIT_TIMEOUT: The timeout period has elapsed.

Visual Basic-Specific Issues

None.

Parameters

hHandle

A handle to the object to wait for to enter into a signaled state. This handle can refer to one of the following types of objects:

Change Notification
Console Input
Event
Job (is signaled when the job has finished)
Mutex
Process (is signaled when the process has terminated)
Semaphore
Thread (is signaled when the thread has terminated)
Waitable timer

dwMilliseconds

The timeout interval to wait for. The function will return (with a value of WAIT_TIMEOUT) if this timeout period elapses, even if the object being waited for has not entered a single state. This parameter could also be the following value:

INFINITE: Wait forever -- do not use a timeout period.

Constant Definitions

Const WAIT_ABANDONED = &80
Const WAIT_FAILED = &HFFFFFFFF
Const WAIT_OBJECT_0 = &H0
Const WAIT_TIMEOUT = &H102
Const INFINITE = &HFFFF

Example

Open the file "C:\Docs\readme.txt" using whatever program is associated with *.txt files (by default, Notepad). Wait until the user has closed the window before continuing with the example. The example begins when the user clicks button Command1. Obviously, to use this example, you need to place a command button named Command1 on a form window.

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Type SHELLEXECUTEINFO
	cbSize As Long
	fMask As Long
	hwnd As Long
	lpVerb As String
	lpFile As String
	lpParameters As String
	lpDirectory As String
	nShow As Long
	hInstApp As Long
	lpIDList As Long
	lpClass As String
	hkeyClass As Long
	dwHotKey As Long
	hIcon As Long
	hProcess As Long
End Type
Public Const SEE_MASK_NOCLOSEPROCESS = &H40
Public Const SW_SHOWNORMAL = 1
Public Declare Function ShellExecuteEx Lib "shell32.dll" Alias "ShellExecuteExA" (lpExecInfo As _
	SHELLEXECUTEINFO) As Long
Public Const SE_ERR_FNF = 2
Public Const SE_ERR_NOASSOC = 31
Public Declare Function WaitForSingleObject Lib "kernel32.dll" (ByVal hHandle As Long, ByVal _
	dwMilliseconds As Long) As Long
Public Const INFINITE = &HFFFF
Public Const WAIT_TIMEOUT = &H102

' *** Place the following code inside window Form1. ***
Private Sub Command1_Click()
	Dim sei As SHELLEXECUTEINFO  ' structure used by the function
	Dim retval As Long  ' return value
	
	' Load the information needed to open C:\Docs\readme.txt
	' into the structure.
	With sei
		' Size of the structure
		.cbSize = Len(sei)
		' Use the optional hProcess element of the structure.
		.fMask = SEE_MASK_NOCLOSEPROCESS
		' Handle to the window calling this function.
		.hwnd = Form1.hWnd
		' The action to perform: open the file.
		.lpVerb = "open"
		' The file to open.
		.lpFile = "C:\Docs\readme.txt"
		' No additional parameters are needed here.
		.lpParameters = ""
		' The default directory -- not really necessary in this case.
		.lpDirectory = "C:\Docs\"
		' Simply display the window.
		.nShow = SW_SHOWNORMAL
		' The other elements of the structure are either not used
		' or will be set when the function returns.
	End With
	
	' Open the file using its associated program.
	retval = ShellExecuteEx(sei)
	If retval = 0 Then
		' The function failed, so report the error.  Err.LastDllError
		' could also be used instead, if you wish.
		Select Case sei.hInstApp
		Case SE_ERR_FNF
			Debug.Print "The file C:\Docs\readme.txt was not found."
		Case SE_NOASSOC
			Debug.Print "No program is associated with *.txt files."
		Case Else
			Debug.Print "An unexpected error occured."
		End Select
	Else
		' Wait for the opened process to close before continuing.  Instead
		' of waiting once for a time of INFINITE, this example repeatedly checks to see if the
		' is still open.  This allows the DoEvents VB function to be called, preventing
		' our program from appearing to lock up while it waits.
		Do
			DoEvents
			retval = WaitForSingleObject(sei.hProcess, 0)
		Loop While retval = WAIT_TIMEOUT
		Debug.Print "Notepad (or whatever program was opened) has just closed."
	End If		
End Sub