Interpretación de informes de HID

En este artículo se describe cómo las aplicaciones de modo usuario y los controladores de modo kernel utilizan las rutinas de soporte HidP_Xxx de HIDClass 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 sujeto a escala.
• 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 que las aplicaciones y controladores usen HidP_GetUsageValueArray, deben asignar un búfer inicializado en cero lo suficientemente grande como para contener el array 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 correspondiente al valor de uso, redondeado hacia arriba al byte más cercano.

Extracción de usos de botón establecidos en ON

Para extraer los usos de HID de botones configurados en ON (1), las aplicaciones y los controladores llaman a una de las siguientes funciones de soporte de HID:

• HidP_GetButtons (o HidP_GetUsages) Devuelve el identificador de uso de todos los botones de una página de uso especificada que están activados.
• HidP_GetButtonsEx (o HidP_GetUsagesEx) devuelve la página de uso y el identificador de uso de todos los botones que están activados.

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 botones en una página de uso especificada en el informe. Si la aplicación o el controlador especifica una página de usos de cero, la rutina devuelve el número total de usos de botones en el informe.

El tamaño de búfer necesario, en bytes, es:

• (Para HidP_GetButtons) El valor devuelto por HidP_MaxUsageListLength multiplicado por sizeof(USAGE)
• (Para HidP_GetButtonsEx) El valor devuelto por HidP_MaxUsageListLength multiplicado por el tamaño de USAGE_AND_PAGE.

Después de que una aplicación o controlador utilice estas rutinas para obtener información sobre qué botones están activados, puede determinar la diferencia entre el estado actual y el estado 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:

• HidP_UsageListDifference
• HidP_UsageAndPageListDifference

Definició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 soporte HIDClass:

• HidP_SetButtons (o HidP_SetUsages) Establece un conjunto especificado de botones en ON (1).
• HidP_UnsetButtons (o HidP_UnsetUsages) desactiva un conjunto especificado de botones, poniéndolos en cero.

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 soporte de HIDClass:

• HidP_GetData
• HidP_SetData

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 del HID, debe llamar a HidP_GetUsageValue por 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.

Consulte también

• Inicializando informes de HID