HidP_GetUsages-Funktion (hidpi.h)

Artikel
08/07/2023

Die HidP_GetUsages Routine gibt eine Liste aller Verwendungen von HID-Steuerelementschaltflächen zurück, die sich auf einer angegebenen Verwendungsseite befinden und in einem HID-Bericht auf ON festgelegt sind.

Syntax

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

Parameter

[in] ReportType

Gibt einen HIDP_REPORT_TYPE Enumeratorwert an, der den Berichtstyp identifiziert.

[in] UsagePage

Gibt die Verwendungsseite der Schaltflächennutzungen an. Die Routine gibt nur Informationen zu Schaltflächen auf dieser Verwendungsseite zurück.

[in] LinkCollection

Gibt die Linkauflistung der Schaltflächenverwendungen an. Wenn LinkCollection ungleich null ist, gibt die Routine nur Informationen zu den Schaltflächen zurück, die diese Linkauflistung enthält. Andernfalls gibt die Routine, wenn LinkCollection null ist, Informationen zu allen Schaltflächen in der Auflistung der obersten Ebene zurück, die PreparsedData zugeordnet ist.

[out] UsageList

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der von der Routine verwendet wird, um die Verwendungen aller Schaltflächen zurückzugeben, die auf ON festgelegt sind und zu der von UsagePage angegebenen Nutzungsseite gehören.

[in, out] UsageLength

Gibt bei der Eingabe die Länge des UsageList-Puffers in Arrayelementen an. Gibt bei der Ausgabe die Anzahl der Schaltflächen an, die auf der angegebenen Verwendungsseite auf EIN festgelegt sind.

[in] PreparsedData

Zeiger auf die vorbereiteten Daten einer Sammlung auf oberster Ebene.

[out] Report

Zeiger auf einen Bericht.

[in] ReportLength

Gibt die Länge des Berichts in Byte an, der sich unter Bericht befindet.

Rückgabewert

HidP_GetUsages gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
HIDP_STATUS_SUCCESS	Die Routine hat erfolgreich alle Schaltflächenverwendungen zurückgegeben, die auf EIN festgelegt sind.
HIDP_INVALID_REPORT_LENGTH	Die Berichtslänge ist ungültig.
HIDP_INVALID_REPORT_TYPE	Der angegebene Berichtstyp ist ungültig.
HIDP_STATUS_BUFFER_TOO_SMALL	Der UsageList-Puffer ist zu klein, um alle Verwendungen aufzunehmen, die derzeit auf der angegebenen Verwendungsseite auf ON festgelegt sind.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	Die Auflistung enthält Schaltflächen auf der angegebenen Verwendungsseite in einem Bericht des angegebenen Typs, aber es gibt keine solchen Verwendungen im angegebenen Bericht.
HIDP_STATUS_INVALID_PREPARSED_DATA	Die vorbereiteten Daten sind ungültig.
HIDP_STATUS_USAGE_NOT_FOUND	Die Auflistung enthält keine Schaltflächen auf der angegebenen Verwendungsseite in einem Bericht des angegebenen Berichtstyps.

Hinweise

Benutzermodusanwendungen und Kernelmodustreiber rufen HidP_MaxUsageListLength auf, um die maximale Anzahl von Schaltflächen zu bestimmen, die für den angegebenen Berichtstyp zurückgegeben werden können. Alternativ können Anwendungen oder Treiber HidP_GetUsages aufrufen und (*UsageLength) auf 0 festlegen, um die erforderliche Länge in UsageLength zurückzugeben. Anders ausgedrückt: UsageLength sollte ein gültiger Zeiger sein, der auf einen ULONG-Wert 0 zeigt, um die erforderliche Länge zu erhalten.

Anwendungen oder Treiber bestimmen die erforderliche Berichtslänge aus den XxxReportByteLength-Membern in der HIDP_CAPS-Struktur einer Sammlung der obersten Ebene.

Weitere Informationen finden Sie unter HID-Auflistungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 2000 und höheren Versionen von Windows.
Zielplattform	Universell
Header	hidpi.h (hidpi.h einschließen)
Bibliothek	Hidparse.lib
IRQL	<= DISPATCH_LEVEL