Windows API Guide: SOCKADDR Structure


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

See Also

-->

Category

Synchronization

Back to the Function list.
Back to the Reference section.


Last Modified: October 29, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/w/waitforsingleobject.html



Windows API Guide
Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems
ISBN: B001V0KQIY
EAN: N/A
Year: 1998
Pages: 610

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net