HidP_GetButtonArray-Funktion (hidpi.h)

  • Artikel

HidP_GetButtonArray gibt ein Array von HIDP_BUTTON_ARRAY_DATA Strukturen für den angegebenen Bericht zurück.

Syntax

NTSTATUS HidP_GetButtonArray(
  HIDP_REPORT_TYPE        ReportType,
  USAGE                   UsagePage,
  USHORT                  LinkCollection,
  USAGE                   Usage,
  PHIDP_BUTTON_ARRAY_DATA ButtonData,
  PUSHORT                 ButtonDataLength,
  PHIDP_PREPARSED_DATA    PreparsedData,
  PCHAR                   Report,
  ULONG                   ReportLength
);

Parameter

ReportType

Ein Wert aus der HIDP_REPORT_TYPE Enumeration.

UsagePage

Die Verwendungsseite, auf die sich die angegebene Verwendung bezieht.

LinkCollection

(Optional) Dieser Wert kann verwendet werden, um zwischen zwei Feldern zu unterscheiden, die möglicherweise die gleiche UsagePage und Usage aufweisen, aber in unterschiedlichen Sammlungen vorhanden sind. Wenn der LinkCollection-WertHIDP_LINK_COLLECTION_UNSPECIFIED ist, wird unabhängig vom Speicherort das erste Schaltflächenarray zurückgegeben, das mit usagePage und Usage übereinstimmt. Wenn der LinkCollection-WertHIDP_LINK_COLLECTION_ROOT ist, wird das erste Schaltflächenarray in der Stammsammlung zurückgegeben, das mit UsagePage und Usage übereinstimmt.

Usage

Die Verwendung, deren Schaltflächen HidP_GetButtonArray abgerufen werden.

ButtonData

Ein Array von HIDP_BUTTON_ARRAY_DATA Strukturen, in denen die Daten der auf festgelegten Schaltflächen platziert ON werden. Die Anzahl der erforderlichen Elemente ist das Feld ReportCount des HIDP_BUTTON_CAPS für dieses Steuerelement. Dieser Puffer wird vom Aufrufer bereitgestellt.

ButtonDataLength

Als Eingabe gibt dieser Parameter die Länge des ButtonData-Parameters in der Anzahl der Arrayelemente an, nicht in der Anzahl der Bytes. Wenn HIDP_STATUS_SUCCESS zurückgegeben wird, wird dieser Wert als Ausgabe festgelegt, um anzugeben, wie viele dieser Arrayelemente von der Funktion ausgefüllt wurden. Die maximale Anzahl von HIDP_BUTTON_ARRAY_DATA Strukturen, die zurückgegeben werden können, wird durch HIDP_BUTTON_CAPS bestimmt. ReportCount. Wenn HIDP_STATUS_BUFFER_TOO_SMALL zurückgegeben wird, enthält dieser Wert die Anzahl der Arrayelemente, die zum erfolgreichen Abschluss der Anforderung erforderlich sind.

PreparsedData

Die vorab analysierten Daten, die von der HIDCLASS zurückgegeben werden.

Report

Das Berichtspaket. Das erste Byte muss die ReportId sein. Dies wird ordnungsgemäß festgelegt, wenn der Bericht aus dem System gelesen wird.

ReportLength

Länge des angegebenen Berichtspakets in Bytes.

Rückgabewert

HidP_GetButtonArray gibt einen der folgenden status Werte zurück:

Rückgabecode Beschreibung
HIDP_STATUS_SUCCESS Die Schaltflächen wurden erfolgreich aus dem Berichtspaket abgerufen.
HIDP_STATUS_INVALID_REPORT_TYPE Der ReportType-Parameter ist ungültig.
HIDP_STATUS_INVALID_PREPARSED_DATA Der PreparsedData-Parameter ist ungültig.
HIDP_STATUS_INVALID_REPORT_LENGTH Die Länge des Berichtspakets entspricht nicht der Länge, die in der HIDP_CAPS-Struktur für den angegebenen ReportType angegeben ist.
HIDP_STATUS_NOT_BUTTON_ARRAY Das angegebene Steuerelement ist kein Schaltflächenarray.
HIDP_STATUS_BUFFER_TOO_SMALL Die Größe des übergebenen Puffers, in dem das Array zurückgegeben werden soll, ist zu klein.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID Die angegebene Nutzungsseite, Die angegebene Verwendungs- und Linksammlung ist in einem Bericht mit einer anderen Berichts-ID als der übergebene Bericht vorhanden.
HIDP_STATUS_USAGE_NOT_FOUND Die Kombination aus Nutzungsseite, Verwendung und Linksammlung ist in keinem Bericht für diesen ReportType vorhanden.

Hinweise

Der Aufrufer sollte HidP_GetVersion verwenden, um zu bestimmen, ob diese Funktion verfügbar ist. HidP_GetButtonArray ist nur verfügbar, wenn HidP_GetVersion einen Wert von mindestens zwei zurückgibt. Version 2 der API entspricht Windows 11.

Ein Schaltflächenarray tritt auf, wenn die letzte Verwendung in der Reihenfolge der Verwendungen, die ein Standard Element beschreiben, wiederholt werden muss, da weniger Verwendungen als der für das angegebene Standard Element deklarierte ReportCount definiert sind. In diesem Fall wird ein einzelner HIDP_BUTTON_CAPS für diese Verwendung zugewiesen, und der ReportCount des HIDP_BUTTON_CAPS wird so festgelegt, dass die Anzahl der Felder, auf die sich die Verwendung bezieht, widerspiegelt.

Eine HIDP_BUTTON_CAPS , die ein Schaltflächenarray beschreibt, weist ReportCount immer mehr als eins auf. Wenn ReportCount gleich einem ist, handelt es sich nicht um ein Schaltflächenarray und kann nicht mit HidP_GetButtonArray verwendet werden. Siehe stattdessen HidP_GetUsages .

Anforderungen

Anforderung Wert
Header hidpi.h

Weitere Informationen