función HidP_GetUsages (hidpi.h)

Artículo
08/07/2023

La rutina HidP_GetUsages devuelve una lista de todos los usos del botón de control HID que se encuentran en una página de uso especificada y se establecen en ON en un informe HID.

Sintaxis

NTSTATUS HidP_GetUsages(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [out]     PUSAGE               UsageList,
  [in, out] PULONG               UsageLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [out]     PCHAR                Report,
  [in]      ULONG                ReportLength
);

Parámetros

[in] ReportType

Especifica un valor de enumerador HIDP_REPORT_TYPE que identifica el tipo de informe.

[in] UsagePage

Especifica la página de uso de los usos del botón. La rutina solo devuelve información sobre los botones de esta página de uso.

[in] LinkCollection

Especifica la colección de vínculos de los usos del botón. Si LinkCollection es distinto de cero, la rutina solo devuelve información sobre los botones que contiene esta colección de vínculos; de lo contrario, si LinkCollection es cero, la rutina devuelve información sobre todos los botones de la colección de nivel superior asociada a PreparsedData.

[out] UsageList

Puntero a un búfer asignado por el autor de la llamada que la rutina usa para devolver los usos de todos los botones que se establecen en ON y pertenecen a la página de uso especificada por UsagePage.

[in, out] UsageLength

Especifica, en la entrada, la longitud, en los elementos de matriz, del búfer UsageList . Especifica, en la salida, el número de botones que se establecen en ON en la página de uso especificada.

[in] PreparsedData

Puntero a los datos preparados de una colección de nivel superior.

[out] Report

Puntero a un informe.

[in] ReportLength

Especifica la longitud, en bytes, del informe ubicado en Informe.

Valor devuelto

HidP_GetUsages devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
HIDP_STATUS_SUCCESS	La rutina devolvió correctamente todos los usos de botón establecidos en ON.
HIDP_INVALID_REPORT_LENGTH	La longitud del informe no es válida.
HIDP_INVALID_REPORT_TYPE	El tipo de informe especificado no es válido.
HIDP_STATUS_BUFFER_TOO_SMALL	El búfer UsageList es demasiado pequeño para contener todos los usos que se establecen actualmente en ON en la página de uso especificada.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	La colección contiene botones en la página de uso especificada en un informe del tipo especificado, pero no hay tales usos en el informe especificado.
HIDP_STATUS_INVALID_PREPARSED_DATA	Los datos preparados no son válidos.
HIDP_STATUS_USAGE_NOT_FOUND	La colección no contiene botones en la página de uso especificada en ningún informe del tipo de informe especificado.

Comentarios

Las aplicaciones en modo de usuario y los controladores en modo kernel llaman a HidP_MaxUsageListLength para determinar el número máximo de botones que se pueden devolver para el tipo de informe especificado. Como alternativa, las aplicaciones o los controladores pueden llamar a HidP_GetUsages y establecer (*UsageLength) en cero para devolver la longitud necesaria en UsageLength. En otras palabras, UsageLength debe ser un puntero válido que apunte a un valor de ULONG 0 para obtener la longitud necesaria.

Las aplicaciones o los controladores determinan la longitud de informe necesaria de los miembros XxxReportByteLength en la estructura de HIDP_CAPS de una colección de nivel superior.

Para obtener más información, consulte Colecciones HID.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 2000 y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	hidpi.h (include Hidpi.h)
Library	Hidparse.lib
IRQL	<= DISPATCH_LEVEL