CreateToolhelp32Snapshot Function

Declare Function CreateToolhelp32Snapshot Lib "kernel32.dll" (ByVal dwFlags As Long, ByVal th32ProcessID As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Not Supported.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

CreateToolhelp32Snapshot creates a snapshot of what is running on the computer the moment the function is called. Depending on the flags specified, this snapshot can include running processes and/or threads, among other things. With this snapshot, you can then examine what things were running when the snapshot was made. After your program no longer needs the snapshot, destroy it using CloseHandle.

Return Value

If successful, the function returns a handle to the snapshot that was made. If an error occured, the functions returns -1 (use GetLastError to get the error code).

Visual Basic-Specific Issues

None.

Parameters

dwFlags

A combination of the following flags specifying which information to include in the snapshot:

TH32CS_INHERIT: Make the returned snapshot handle inheritable.
TH32CS_SNAPALL: Include everything (heap list of a process, modules, processes, and threads) in the snapshot.
TH32CS_SNAPHEAPLIST: Include the heap list of the process specified by th32ProcessID in the snapshot.
TH32CS_SNAPMODULE: Include the module list of the process specified by th32ProcessID in the snapshot.
TH32CS_SNAPPROCESS: Include the process list in the snapshot.
TH32CS_SNAPTHREAD: Include the thread list in the snapshot.

th32ProcessID

The identifier of the process for when TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE is specified in dwFlags. A value of 0 indicates the current process. If neither of those two flags are specified, this parameter is ignored.

Constant Definitions

Const TH32CS_INHERIT = &H80000000
Const TH32CS_SNAPALL = &HF
Const TH32CS_SNAPHEAPLIST = &H1
Const TH32CS_SNAPPROCESS = &H2
Const TH32CS_SNAPTHREAD = &H4
Const TH32CS_SNAPMODULE = &H8

Example

Print a list of all the processes currently running on the computer when the user clicks button Command1. To do this, a snapshot of the running process list is taken, and then each process in it is analyzed. The filename of the process and the number of threads owned by it is then displayed. To use this example, 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 Declare Function CreateToolhelp32Snapshot Lib "kernel32.dll" (ByVal dwFlags As Long, ByVal _
	th32ProcessID As Long) As Long
Public Const TH32CS_SNAPPROCESS = &H2
Public Type PROCESSENTRY32
	dwSize As Long
	cntUsage As Long
	th32ProcessID As Long
	th32DefaultHeapID As Long
	th32ModuleID As Long
	cntThreads As Long
	th32ParentProcessID As Long
	pcPriClassBase As Long
	dwFlags As Long
	szExeFile As String * 260
End Type
Public Declare Function Process32First Lib "kernel32.dll" (ByVal hSnapshot As Long, _
	lppe As PROCESSENTRY32) As Long
Public Declare Function Process32Next Lib "kernel32.dll" (ByVal hSnapshot As Long, _
	lppe As PROCESSENTRY32) As Long
Public Declare Function CloseHandle Lib "kernel32.dll" (ByVal hObject As Long) As Long

' *** Place the following code inside a form window. ***

Private Sub Command1_Click()
	Dim hSnapshot As Long  ' handle to the snapshot of the process list
	Dim processInfo As PROCESSENTRY32  ' information about a process in that list
	Dim success As Long    ' success of having gotten info on another process
	Dim exeName As String  ' filename of the process
	Dim retval As Long     ' generic return value
	
	' First, make a snapshot of the current process list.
	hSnapshot = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0)
	
	' Get information about the first process in the list.
	processInfo.dwSize = Len(processInfo)
	success = Process32First(hSnapshot, processInfo)
	' Make sure a handle was returned.	
	If hSnapshot = -1 Then
		Debug.Print "Unable to take snapshot of process list!"
		Exit Sub
	End If

	' Loop for each process on the list.
	While success <> 0
		' Extract the filename of the process (i.e., remove the empty space)
		exeName = Left(processInfo.szExeFile, InStr(processInfo.szExeFile, vbNullChar) - 1)
		' Display the process name and the number of threads it owns.
		Debug.Print "Process: "; exeName
		Debug.Print "  - Number of threads:"; processInfo.cntThreads
		
		' Get information about the next process, if there is one.
		processInfo.dwSize = Len(processInfo)
		success = Process32Next(hSnapshot, processInfo)
	Wend
	
	' Destroy the snapshot, now that we no longer need it.
	retval = CloseHandle(hSnapshot)
End Sub