função HidP_GetUsages (hidpi.h)

Artigo
03/01/2024

A rotina HidP_GetUsages retorna uma lista de todos os usos do botão de controle HID que estão em uma página de uso especificada e são definidos como ON em um relatório HID.

Sintaxe

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 um valor de enumerador HIDP_REPORT_TYPE que identifica o tipo de relatório.

[in] UsagePage

Especifica a página de uso dos usos do botão. A rotina retorna apenas informações sobre botões nesta página de uso.

[in] LinkCollection

Especifica a coleção de links dos usos de botão. Se LinkCollection for diferente de zero, a rotina retornará apenas informações sobre os botões que esta coleção de links contém; caso contrário, se LinkCollection for zero, a rotina retornará informações sobre todos os botões na coleção de nível superior associada a PreparsedData.

[out] UsageList

Ponteiro para um buffer alocado pelo chamador que a rotina usa para retornar os usos de todos os botões definidos como ON e pertencem à página de uso especificada por UsagePage.

[in, out] UsageLength

Especifica, na entrada, o comprimento, em elementos de matriz, do buffer UsageList . Especifica, na saída, o número de botões definidos como ON na página de uso especificada.

[in] PreparsedData

Ponteiro para os dados pré-preparados de uma coleção de nível superior.

[out] Report

Ponteiro para um relatório.

[in] ReportLength

Especifica o comprimento, em bytes, do relatório localizado em Relatório.

Retornar valor

HidP_GetUsages retorna um dos seguintes valores de status:

Código de retorno	Descrição
HIDP_STATUS_SUCCESS	A rotina retornou com êxito todos os usos de botão definidos como ON.
HIDP_INVALID_REPORT_LENGTH	O comprimento do relatório não é válido.
HIDP_INVALID_REPORT_TYPE	O tipo de relatório especificado não é válido.
HIDP_STATUS_BUFFER_TOO_SMALL	O buffer UsageList é muito pequeno para conter todos os usos atualmente definidos como ON na página de uso especificada.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	A coleção contém botões na página de uso especificada em um relatório do tipo especificado, mas não há esses usos no relatório especificado.
HIDP_STATUS_INVALID_PREPARSED_DATA	Os dados pré-preparados não são válidos.
HIDP_STATUS_USAGE_NOT_FOUND	A coleção não contém botões na página de uso especificada em nenhum relatório do tipo de relatório especificado.

Comentários

Aplicativos de modo de usuário e drivers de modo kernel chamam HidP_MaxUsageListLength para determinar o número máximo de botões que podem ser retornados para o tipo de relatório especificado. Como alternativa, aplicativos ou drivers podem chamar HidP_GetUsages e definir (*UsageLength) como zero para retornar o comprimento necessário em UsageLength. Em outras palavras, UsageLength deve ser um ponteiro válido que aponta para um valor ULONG 0 para obter o comprimento necessário.

Aplicativos ou drivers determinam o comprimento do relatório necessário dos membros XxxReportByteLength na estrutura HIDP_CAPS de uma coleção de nível superior.

Para obter mais informações, consulte Coleções HID.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 2000 e versões posteriores do Windows.
Plataforma de Destino	Universal
Cabeçalho	hidpi.h (inclua Hidpi.h)
Biblioteca	Hidparse.lib
IRQL	<= DISPATCH_LEVEL