HidP_GetUsages 함수(hidpi.h)

아티클
08/07/2023

HidP_GetUsages 루틴은 지정된 사용량 페이지에 있고 HID 보고서에서 ON으로 설정된 모든 HID 컨트롤 단추 사용량 목록을 반환합니다.

구문

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
);

매개 변수

[in] ReportType

보고서 형식을 식별하는 HIDP_REPORT_TYPE 열거자 값을 지정합니다.

[in] UsagePage

단추 사용량의 사용 페이지를 지정합니다. 루틴은 이 사용 페이지의 단추에 대한 정보만 반환합니다.

[in] LinkCollection

단추 사용의 링크 컬렉션을 지정합니다. LinkCollection이 0이 아닌 경우 루틴은 이 링크 컬렉션에 포함된 단추에 대한 정보만 반환합니다. 그렇지 않으면 LinkCollection이 0이면 루틴은 PreparsedData와 연결된 최상위 컬렉션의 모든 단추에 대한 정보를 반환합니다.

[out] UsageList

루틴이 ON으로 설정되고 UsagePage에서 지정한 사용량 페이지에 속하는 모든 단추의 사용을 반환하는 데 사용하는 호출자 할당 버퍼에 대한 포인터입니다.

[in, out] UsageLength

입력에서 UsageList 버퍼의 길이(배열 요소)를 지정합니다. 출력 시 지정된 사용량 페이지에서 ON으로 설정된 단추 수를 지정합니다.

[in] PreparsedData

최상위 컬렉션의 준비 데이터에 대한 포인터입니다.

[out] Report

보고서에 대한 포인터입니다.

[in] ReportLength

보고서에 있는 보고서의 길이(바이트)를 지정합니다.

반환 값

HidP_GetUsages 다음 상태 값 중 하나를 반환합니다.

반환 코드	설명
HIDP_STATUS_SUCCESS	루틴이 ON으로 설정된 모든 단추 사용을 성공적으로 반환했습니다.
HIDP_INVALID_REPORT_LENGTH	보고서 길이가 잘못되었습니다.
HIDP_INVALID_REPORT_TYPE	지정한 보고서 형식이 잘못되었습니다.
HIDP_STATUS_BUFFER_TOO_SMALL	UsageList 버퍼가 너무 작아서 지정된 사용량 페이지에서 현재 ON으로 설정된 모든 사용량을 보유할 수 없습니다.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	컬렉션에는 지정된 형식의 보고서에 지정된 사용량 페이지의 단추가 포함되어 있지만 지정된 보고서에는 이러한 사용법이 없습니다.
HIDP_STATUS_INVALID_PREPARSED_DATA	준비한 데이터가 잘못되었습니다.
HIDP_STATUS_USAGE_NOT_FOUND	컬렉션에는 지정된 보고서 유형의 보고서에 지정된 사용량 페이지의 단추가 포함되어 있지 않습니다.

설명

사용자 모드 애플리케이션 및 커널 모드 드라이버는 HidP_MaxUsageListLength 호출하여 지정된 보고서 유형에 대해 반환할 수 있는 최대 단추 수를 결정합니다. 또는 애플리케이션 또는 드라이버가 HidP_GetUsages 호출하고 (*UsageLength) 를 0으로 설정하여 UsageLength에서 필요한 길이를 반환할 수 있습니다. 즉, UsageLength 는 필요한 길이를 얻기 위해 ULONG 값 0 을 가리키는 유효한 포인터여야 합니다.

애플리케이션 또는 드라이버는 최상위 컬렉션의 HIDP_CAPS 구조에서 XxxReportByteLength 멤버의 필수 보고서 길이를 결정합니다.

자세한 내용은 HID 컬렉션을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 이상 버전의 Windows에서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	hidpi.h(Hidpi.h 포함)
라이브러리	Hidparse.lib
IRQL	<= DISPATCH_LEVEL