Interpretació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 usan las rutinas de compatibilidad de HidP_XxxHIDClass para interpretar los datos de control en un informe HID.
Extracción de datos de valor especificando su uso
Para extraer datos de valor de un informe HID, una aplicación o controlador puede usar una de las siguientes rutinas de soporte técnico de HID:
- HidP_GetScaledUsageValue Devuelve un valor con signo y escalado.
- HidP_GetUsageValue Devuelve un valor no escalado en un formato sin signo o un valor escalado que está fuera de su intervalo Normal.
- HidP_GetUsageValueArray Devuelve una matriz de valores de uso.
Para usar aplicaciones y controladores HidP_GetUsageValueArray debe asignar un búfer inicializado a cero, que sea lo suficientemente grande como para contener la matriz de valores de uso. El tamaño necesario en bytes es el producto de los miembros BitSize y ReportCount de la estructura HIDP_VALUE_CAPS de la matriz de valores de uso, redondeado al byte más cercano.
Extracción de usos de botón establecidos en ON
Para extraer los usos de HID de botones establecidos en ON (1), las aplicaciones y los controladores llaman a una de las siguientes rutinas de compatibilidad de HID:
- HidP_GetButtons (o HidP_GetUsages) Devuelve el identificador de uso de todos los botones de una página de uso especificada establecidos en ON.
- HidP_GetButtonsEx (o HidP_GetUsagesEx) Devuelve la página de uso y el identificador de uso de todos los botones establecidos en ON.
Estas rutinas devuelven una matriz de toda la información de uso de todos los botones que actualmente están establecidos en ON. Implícitamente, los botones cuyo uso no devuelve estas rutinas se establecen en OFF (cero).
Para llamar a estas rutinas, las aplicaciones y los controladores deben asignar primero e inicializar a cero el búfer usado para devolver la matriz de usos de botón. Una aplicación o controlador llama a HidP_MaxUsageListLength para determinar el número de usos de botón en una página de uso especificada en el informe. Si la aplicación o el controlador especifica una página de uso de cero, la rutina devuelve el número de todos los usos de botón del informe.
El tamaño de búfer necesario, en bytes, es:
- (Para HidP_GetButtons) El valor devuelto por HidP_MaxUsageListLength veces el tamaño de (USAGE)
- (Para HidP_GetButtonsExs) El valor devuelto por HidP_MaxUsageListLength veces el tamaño de (USAGE_AND_PAGE)
Después de que una aplicación o controlador use estas rutinas para obtener información sobre los botones que están establecidos en ON, puede determinar la diferencia entre el estado actual y el anterior de los botones llamando a una de las siguientes rutinas de compatibilidad de HIDClass. Estas rutinas devuelven la diferencia entre dos matrices de información de uso:
Extracción y configuración de datos de control por índices de datos
Para usar índices de datos para extraer y establecer datos de control en un informe HID, una aplicación o controlador puede usar las siguientes rutinas de compatibilidad con HIDClass:
Estas rutinas son útiles para una aplicación o controlador que proporciona un servicio de "valor añadido". Por ejemplo, una que proporciona una interfaz personalizada a todos los controles admitidos por un dispositivo HIDClass. Microsoft DirectInput es un ejemplo.
Una aplicación o controlador que llama a estas rutinas puede obtener y establecer de forma más eficaz todos los valores de un informe. Por ejemplo, para obtener todos los datos de valor por sus usos de HID, debe llamar a HidP_GetUsageValue para cada uso. Sin embargo, para obtener todos los datos de valor por índice de datos, solo tiene que llamar a HidP_GetData una vez.
Una aplicación o controlador usa los índices de datos especificados en las matrices de funcionalidad de botón de una colección y matrices de funcionalidad de valor para identificar los usos de HID.
Configuración de datos de valor especificando su uso
Una aplicación o controlador puede establecer un valor en un informe HID inicializado correctamente llamando a una de las siguientes rutinas de compatibilidad de HID:
- HidP_SetScaledUsageValue Establece un valor con signo y escalado en un informe.
- HidP_SetUsageValue Establece un valor en un informe.
- HidP_SetUsageValueArray Establece una matriz de valores de uso en un informe.
Configuración del estado del botón especificando su uso
Una aplicación o controlador puede establecer el estado de los botones en un informe HID inicializado correctamente llamando a una de las siguientes rutinas de compatibilidad con HIDClass:
- HidP_SetButtons (o HidP_SetUsages) Establece un conjunto especificado de botones en ON (1).
- HidP_UnsetButtons (o HidP_UnsetUsages) Establece un conjunto especificado de botones en OFF (cero).
Extracción y configuración de datos de control de HID por índices de datos
Para usar índices de datos para extraer y establecer datos de control en un informe HID, una aplicación o controlador puede usar las siguientes rutinas de compatibilidad con HIDClass:
Estas rutinas son útiles para una aplicación o controlador que proporciona un servicio de "valor añadido". Por ejemplo, una que proporciona una interfaz personalizada a todos los controles admitidos por un dispositivo HIDClass. Microsoft DirectInput es un ejemplo.
Una aplicación o controlador que llama a estas rutinas puede obtener y establecer de forma más eficaz todos los valores de un informe. Por ejemplo, para obtener todos los datos de valor por sus usos de HID, debe llamar a HidP_GetUsageValue para cada uso. Sin embargo, para obtener todos los datos de valor por índice de datos, solo tiene que llamar a HidP_GetData una vez.
Una aplicación o controlador usa los índices de datos especificados en las matrices de funcionalidad de botón de una colección y matrices de funcionalidad de valor para identificar los usos de HID.