HidP_GetButtonArray-Funktion (hidpi.h)
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 dieselbe UsagePage- und Usage aufweisen, aber in verschiedenen Auflistungen vorhanden sind. Wenn der LinkCollection-wertHIDP_LINK_COLLECTION_UNSPECIFIEDist, wird das erste Schaltflächenarray gefunden, das dem UsagePage- entspricht und Usage unabhängig vom Speicherort zurückgegeben wird. Wenn der LinkCollection- Wert HIDP_LINK_COLLECTION_ROOTist, wird das erste Schaltflächenarray in der Stammauflistung zurückgegeben, das dem UsagePage- entspricht und Usage zurückgegeben wird.
Usage
Die Verwendung, deren Schaltflächen HidP_GetButtonArray abgerufen werden.
ButtonData
Ein Array von HIDP_BUTTON_ARRAY_DATA Strukturen, in denen die Auf ON festgelegten Daten von Schaltflächen platziert werden. Die Anzahl der erforderlichen Elemente ist das ReportCount Feld 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 und nicht die Anzahl der Bytes an. 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 Abschließen der Anforderung erforderlich sind.
PreparsedData
Die vorab analysierten Daten, die von der HIDCLASSzurü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 Byte.
Rückgabewert
HidP_GetButtonArray gibt einen der folgenden Statuswerte 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 parameter "preparsedData" "PreparsedData" 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 die angegebene ReportType- |
| 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 Verwendungsseite, Verwendungs- und Linksammlung ist in einem Bericht mit einer anderen Berichts-ID vorhanden als der Bericht, der übergeben wird. |
| HIDP_STATUS_USAGE_NOT_FOUND | Die Kombination aus Verwendungsseiten, Verwendung und Linksammlung ist in keinem Bericht für diesen ReportType- vorhanden. |
Bemerkungen
Der Aufrufer sollte HidP_GetVersion verwenden, um festzustellen, ob diese Funktion verfügbar ist. HidP_GetButtonArray ist nur verfügbar, wenn HidP_GetVersion einen Wert von zwei oder mehr zurückgibt. Version 2 der API entspricht Windows 11.
Ein Schaltflächenarray tritt auf, wenn die letzte Verwendung in der Abfolge von Verwendungen, die ein Hauptelement beschreiben, wiederholt werden muss, da weniger Verwendungen definiert sind als die ReportCount für das angegebene Hauptelement deklariert wurde. In diesem Fall wird ein einzelner HIDP_BUTTON_CAPS für diese Verwendung zugewiesen, und die ReportCount- der HIDP_BUTTON_CAPS wird so festgelegt, dass die Anzahl der Felder, auf die sich die Verwendung bezieht, berücksichtigt wird.
Eine HIDP_BUTTON_CAPS, die ein Schaltflächenarray beschreibt, weist immer ReportCount größer als eins auf. Wenn ReportCount gleich einem ist, handelt es sich nicht um ein Schaltflächenarray und kann nicht mit HidP_GetButtonArrayverwendet werden. Stattdessen HidP_GetUsages anzeigen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Header- | hidpi.h |