Kbfiltr Driver Reference
Kbfiltr is designed to be used with Kbdclass, the system class driver for keyboard devices that are used with Windows 2000 and later versions, and I8042prt, the function driver for a PS/2-style keyboard used with Windows 2000 and later versions. Kbfiltr demonstrates how to filter I/O requests and how to add callback routines that modify the operation of Kbdclass and I8042prt.
For more information about Kbfiltr operation, see the following:
- The ntddkbd.h WDK header file.
- The sample Kbfiltr source code in the MSDN Code Gallery.
The IOCTL_INTERNAL_I8042_HOOK_KEYBOARD request does the following:
The initialization and ISR callbacks are optional and are provided by an upper-level filter driver for a PS/2-style keyboard device.
After I8042prt receives an IOCTL_INTERNAL_KEYBOARD_CONNECT request, it sends a synchronous IOCTL_INTERNAL_I8042_HOOK_KEYBOARD request to the top of the keyboard device stack.
After Kbfiltr receives the hook keyboard request, Kbfiltr filters the request in the following way:
For more information about this request and the callbacks, see the following topics:
The IOCTL_INTERNAL_KEYBOARD_CONNECT request connects the Kbdclass service to the keyboard device. Kbdclass sends this request down the keyboard device stack before it opens the keyboard device.
After Kbfiltr received the keyboard connect request, Kbfiltr filters the connect request in the following way:
If the request is not successful, Kbfiltr completes the request with an appropriate error status.
Kbfiltr provides a template for a filter service callback routine that can supplement the operation of KeyboardClassServiceCallback, the Kbdclass class service callback routine. The filter service callback can filter the input data that is transferred from the device input buffer to the class data queue.
For more information about the connection of the Kbdclass service, see the following topics:
The IOCTL_INTERNAL_KEYBOARD_DISCONNECT request is completed with a status of STATUS_NOT_IMPLEMENTED. Note that a Plug and Play keyboard can be added or removed by the Plug and Play manager.
For all other device control requests, Kbfiltr skips the current IRP stack and sends the request down the device stack without further processing.
Callback routines implemented by Kbfiltr
KbFilter_InitializationRoutine is not needed if I8042prt's default initialization of a keyboard is sufficient.
I8042prt calls KbFilter_InitializationRoutine when it initializes the keyboard. Default keyboard initialization includes the following operations: reset the keyboard, set the typematic rate and delay, and set the light-emitting diodes (LED).
/* Parameters DeviceObject [in] Pointer to the device object that is the context for this callback. SynchFuncContext [in] Pointer to the context for the routines pointed to by ReadPort and Writeport. ReadPort [in] Pointer to the system-supplied PI8042_SYNCH_READ_PORT callback that reads from the port. WritePort [in] Pointer to the system-supplied PI8042_SYNCH_WRITE_PORT callback that writes to the port. TurnTranslationOn [out] Specifies, if TRUE, to turn translation on. Otherwise, translation is turned off. Return value KbFilter_InitializationRoutine returns an appropriate NTSTATUS code. */ NTSTATUS KbFilter_InitializationRoutine( _In_ PDEVICE_OBJECT DeviceObject, _In_ PVOID SynchFuncContext, _In_ PI8042_SYNCH_READ_PORT ReadPort, _In_ PI8042_SYNCH_WRITE_PORT WritePort, _Out_ PBOOLEAN TurnTranslationOn );
This callback is not needed if the default operation of I8042prt is sufficient.
The I8042prt keyboard ISR calls KbFilter_IsrHook after it validates the interrupt and reads the scan code.
KbFilter_IsrHook runs in kernel mode at the IRQL of the I8042prt keyboard ISR.
/* Parameters DeviceObject [in] Pointer to the filter device object of the driver that supplies this callback. CurrentInput [in] Pointer to the input KEYBOARD_INPUT_DATA structure that is being constructed by the ISR. CurrentOutput [in] Pointer to an OUTPUT_PACKET structure that specifies the bytes that are being written to the hardware device. StatusByte [in, out] Specifies the status byte that is read from I/O port 60 when an interrupt occurs. DataByte [in] Specifies the data byte that is read from I/O port 64 when an interrupt occurs. ContinueProcessing [out] Specifies, if TRUE, to continue processing in the I8042prt keyboard ISR after this callback returns; otherwise, processing is not continued. ScanState [in] Pointer to a KEYBOARD_SCAN_STATE structure that specifies the keyboard scan state. Return value KbFilter_IsrHook returns TRUE if the interrupt service routine should continue; otherwise it returns FALSE. */ KbFilter_IsrHook KbFilter_IsrHook( _In_ PDEVICE_OBJECT DeviceObject, _In_ PKEYBOARD_INPUT_DATA CurrentInput, _In_ POUTPUT_PACKET CurrentOutput, _Inout_ UCHAR StatusByte, _In_ PUCHAR DataByte, _Out_ PBOOLEAN ContinueProcessing, _In_ PKEYBOARD_SCAN_STATE ScanState ); );
- KbFilter_ServiceCallback (see PSERVICE_CALLBACK_ROUTINE)
The ISR dispatch completion routine of the function driver calls KbFilter_ServiceCallback, which then calls the keyboard class driver's implementation of PSERVICE_CALLBACK_ROUTINE. A vendor can implement a filter service callback to modify the input data that is transferred from the device's input buffer to the class data queue. For example, the callback can delete, transform, or insert data.
/* Parameters DeviceObject [in] Pointer to the class device object. InputDataStart [in] Pointer to the first keyboard input data packet in the input data buffer of the port device. InputDataEnd [in] Pointer to the keyboard input data packet that immediately follows the last data packet in the input data buffer of the port device. InputDataConsumed [in, out] Pointer to the number of keyboard input data packets that are transferred by the routine. Return value None */ VOID KbFilter_ServiceCallback( _In_ PDEVICE_OBJECT DeviceObject, _In_ PKEYBOARD_INPUT_DATA InputDataStart, _In_ PKEYBOARD_INPUT_DATA InputDataEnd, _Inout_ PULONG InputDataConsumed ); );