Отправка отчетов HID

В этом разделе описывается, как приложения пользовательского режима и драйверы режима ядра отправляют отчеты HID в коллекцию HID.

Отправка отчетов HID по приложениям User-Mode

Приложение в пользовательском режиме должно использовать WriteFile в качестве main подхода для непрерывной отправки выходных отчетов в коллекцию HID. Приложение также может использовать HidD_SetXxx подпрограммы для отправки выходных отчетов и отчетов о функциях в коллекцию. Однако приложение должно использовать эти подпрограммы только для задания текущего состояния коллекции. Некоторые устройства могут не поддерживать HidD_SetOutputReport и перестают отвечать на запросы при использовании этой процедуры.

Использование WriteFile

Приложение должно использовать запросы на запись для отправки выходных отчетов в коллекцию HID. После того как приложение пользовательского режима создало выходной отчет, оно может отправить выходной отчет в коллекцию с помощью WriteFile.

Использование процедур HidD_SetXxx

Приложение может использовать следующие процедуры поддержки HIDClass для отправки отчетов HID в коллекцию HID:

HidD_SetOutputReport Отправляет выходной отчет в коллекцию HID (Windows XP и более поздние версии).

HidD_SetFeature Отправляет отчет о функциях в коллекцию HID.

Отправка отчетов HID по драйверам Kernel-Mode

Драйвер режима ядра должен использовать IRP_MJ_WRITE запросы в качестве main подхода для непрерывной отправки выходных отчетов в коллекцию HID. Драйверы также могут использовать IOCTL_HID_SET_Xxx запросы для отправки выходных отчетов и отчетов о функциях в коллекцию. Однако драйвер должен использовать только эти запросы ввода-вывода для задания текущего состояния коллекции. Некоторые устройства могут не поддерживать IOCTL_HID_SET_OUTPUT_REPORT и перестают отвечать на запросы.

Использование запросов IRP_MJ_WRITE

Драйверы Windows 2000, отличные от WDM, и драйверы для Windows XP и более поздних версий могут использовать одну IRP для всех запросов на запись, отправленных в коллекцию. Однако драйверы Windows 2000 WDM должны выделять новый IRP для каждого запроса на запись. Дополнительные сведения об использовании и повторном использовании IRP см. в разделе Обработка ИРП и повторное использование IRP.

Если драйвер повторно использует IRP для записи, подпрограмма IoCompletion IRP должна завершить запрос с состоянием STATUS_MORE_PROCESSING_REQUIRED (а не освобождать IRP). Если драйвер больше не требует IRP, он должен завершить и освободить IRP, вызвав IoCompleteRequest и IoFreeIrp. Например, драйвер обычно может завершить и освободить IRP в процедуре выгрузки или после удаления устройства.

Если драйвер использует IRP только для одного запроса на запись, процедура IoCompletion IRP должна завершить и освободить IRP, а также вернуть STATUS_SUCCESS.

Перед отправкой выходного отчета драйвер должен сначала инициализировать и задать буфер выходного отчета, как описано в разделе Инициализация отчетов HID. Затем драйвер должен использовать MDL для сопоставления буфера выходного отчета для запроса на запись. Драйвер вызывает IoAllocateMdl, чтобы выделить MDL для выходного отчета, и задает для элемента IRP-MdlAddress записи MDL-адрес> MDL выходного буфера отчета. Драйвер должен освободить буфер отчета и MDL, если они больше не требуются.

Помимо задания MDL-адреса IRP записи, драйвер также должен задать расположение стека ввода-вывода для следующего драйвера нижнего уровня. Драйвер получает доступ к расположению стека ввода-вывода следующего драйвера нижнего уровня, вызывая IoGetNextIrpStackLocation. Драйвер задает следующие элементы расположения стека ввода-вывода:

Parameters.Write.Length
Задайте длину выходного отчета в байтах. Это значение должно иметь длину выходных отчетов коллекции HID, как указано в элементе OutputReportByteLength структуры HIDP_CAPS коллекции.

Parameters.Write.Key
Задайте нулевое значение.

Parameters.Write.ByteOffset.QuadPart
Задайте нулевое значение.

MajorFunction
Задайте значение IRP_MJ_WRITE.

FileObject
Задайте для указателя объекта файла, который представляет открытый файл в коллекции HID.

Использование запросов IOCTL_HID_SET_Xxx

Драйвер также может использовать следующие запросы ввода-вывода для отправки выходных и функциональных отчетов в коллекцию HID:

IOCTL_HID_SET_OUTPUT_REPORT
Отправляет выходной отчет в коллекцию (Windows XP и более поздние версии).

IOCTL_HID_SET_FEATURE
Отправляет отчет о функциях в коллекцию.