JournalPlaybackProc
The JournalPlaybackProc
hook procedure is a callback function that inserts mouse and keyboard messages
into the system message queue. Typically, an application uses this hook
procedure to play back a series of mouse and keyboard messages recorded
previously by the JournalRecordProc hook procedure. As long as a JournalPlaybackProc
hook procedure is installed, regular mouse and keyboard input is disabled.
LRESULT CALLBACK JournalPlaybackProc(
|
int code, |
// hook code |
|
WPARAM wParam, |
// undefined |
|
LPARAM lParam |
// address of
message being processed |
|
); |
|
Parameters
code
Specifies a
code the hook procedure uses to determine how to process the message. This
parameter can be one of the following values:
|
Value |
Meaning |
|
HC_GETNEXT |
The hook
procedure must copy the current mouse or keyboard message to the EVENTMSG structure pointed to by
the lParam parameter. |
|
HC_NOREMOVE |
An
application has called the PeekMessage function with wRemoveMsg set to
PM_NOREMOVE, indicating that the message is not removed from the message
queue after PeekMessage processing. |
|
HC_SKIP |
The hook
procedure must prepare to copy the next mouse or keyboard message to the EVENTMSG structure pointed to by lParam.
Upon receiving the HC_GETNEXT code, the hook procedure must copy the message
to the structure. |
|
HC_SYSMODALOFF |
A system-modal
dialog box has been destroyed. The hook procedure must resume playing back
the messages. |
|
HC_SYSMODALON |
A
system-modal dialog box is being displayed. Until the dialog box is destroyed,
the hook procedure must stop playing back messages. |
If code is less than zero, the hook procedure must pass the
message to the CallNextHookEx
function without further processing and should return the value returned by CallNextHookEx.
wParam
Specifies a
NULL value.
lParam
Points to an EVENTMSG structure that represents a
message being processed by the hook procedure. This parameter is valid only
when the code parameter is HC_GETNEXT.
Return Values
To have the
system wait before processing the message, the return value must be the amount
of time, in clock ticks, that the system should wait. (This value can be
computed by calculating the difference between the time members in the
current and previous input messages.) To process the message immediately, the
return value should be zero. The return value is used only if the hook code is
HC_GETNEXT; otherwise, it is ignored.
Remarks
A JournalPlaybackProc
hook procedure should copy an input message to the lParam parameter. The
message must have been previously recorded by using a JournalRecordProc hook procedure, which
should not modify the message.
To retrieve
the same message over and over, the hook procedure can be called several times
with the code parameter set to HC_GETNEXT without an intervening call
with code set to HC_SKIP.
If code
is HC_GETNEXT and the return value is greater than zero, the system sleeps for
the number of milliseconds specified by the return value. When the system
continues, it calls the hook procedure again with code set to HC_GETNEXT
to retrieve the same message. The return value from this new call to JournalPlaybackProc
should be zero; otherwise, the system will go back to sleep for the number of
milliseconds specified by the return value, call JournalPlaybackProc
again, and so on. The system will appear to be hung.
Unlike most
other global hook procedures, the JournalRecordProc and JournalPlaybackProc
hook procedures are always called in the context of the thread that set the
hook.
After the
hook procedure returns control to the system, the message continues to be
processed. If code is HC_SKIP, the hook procedure must prepare to return
the next recorded event message on its next call.
An
application installs a JournalPlaybackProc hook procedure by specifying
the WH_JOURNALPLAYBACK hook
type and the address of the hook procedure in a call to the SetWindowsHookEx function.
A Win32 JournalRecordProc
hook procedure does not need to live in a dynamic-link library. A Win32 JournalRecordProc
hook procedure can live in the application itself.
If the user
presses CTRL+ESC or CTRL+ALT+DEL during journal playback, the system stops the
playback, unhooks the journal playback procedure, and posts a WM_CANCELJOURNAL message to the journaling
application.
If the hook
procedure returns a message in the range WM_KEYFIRST to WM_KEYLAST, the
following conditions apply:
The paramL member of the
EVENTMSG structure specifies the virtual key code of the key that was pressed.
The paramH member of the
EVENTMSG structure specifies the scan code.
There s no way to specify a
repeast count. The event is always taken to represent one key event.
JournalPlaybackProc is a placeholder for an application-defined or
library-defined function name.
See Also