Table of contents
TOC
Collapse the table of content
Expand the table of content

Sending HID Reports by Kernel-Mode Drivers

Last Updated: 8/3/2016

A kernel-mode driver should use IRP_MJ_WRITE requests as its main approach to continuously send output report to a HID collection. Drivers can also use IOCTL_HID_SET_Xxx requests to send output reports and feature reports to a collection. However, a driver should only use these I/O requests to set the current state of a collection. Some devices might not support IOCTL_HID_SET_OUTPUT_REPORT and will become unresponsive if this request is used.

For more information, see Using IRP_MJ_WRITE Requests and Using IOCTL_HID_SET_Xxx Requests.

Using IRP_MJ_WRITE Requests

Non-WDM Windows 2000 drivers, and drivers for Windows XP and later versions, can use a single IRP for all write requests sent to a collection. However, Windows 2000 WDM drivers must allocate a new IRP for each write request. For more information about how to use and reuse IRPs, see Handling IRPs and Reusing IRPs.

If the driver reuses a write IRP, the IRP's IoCompletion routine should complete the request with a status of STATUS_MORE_PROCESSING_REQUIRED (and not free the IRP). When the driver no longer requires the IRP, it should complete and free the IRP by calling IoCompleteRequest and IoFreeIrp. For example, a driver might typically complete and free the IRP in its Unload routine, or after a device is removed.

If a driver uses an IRP for only one write request, the IRP's IoCompletion routine should complete and free the IRP, and return STATUS_SUCCESS.

Before sending an output report, a driver must first initialize and set an output report buffer, as described in Initializing HID Reports. The driver must then use an MDL to map the output report buffer for a write request. A driver calls IoAllocateMdl to allocate the MDL for an output report, and sets a write IRP's Irp->MdlAddress member to the MDL address of the output report buffer. The driver must free the report buffer and the MDL when they are no longer required.

In addition to setting the write IRP's MDL address, the driver must also set the I/O stack location of the next lower-level driver. A driver obtains access to the I/O stack location of the next lower-level driver by calling IoGetNextIrpStackLocation. The driver sets the following members of the I/O stack location:

Parameters.Write.Length
Set to the length, in bytes, of an output report. This should be set to the length of a HID collection's output reports, as specified by the OutputReportByteLength member of a collection's HIDP_CAPS structure.

Parameters.Write.Key
Set to zero.

Parameters.Write.ByteOffset.QuadPart
Set to zero.

MajorFunction
Set to IRP_MJ_WRITE.

FileObject
Set to the file object pointer that represents the open file on the HID collection.

Using IOCTL_HID_SET_Xxx Requests

A driver can also use the following I/O requests to send output and feature reports to a HID collection:

IOCTL_HID_SET_OUTPUT_REPORT
Sends an output report to a collection (Windows XP and later versions).

IOCTL_HID_SET_FEATURE
Sends a feature report to a collection.


Send comments about this topic to Microsoft

© 2016 Microsoft