Obtención de informes de HID

En este artículo se describe cómo las aplicaciones en modo de usuario y los controladores en modo kernel obtienen informes HID de una colección HID.

Obtención de informes HID por aplicaciones en modo de usuario

En esta sección se describe la obtención de informes de entrada HID o informes de características HID, mediante aplicaciones en modo de usuario con ReadFile o las rutinas HidD_GetXxx.

Sin embargo, una aplicación solo debe usar las rutinas HidD_GetXxx para obtener el estado actual de un dispositivo. Si una aplicación intenta usar HidD_GetInputReport para obtener continuamente informes de entrada, se pueden perder los informes. Además, algunos dispositivos no admiten HidD_GetInputReport y dejan de responder si se usa esta rutina.

Uso de ReadFile

Una aplicación usa el identificador de archivo abierto que obtuvo mediante CreateFile para abrir un archivo en la colección. Cuando la aplicación llama a ReadFile, no tiene que especificar la E/S superpuesta porque los búferes de controladores cliente HID notifican en un búfer de anillo. Sin embargo, una aplicación puede usar E/S superpuesta para tener más de una solicitud de lectura pendiente.

Uso de rutinas de HidD_GetXxx

Una aplicación puede usar las siguientes rutinas de compatibilidad de HIDClass para obtener los informes de entrada y los informes de características más actuales de una colección HID:

• HidD_GetInputReport: devuelve un informe de entrada de una colección HID (Windows XP y versiones posteriores).
• HidD_GetFeature: devuelve un informe de características de una colección HID.

Una aplicación puede solicitar la devolución de un informe específico. Para recuperar un informe específico mediante rutinas HidD_GetXxx, la aplicación asigna el búfer de salida del informe, inicializa a cero el búfer y establece el primer byte del búfer con el identificador de informe específico. Para obtener más información, consulte Inicialización de informes HID.

Obtención de informes HID por controladores en modo kernel

En esta sección se describe cómo un controlador en modo kernel debe usar solicitudes IRP_MJ_READ como enfoque principal para obtener informes de entrada HID continuamente.

Las solicitudes de lectura consecutivas devuelven informes de entrada en el orden en que se recibieron de la colección. El controlador también puede usar solicitudes IOCTL_HID_GET_Xxx para obtener informes de entrada y características. Sin embargo, un controlador solo debe usar solicitudes IOCTL_HID_GET_Xxx para obtener el estado actual de un dispositivo. Si el controlador intenta usar IOCTL_HID_GET_INPUT_REPORT para obtener continuamente informes de entrada, se pueden perder informes. Además, algunos dispositivos no admiten IOCTL_HID_GET_INPUT_REPORT y dejan de responder si se usa esta solicitud.

Uso de solicitudes IRP_MJ_READ

Para obtener información general sobre cómo usar y reutilizar paquetes de solicitud de E/S (IRP), consulte Control de IRP y Reutilización de IRP.

Si un controlador reutiliza un IRP, la rutina IoCompletion del IRP debe completar la solicitud con un estado de STATUS_MORE_PROCESSING_REQUIRED (y no liberar el IRP). Cuando el controlador ya no requiere IRP, debe completarse y liberar el IRP llamando a IoCompleteRequest e IoFreeIrp. Por ejemplo, un controlador puede completar y liberar el IRP en su rutina de descarga o después de quitar un dispositivo.

Si un controlador usa un IRP solo para una solicitud de lectura, la rutina IoCompletion del IRP debe completarse y liberar el IRP y devolver STATUS_SUCCESS.

Para que un controlador pueda solicitar un informe de entrada, primero debe asignar un búfer de informe de entrada inicializado a cero desde un grupo de memoria no paginado. El tamaño, en bytes, del búfer se especifica mediante el miembro InputReportByteLength de la estructura HIDP_CAPS de una colección HID. A continuación, un controlador debe usar una MDL para asignar el búfer del informe de entrada para una solicitud de lectura. El controlador llama a IoAllocateMdl para asignar la MDL para un búfer de informe de entrada y establece el miembro Irp->MdlAddress de IRP leído con la dirección MDL del búfer del informe de entrada. El controlador debe liberar el búfer del informe y el MDL cuando ya no sean necesarios.

Además de establecer la dirección MDL de IRP de lectura, el controlador también debe establecer la ubicación de la pila de E/S del siguiente controlador de nivel inferior. Un controlador obtiene acceso a la ubicación de la pila de E/S del siguiente controlador de nivel inferior mediante una llamada a IoGetNextIrpStackLocation. El controlador establece los siguientes miembros de la ubicación de la pila de E/S:

• Parameters.Read.Length: se establece con el tamaño, en bytes, del búfer de lectura. El tamaño debe ser mayor o igual que el valor especificado por el miembro InputReportByteLength de la estructura HIDP_CAPS de una colección HID.
• Parameters.Read.Key: se establece en cero.
• Parameters.Read.ByteOffset.QuadPart: se establece en cero.
• MajorFunction: se establece en IRP_MJ_READ.
• FileObject: se establece en el puntero del objeto de archivo que representa el archivo abierto en la colección HID.

Una vez que el controlador obtiene un informe de entrada, puede acceder a los datos de control, como se describe en Interpretación de informes HID.

Uso de solicitudes IOCTL_HID_GET_Xxx

Un controlador puede usar las siguientes solicitudes de E/S para obtener los informes de entrada y características más actuales de una colección HID:

• IOCTL_HID_GET_INPUT_REPORT: devuelve un informe de entrada de una colección HID (Windows XP y versiones posteriores).
• IOCTL_HID_GET_FEATURE: devuelve un informe de características de una colección HID.

Un controlador puede solicitar la devolución de un informe específico. Para recuperar un informe específico mediante estas solicitudes de E/S, el controlador asigna primero el búfer del informe de salida y, a continuación, inicializa a cero el búfer y establece el primer byte del búfer con el identificador del informe específico.

Para obtener más información, consulte Interpretación de informes HID.