ShellExecuteEx Function

Declare Function ShellExecuteEx Lib "shell32.dll" Alias "ShellExecuteExA" (lpExecInfo As SHELLEXECUTEINFO) As Long

Platforms

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

Description & Usage

ShellExecuteEx opens, prints, or executes a file using the Windows shell. When working with a non-executable file, the file is opened using its associated program. ShellExecuteEx can also open Windows Explorer windows. The function returns immediately after opening the file, starting the program, or performing whatever other action was specified.

Return Value

If successful, the function returns a non-zero value. If an error occured, the function returns zero (use GetLastError to get the error code).

Visual Basic-Specific Issues

None.

Parameters

lpExecInfo: Information describing the action to perform through the Windows shell. After the function call completes, this structure also receives information about the function's result.

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