Moufiltr Driver Reference

Moufiltr is designed to be used with Mouclass, the system class driver for mouse devices used with Windows 2000 and later versions, and I8042prt, the function driver for a PS/2-style mouse used with Windows 2000 and later. Moufiltr demonstrates how to filter I/O requests and add callback routines that modify the operation of Mouclass and I8042prt.

  • The ntddmou.h WDK header file.
  • Moufiltr sample source code in the MSDN Code Gallery.

Moufiltr IOCTLs

This section includes the following topics about Moufiltr, the sample upper-level mouse filter driver in the MSDN Code Gallery:

In this section

Control CodeDescription

IOCTL_INTERNAL_I8042_HOOK_MOUSE

The IOCTL_INTERNAL_I8042_HOOK_MOUSE request adds an ISR callback routine to the I8042prt mouse ISR. The ISR callback is optional and is provided by an upper-level mouse filter driver.

I8042prt sends this request after it receives an IOCTL_INTERNAL_MOUSE_CONNECT request. I8042prt sends a synchronous IOCTL_INTERNAL_I8042_HOOK_MOUSE request to the top of the mouse device stack.

After Moufiltr receives the hook mouse request, it filters the request in the following way:

  • Saves the upper-level information passed to Moufiltr, which includes the context of an upper-level device object 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 Moufiltr ISR callbacks can use

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

I8042prt Callback Routines

Moufiltr Callback Routines

IOCTL_INTERNAL_MOUSE_CONNECT

The IOCTL_INTERNAL_MOUSE_CONNECT request connects Mouclass service to a mouse device. Mouclass sends this request down the device stack before it opens a mouse device.

After Moufiltr receives the mouse connect request, it filters the request in the following way:

  1. Saves a copy of the CONNECT_DATA (Mouclass) structure that was passed to Moufiltr

  2. Substitutes its own connect information for the class driver connect information

  3. Sends the IOCTL_INTERNAL_MOUSE_CONNECT request down the device stack

If the request is not successful, Moufiltr completes the request with an appropriate error status.

Moufiltr provides a template for a filter service callback routine that can supplement the operation of MouseClassServiceCallback, the Mouclass service callback routine. The filter service callback can filter the input data that is transferred from the device input buffer to the class driver data queue.

For more information about the connection of the Mouclass service, see the following topics:

I8042prt Callback Routines

Moufiltr Callback Routines

IOCTL_INTERNAL_MOUSE_DISCONNECT

The IOCTL_INTERNAL_MOUSE_DISCONNECT request is completed by Moufiltr with an error status of STATUS_NOT_IMPLEMENTED. (Note that a Plug and Play mouse device can be added or removed by the Plug and Play manager.)

 

For all other requests, Moufiltr skips the current IRP stack and sends the request down the device stack without further processing.

Callback routines implemented by Kbfiltr

MouFilter_IsrHook (See PI8042_MOUSE_ISR)


/*
Parameters
DeviceObject 
Pointer to the filter device object of the driver that supplies this callback.

CurrentInput 
Pointer to the input MOUSE_INPUT_DATA structure being constructed by the ISR.

CurrentOutput 
Pointer to the OUTPUT_PACKET structure that specifies the bytes being written to the hardware device.

StatusByte 
Specifies a status byte that is read from I/O port 60 when the interrupt occurs.

DataByte 
Specifies a data byte that is read from I/O port 64 when the interrupt occurs.

ContinueProcessing 
Specifies, if TRUE, that the I8042prt mouse ISR continues processing after this callback returns. Otherwise, processing is not continued.

MouseState 
Pointer to a MOUSE_STATE enumeration value, which identifies the state of mouse input.

ResetSubState 
Pointer to MOUSE_RESET_SUBSTATE enumeration value, which identifies the mouse reset substate. See the Remarks section.

Return value
MouFilter_IsrHook returns TRUE if the interrupt service routine should continue; otherwise it returns FALSE.


*/

BOOLEAN MouFilter_IsrHook(
   PDEVICE_OBJECT        DeviceObject,
   PMOUSE_INPUT_DATA     CurrentInput,
   POUTPUT_PACKET        CurrentOutput,
   UCHAR                 StatusByte,
   PUCHAR                DataByte,
   PBOOLEAN              ContinueProcessing,
   PMOUSE_STATE          MouseState,
   PMOUSE_RESET_SUBSTATE ResetSubState
);

A MouFilter_IsrHook callback is not needed if the default operation of I8042prt is sufficient. The I8042prt mouse ISR calls MouFilter_IsrHook after it validates the interrupt. To reset a mouse, I8042prt goes through a sequence of operational substates, each one of which is identified by an MOUSE_RESET_SUBSTATE enumeration value. For more information about how I8042prt resets a mouse and the corresponding mouse reset substates, see the documentation of MOUSE_RESET_SUBSTATE in ntdd8042.h. MouFilter_IsrHook runs in kernel mode at the IRQL of the I8042prt mouse ISR.

MouFilter_ServiceCallback (See PSERVICE_CALLBACK_ROUTINE)


/*
Parameters
DeviceObject [in] 
Pointer to the class device object.

InputDataStart [in] 
Pointer to the first mouse input data packet in the input data buffer of the port device.

InputDataEnd [in] 
Pointer to the mouse input data packet immediately following the last data packet in the port device's input data buffer.

InputDataConsumed [in, out] 
Pointer to the number of mouse input data packets that are transferred by the routine.

Return value
None


*/


VOID MouFilter_ServiceCallback(
  _In_    PDEVICE_OBJECT    DeviceObject,
  _In_    PMOUSE_INPUT_DATA InputDataStart,
  _In_    PMOUSE_INPUT_DATA InputDataEnd,
  _Inout_ PULONG            InputDataConsumed
);



The ISR DPC of I8042prt calls MouFilter_ServiceCallback, which then calls MouseClassServiceCallback. A filter service callback can be configured 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.

 

 

Send comments about this topic to Microsoft

Show: