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.

Kbfiltr IOCTLs

In this section

Control CodeDescription

IOCTL_INTERNAL_I8042_HOOK_KEYBOARD

The IOCTL_INTERNAL_I8042_HOOK_KEYBOARD request does the following:

  • Adds an initialization callback routine to the I8042prt keyboard initialization routine

  • Adds an ISR callback routine to the I8042prt keyboard ISR

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:

  • Saves the upper-level information passed to Kbfiltr, which includes the context of an upper-level device object, a pointer to an initialization callback, and a pointer to an ISR callback

  • Replaces the upper-level information with its own

  • Saves the context of I8042prt and pointers to callbacks that the Kbfiltr ISR callback can use

For more information about this request and the callbacks, see the following topics:

I8042prt Callback Routines

Kbfiltr Callback Routines

IOCTL_INTERNAL_KEYBOARD_CONNECT

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:

  • Saves a copy of Kbdclass's CONNECT_DATA (Kbdclass) structure that is passed to the filter driver by Kbdclass

  • Substitutes its own connect information for the class driver connect information

  • Sends the IOCTL_INTERNAL_KEYBOARD_CONNECT request down the device stack

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:

Kbdclass Class Service Callback Routine

Kbfiltr Callback Routines

IOCTL_INTERNAL_KEYBOARD_DISCONNECT

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 (see PI8042_KEYBOARD_INITIALIZATION_ROUTINE)

    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
    );
    
    
  • KbFilter_IsrHook (see PI8042_KEYBOARD_ISR)

    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
    );
    
    );
    
    

 

 

Send comments about this topic to Microsoft

Show: