VDAMon v1.4 August 1999

Release history

Properties

* = The property applies only to VDAMon

Methods

* = The method applies only to VDAMon

Events

* = The event applies only to VDAMon

Properties

CBTProcEnabled property

Description
This property enables or disables firing of the CBTProc event. The name CBT (computer based training) may seem a little confusing, but this is what it's called if you want to search for more information on, for example, MS Developer Network.

Usage
VDAMon.CBTProcEnabled [ = state ]

Remarks
This property is not available at design-time.

Data type
Boolean

Example
VDAMon1.CBTProcEnabled = True

CBTUnownedWindowsOnly property

Description
This property states that the CBTProc event shall only fire for windows that belongs for other processes than the current one (the program that's using this instance of VBAMon).

Usage
VDAMon.CBTUnownedWindowsOnly [ = state ]

Remarks
This property is not available at design-time.

Data type
Boolean

Example
VDAMon1.CBTUnownedWindowsOnly = True

CPTID property

Description
This property may be read directly after executing CreateDebugProcess or ShellWithNotify. It will return the ID of the newly created thread (as opposed to the return value of these methods, which is the ID of the process).

Usage
VDAMon.CPTID

Remarks
This property is not available at design-time and it is read only at run-time.

Data type
Long

Example
tid = VDAMon1.CPTID

Methods

ActivatePID method

Description
This is similar to the Visual Basic ActivateApp statement, but instead of taking an application title as argument, ActivatePID takes a process ID. Optionally, ActivatePID may restore the application if it is currently minimized.

Usage
[hwnd =] VDAMon.ActivatePID ( pid, RestoreMinimized )

• pid As Long
  This is the ID of the process to activate. It is the same ID as returned by the Visual Basic Shell function, CreateDebugProcess, ShellWithNotify and CreateProcess.
• RestoreMinimized As Integer
  This determines if the activated process' window shall be restored if it is minimized. 0=leave minimized, 1=restore from minimized, 2=maximize
• Return value: hwnd As Long
  The handle of the application's active window.

Remarks
When RestoreMinimized is not zero, ActivatePID will sleep for a brief time (100ms) after activating the application's top level window. Thereafter will ActivatePID determine which window really got focus before investigating if the window is minimized or not. This has proved necessary since not all applications use the top level window as their main window.

Example
VDAMon1.ActivatePID pidNotepad, 2

CreateDebugProcess method

Description
This is similar to the Visual Basic Shell statement, but executes the new application as a debug process, which makes it possible to track the applications that process starts in turn.

Usage
[pid =] VDAMon.CreateDebugProcess ( filename, windowstyle )

• filename As String
  The file name of the application to be debugged.
• windowstyle As Long
  This is the same parameter as is normally used with the Shell function. I.e. vbNormalFocus.
• Return value: pid As Long
  The ID of the process being created. This is the same value as returned by the Visual Basic Shell function.

Remarks
When a process is being debugged, the CreateProcess, ExitProcess and DebugProcessDone events will be fired.

Example
VDAMon1.CreateDebugProcess "notes.exe", vbMinimizedNoFocus

IMPORTANT: THIS METHOD CANNOT BE USED TO EXECUTE 16-BIT APPLICATIONS!

GetEnv method

Description
Reads an environment variable.

Usage
envvarvalue = VDAMon.GetEnv( envvarname )

• envvarname As String
  The name of an evironment variable.
• Return value: envvarvalue As String
  The value ot the environment variable (or an empty string if the environment variable isn't found).

Remarks
This method offers no advantages over the standard VB function Environ$, but may prove useful in other scripting languages.

Example
strPath = VDAMon1.GetEnv("PATH")

Hotkey method

Description
Registers a hotkey. Each time the hotkey is pressed, a Hotkey event is fired.

Usage
[ retval =] VDAMon.Hotkey( id, virtkey, modifier )

• id As Long
  A unique ID referring to this hotkey. The Hotkey event will be called with this ID as parameter. You may choose this freely, as long as it's a positive number.
• virtkey As Long
  The virtual key code of the keyboard key. If it's a letter key, use the ANSI code of that letter.
• modifier As Long
  Which shift keys that should be used with the key. Add any of the following constants together:
  • 1 - Alt
  • 2 - Ctrl
  • 4 - Shift
  • 8 - Windows 95 key
• Return value: retval As Boolean
  True if the hotkey was registered successfully.

Remarks
To unregister a hot key, just register(!) it with it's negative ID.

Example
VDAMon1.Hotkey 1, Asc("A"), 5 'register alt+shift+a

VDAMon1.Hotkey -1, 0, 0 'unregister

NotifyOnProcessID method

Description
This method causes the ExitProcess event to fire when the supplies process ID terminates. This method is useful if you want to monitor an application you didn't start, or if you couldn't use ShellWithNotify to start it (one reason could be that you needed to use the ShellExecute API).

Usage
VDAMon.NotifyOnProcessID lPID

• lPID As Long
  An existing process ID.

Remarks
The process ID could have been achieved using the GetWindowThreadProcessID or the TaskList method.

PtrRef method

Description
This method is used to de-reference pointer variables. This may be useful when trapping messages where some arguments (as wParam or lParam in the WndProc event) may be pointer variables.

Usage
value = VDAMon.PtrRef( pointer, vartype )

• pointer As Long
  This must be a value pointing to a valid memory location.
• vartype As Integer
  Must be one of the following: vbInteger, vbLong or vbString, depending on what data type the pointer points to.
• Return value: value As Variant
  A variant of the type specified by vartype is returned.

Remarks
Passing an invalid pointer value may cause a protection fault.

Example
strText = VDAMon1.PtrRef( lParam, vbString )

ShellWithNotify method

Description
This method works like the VB Shell function, but when the executed application ends, the ExitProcess event will be fired.

Usage
[ pid =] VDAMon.ShellWithNotify( filename, windowstyle )

• filename As String
  The file name of the application to be executed.
• windowstyle As Long
  This is the same parameter as is normally used with the Shell function. I.e. vbHide.
• Return value: pid As Long
  The ID of the process being created. This is the same value as returned by the Visual Basic Shell function.

Remarks
The thread started will just wait for the process to end using the WaitForSingleObject WIN32 function.

Example
pidNotepad = VDAMon1.ShellWithNotify( "Notepad", vbMaximizedFocus )

ShellWithNotify method

Description
This method works like the VB Shell function, but when the executed application ends, the ExitProcess event will be fired.

Usage
[ pid =] VDAMon.ShellWithNotify( filename, windowstyle )

• filename As String
  The file name of the application to be executed.
• windowstyle As Long
  This is the same parameter as is normally used with the Shell function. I.e. vbHide.
• Return value: pid As Long
  The ID of the process being created. This is the same value as returned by the Visual Basic Shell function.

Remarks
The thread started will just wait for the process to end using the WaitForSingleObject WIN32 function.

Example
pidNotepad = VDAMon1.ShellWithNotify( "Notepad", vbMaximizedFocus )

SubclassNewWindow method

Description
The name of this method is quite misleading, since it doesn't perform any subclassing whatsoever! The name has been chosen because of its close resemblance with the SubclassWindow method, which takes an existing window handle and begins spying upon it. In contrast, SubclassNewWindow creates a completely new window and makes it possible to trap it's messages the same way as if SubclassWindow had been used on that window.

This method has primarily been added because of problems with SubclassWindow when trying to detect messages posted or sent from other applications when running under Win95.

Usage
hWnd = VDAMon.SubclassNewWindow ( windowtitle )

• windowtitle As String
  A title to give the new window. In most cases - just pass vbNullString. It may be useful if you want another application to be able to find it using the FindWindow API.
• Return value: hwnd As Long
  The handle of the newly created window.

Remarks
This method cannot be used at the same time as SubclassWindow, for that you must add several VDAMons to your project. To destroy the window (and stop receiving messages through WndProc) call SubclassWindow (note: not SubclassNewWindow), with a zero value as window handle.

Example
VDAMon1.SubclassNewWindow vbNullString
VDAMon1.TrapMessage WM_USER

VDAMon1.SubclassWindow 0 ' destroy the window

SubclassWindow method

Description
This method subclasses another window, which means that VDAMon is able to spy on all messages received by that window. Messages registered with the TrapMessage method is passed on to the WndProc event, where the application may perform further processing.

One typical use is to trap WM_DROPFILES messages. The sample code shows how to do this.

Usage
VDAMon.SubclassWindow hwnd

• hwnd As Long
  The handle of the window to be subclassed, or zero to stop subclassing.

Remarks
In order to spy on several windows you must add several VDAMons to your project. To stop subclassing, pass a zero as window handle. When you stop subclassing, all messages added with TrapMessage are deleted.

Example
VDAMon1.SubclassWindow Picture1.hWnd ' begin subclassing
VDAMon1.TrapMessage WM_DROPFILES

VDAMon.SubclassWindow 0 ' stop subclassing

TaskbarIconAdd method

Description
This method will add an icon to the "tray" area on the taskbar. This may be used by an application that wishes to be invisible but still provide a way to communicate with the user.

Usage
[ retval =] VDAMon.TaskbarIconAdd( id, hIcon, ToolTip )

• id As Long
  An ID which will be used when referring to the icon in the future. You may choose this freely.
• hIcon As Long
  A handle to an icon. A form's Icon property or any control's Picture property (as long as it contains an Icon) will do.
• ToolTip As String
  A tool tip text that will be shown when the user moves the mouse above the icon.
• Return value: retval As Boolean
  True if successful.

Remarks
When an icon has been added to the tray, all user interactions with the icon (mouse movements and clicks) will be fire a TaskbarNotify event. The TaskbarIconModify method may be used to change the icon appearace or the tool tip text later. When the taskbar icon is not needed anymore, or when the application ends, it must be removed using the TaskbarIconRemove method.

Example
VDAMon1.TaskbarIconAdd 1, Image1.Picture, "Click here"

TaskbarIconModify method

Description
Use this method to modify the icon or tool tip text for an icon added using TaskbarIconAdd.

Usage
[ retval =] VDAMon.TaskbarIconModify( id, hIcon, ToolTip )

• id As Long
  An ID previously used to add a taskbar icon.
• hIcon As Long
  The handle to an icon you want to display, or zero if you want to keep the old one.
• ToolTip As String
  A new tool tip text for the task bar icon, or vbNullString if you want to keep the old one.
• Return value: retval As Boolean
  True if successful.

Example
VDAMon1.TaskbarIconModify 1, 0, "Don't click here"

TaskbarIconRemove method

Description
Use this to remove an icon from the taskbar.

Usage
[ retval =] VDAMon.TaskbarIconRemove( id )

• id As Long
  An ID previoudly used to add a taskbar icon with TaskbarIconAdd.
• Return value: retval As Boolean
  True if successful.

Remarks
VDAMon will not remove taskbar icons when the application ends. This must be done manually.

Example
VDAMon1.TaskbarIconRemove 1

TaskList method

Description
This method returns a list of all currently running process in the system, similar the the system Task Manager.

Usage
strTasks = VDAMon.TaskList

Remarks
The returned string is made up of CDLF separated lines, where each line is one process. Each line, in turn is made out of three parameters; lPID, hTask16 and the filname of the EXE file. lPID is the process ID and hTask16 is the 16-bit task handle if the process is a 16-bit app.

In order for this method to work one of these two conditions must be met:

• The application is running on Windows NT with the file PSAPI.DLL present.
• The application is running on Windows 9x.

Otherwise, and empty string is returned.

TrapMessage method

Description
After a window has been subclassed using the SubclassWindow method, this method is used to specify which messages the WndProc event will receive.

Usage
VDAMon.TrapMessage message

• message As Long
  A message to be routed through the WndProc event.

Remarks
This method will raise an error if no window has been subclassed before attempting to trap messages. To remove trapping of a message, pass it to TrapMessage as a negative value.

Example
VDAMon1.TrapMessage WM_SETTEXT 'pass this message to WndProc

VDAMon1.TrapMessage -WM_SETTEXT 'don't want to see it anymore

Events

CBTProc event

Description
The event is called when CBTProcEnabled is True and something happens (see below) to a window in the system.

Sub VDAMon_CBTProc ( message As Long, hWnd As Long, pid As Long, tid As Long )

• message As Long
  What type of action which caused the event to be fired.
• hWnd As Long
  Handle of the concerned window.
• pid As Long
  The process ID to which the window belongs (or belonged).
• tid As Long
  The thread ID to which the window belongs (or belonged).

Remarks
The following values for message may be received:

This event is fired right after the action took place. Even so, under a pre-emptive multitasking operating system like WinNT or Win95, there is no guarantee that the window handle is still valid.

CreateProcess event

Description
This event is fired each time a new process is created within a process started using the CreateDebugProcess method.

Sub VDAMon_CreateProcess ( pidOrg As Long, pid As Long )

• pidOrg As Long
  This is the ID of a process started using CreateDebugProcess.
• pid As Long
  This is the ID of a process which was just created.

Remarks
If pidOrg = pid then this event is fired as a result of the process created with CreateDebugProcess being created, otherwise it is a process being created by that process or any of its children.

The sample program shows how this works by executing PBrush.exe with CreateDebugProcess. (PBrush.exe will execute Paint.exe and then exits, this would be tricky to monitor without VDAMon.)

DebugProcessDone event

Description
This event is fired when the last process created within a process started using the CreateDebugProcess method exits.

Sub VDAMon_DebugProcessDone ( pidOrg As Long )

• pidOrg As Long
  This is the ID of the process started by CreateDebugProcess.

Remarks
Note that the process pidOrg may have ceased to exist a long time ago. The sample code will show how this works by executing and monitoring PBrush.exe.

ExitProcess event

Description
This event is fired when a process exits. Only process (or children to a process) started using the CreateDebugProcess or ShellWithNotify methods are detected.

Sub VDAMon_ExitProcess ( pidOrg As Long, pid As Long, ExitCode As Long )

• pidOrg As Long
  This is the ID of the process started by CreateDebugProcess or zero if the process exiting was executed by ShellWithNotify.
• pid As Long
  The ID of the exiting process.
• ExitCode As Long
  The exit code of the exiting process.

Hotkey event

Description
This event is fired each time a hotkey is pressed. Hotkeys are registered using the Hotkey method.

Sub VDAMon_HotKey ( id As Long )

• id As Long
  The ID given to the hotkey using the Hotkey method.

Remarks
A normal action may be to activate the application. If you are writing some kind of shell application and wishes to activate other (running) applications, the ActivatePID method may prove invaluable.

TaskbarNotify event

Description
This event is fired when the user interacts with an icon in the taskbar tray, previously added using the TaskbarIconAdd method.

Sub VDAMon_TaskbarNotify ( id As Long, message As Long )

• id As Long
  The ID given to the icon using TaskbarIconAdd.
• message As Long
  A message specifying some kind of user interaction with the icon.

Remarks
Take appropriate action depending on message. You may want to include the following in your project to ease interception of the messages:

Public Const WM_LBUTTONDBLCLK = &H203
Public Const WM_LBUTTONDOWN = &H201
Public Const WM_LBUTTONUP = &H202
Public Const WM_MOUSEMOVE = &H200
Public Const WM_RBUTTONDBLCLK = &H206
Public Const WM_RBUTTONDOWN = &H204
Public Const WM_RBUTTONUP = &H205

Upon receiving a WM_RBUTTONDOWN, it is common practice to display a menu or properties window.

WndProc event

Description
This event is fired each time the subclassed window receives a message registered by TrapMessage.

Usage
Sub VDAMon_WndProc ( message As Long, wParam As Long, lParam As Long, retvalue As Long, bCancel As Boolean )

• message As Long
  A message previously being registered by TrapMessage.
• wParam As Long
  Depends on the message.
• lParam As Long
  Depends on the message.
• retvalue As Long
  The value you want to return. For this to have any effect, you must set bCancel = True in order to stop the default processing.
• bCancel As Boolean
  Set this to True to stop this message from being processed by the subclassed window and return the value retvalue.

Remarks
For some messages, wParam or lParam may be pointer variables. These may be accessed using the PtrRef method.

Properties, methods & events by category

Process creation, monitoring and interaction

• CBTProcEnabled property
• CBTUnownedWindowsOnly property
• CPTID property
• ActivatePID method
• CreateDebugProcess method
• NotifyOnProcessID method
• ShellWithNotify method
• TaskList method
• CBTProc event
• CreateProcess event
• DebugProcessDone event
• ExitProcess event

Message Blaster functions

• SubclassNewWindow method
• SubclassWindow method
• TrapMessage method
• WndProc event

Taskbar (Tray icon)

• TaskbarIconAdd method
• TaskbarIconModify method
• TaskbarIconRemove method
• TaskbarNotify event

Hotkeys

• Hotkey method
• Hotkey event

Miscellaneous

• GetEnv method
• PtrRef method

Migrating DBAppMon

Since VDAMon is very different from DBAppMon, re-coding is definitely necessary, and since you're not likely to have more than one DBAppMon in your project anyway, no action has been taken to support migration; just load your 16-bit project and accept the error when DBAppMon.VBX cannot be loaded and then add VDAMon to the project.

Rev 2000-02-28