SHELL_Hook_Properties

mov eax, GroupID            ; property group identifier
mov edx, OFFSET32 DllName   ; address of property group DLL
mov esi, OFFSET32 Callback  ; address of callback procedure
VxDcall  SHELL_Hook_Properties

jc   error
 

Installs a callback procedure that monitors changes to the properties of virtual machines. The GroupID parameter identifies what group of property data the procedure is associated with. The system calls the procedure simply to notify it of changes the user has made to properties associated with a new or existing VM. This means the procedure can examine the property data but cannot make changes. Uses EAX, ECX, EDX, and Flags.

• Clears the carry flag if successful. Otherwise, sets the carry flag to indicate an error, such as invalid property identifier or insufficient memory.

GroupID

Property group identifier. Can be either a valid group ordinal, such as GROUP_TASK (as defined in PIF.H), or the address of a null-terminated string specifying the name of a custom PIF group. The string must not be longer than PIFEXTSIGSIZE (16) characters, including the terminating null character.

DllName

Address of a null-terminated string specifying the name of the property group DLL. This parameter can be NULL if no DLL exists.

Callback

Address of the callback procedure. For more information about the procedure, see the comments below.

If addresses are given for the GroupID and DllName parameters, the addresses must remain valid for the duration of system operation.

The system calls the callback procedure immediately after Create_VM processing and whenever the properties for a existing VM are changed. The system calls the procedure as follows:

mov ebx, Handle            ; virtual machine handle 
mov edx, OFFSET32 Data     ; address of property data
mov edi, OFFSET32 Ordinal  ; address of property ordinal
call [Callback]
 

The Handle parameter is the handle of the virtual machine being changed. The Data parameter is the address of the property data associated with the virtual machine. The Ordinal parameter is the address of a 32-bit variable that contains the property ordinal. If the property ordinal is zero, the variable is immediately followed by a null-terminated string specifying the name of the property group. No name is given if the ordinal is not zero. The callback requires no return value.