_SHELL_HookSystemBroadcast

include shell.inc
VxDcall SHELL_HookSystemBroadcast, <<OFFSET32 pfnHandler>, \
    dwRef, dwCallOrder>
mov [Handle], eax  ; handle of broadcast callback procedure

Installs a callback procedure into the broadcast notification chain. The chain monitors calls to the _SHELL_BroadcastSystemMessage service and to the Windows BroadcastSystemMessage function. Uses C calling conventions.

• Returns the handle of the installed callback procedure in the EAX register if successful. Otherwise, returns zero.

pfnHandler

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

dwRef

Reference data for the callback procedure.

dwCallOrder

Call order. Must be zero for non-zero virtual devices. If more than one callback procedure is installed to monitor the broadcast service, the call order specifies the order in which the given callback procedure is called relative to the other callback procedures. Procedures with equal call orders are called in an unspecified (but consistent) order.

The system calls the callback procedure whenever a VxD calls the _SHELL_BroadcastSystemMessage service. The system calls the procedure using the C calling conventions as follows:

VxDcall [pfnHandler], <uMsg, wParam, lParam, dwRef>

The uMsg parameter is the message number and wParam is the 16-bit message parameter. For both uMsg and wParam, the low 16 bits contain the parameter value and the high 16 bits are reserved. The lParam parameter is the 32-bit message parameter and dwRef is the same reference data value passed to _SHELL_HookSystemBroadcast.

The return value from the callback procedure is ignored if the broadcast is not a BSF_QUERY. Otherwise, the procedure should return a nonzero value to allow the broadcast to continue, or zero to fail the message and halt the broadcast. The procedure should return 1 for any messages it does not understand.

If the callback procedure is installed while a broadcast in progress, it is unspecified whether the hook will receive that broadcast. It will, regardless, receive all subsequent broadcasts.