WinUsb_SetPowerPolicy-Funktion (winusb.h)

Artikel
03/04/2024

Die WinUsb_SetPowerPolicy-Funktion legt die Energierichtlinie für ein Gerät fest.

Syntax

BOOL WinUsb_SetPowerPolicy(
  [in] WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in] ULONG                   PolicyType,
  [in] ULONG                   ValueLength,
  [in] PVOID                   Value
);

Parameter

[in] InterfaceHandle

Ein undurchsichtiges Handle für die erste (Standard)-Schnittstelle auf dem Gerät, das von WinUsb_Initialize zurückgegeben wird.

[in] PolicyType

Ein Wert, der die festzulegende Energierichtlinie angibt. In der folgenden Tabelle werden symbolische Konstanten beschrieben, die in winusbio.h definiert sind.

Richtlinienparameter	BESCHREIBUNG
AUTO_SUSPEND (0x81)	Gibt den Richtlinientyp für das automatische Anhalten an. Der Power Policy-Parameter muss vom Aufrufer im Parameter Value angegeben werden. Beim automatischen Anhalten muss der Value-Parameter auf eine UCHAR-Variable verweisen. Wenn WertTRUE (nonzero) ist, wird das Gerät vom USB-Stapel angehalten, wenn sich das Gerät im Leerlauf befindet. Ein Gerät befindet sich im Leerlauf, wenn keine Übertragungen ausstehen oder wenn die einzigen ausstehenden Übertragungen IN-Übertragungen zu Unterbrechungen oder Massenendpunkten sind. Der Standardwert wird durch den Wert bestimmt, der in der Registrierungseinstellung DefaultIdleState festgelegt ist. Standardmäßig ist dieser Wert TRUE.
SUSPEND_DELAY (0x83)	Gibt den Richtlinientyp anhaltend verzögert an. Der Power Policy-Parameter muss vom Aufrufer im Parameter Value angegeben werden. Für angehaltene Verzögerung muss Wert auf eine ULONG-Variable verweisen. Value gibt die minimale Zeitspanne in Millisekunden an, die der WinUSB-Treiber nach der Übertragung warten muss, bevor er das Gerät anhalten kann. Der Standardwert wird durch den Wert bestimmt, der in der Registrierungseinstellung DefaultIdleTimeout festgelegt ist. Standardmäßig beträgt dieser Wert fünf Sekunden.

Richtlinienparameter

BESCHREIBUNG

AUTO_SUSPEND

(0x81)

Gibt den Richtlinientyp für das automatische Anhalten an. Der Power Policy-Parameter muss vom Aufrufer im Parameter Value angegeben werden.

Beim automatischen Anhalten muss der Value-Parameter auf eine UCHAR-Variable verweisen.

Wenn WertTRUE (nonzero) ist, wird das Gerät vom USB-Stapel angehalten, wenn sich das Gerät im Leerlauf befindet. Ein Gerät befindet sich im Leerlauf, wenn keine Übertragungen ausstehen oder wenn die einzigen ausstehenden Übertragungen IN-Übertragungen zu Unterbrechungen oder Massenendpunkten sind.

Der Standardwert wird durch den Wert bestimmt, der in der Registrierungseinstellung DefaultIdleState festgelegt ist. Standardmäßig ist dieser Wert TRUE.

SUSPEND_DELAY

(0x83)

Gibt den Richtlinientyp anhaltend verzögert an. Der Power Policy-Parameter muss vom Aufrufer im Parameter Value angegeben werden.

Für angehaltene Verzögerung muss Wert auf eine ULONG-Variable verweisen.

Value gibt die minimale Zeitspanne in Millisekunden an, die der WinUSB-Treiber nach der Übertragung warten muss, bevor er das Gerät anhalten kann.

Der Standardwert wird durch den Wert bestimmt, der in der Registrierungseinstellung DefaultIdleTimeout festgelegt ist. Standardmäßig beträgt dieser Wert fünf Sekunden.

[in] ValueLength

Die Größe des Puffers in Bytes bei Value.

[in] Value

Der neue Wert für den Power Policy-Parameter. Datentyp und Wert für Value hängen vom Typ der Energierichtlinie ab, die in PolicyType übergeben wird. Weitere Informationen finden Sie unter PolicyType.

Rückgabewert

WinUsb_SetPowerPolicy gibt TRUE zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Funktion FALSE zurück, und der Aufrufer kann den protokollierten Fehler abrufen, indem er GetLastError aufruft.

GetLastError kann den folgenden Fehlercode zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Der Aufrufer hat NULL im Parameter InterfaceHandle übergeben.
ERROR_INVALID_PARAMETER	Der Aufrufer hat eine ungültige Größe für den Richtlinienparameterpuffer im ValueLength-Parameter übergeben.
ERROR_NOT_ENOUGH_MEMORY	Gibt an, dass nicht genügend Arbeitsspeicher zum Ausführen des Vorgangs vorhanden ist.

Hinweise

In der folgenden Liste sind die Auswirkungen von Änderungen an Energieverwaltungszuständen zusammengefasst:

Alle Pipehandles, Schnittstellenhandles, Sperren und alternativen Einstellungen bleiben bei Energieverwaltungsereignissen erhalten.
Alle übertragungen, die gerade ausgeführt werden, werden angehalten, wenn ein Gerät in einen Zustand mit geringer Leistung überträgt, und sie werden fortgesetzt, wenn das Gerät in einen funktionierenden Zustand wiederhergestellt wird.
Das Gerät und das System müssen in einem funktionierenden Zustand sein, bevor der Client eine gerätespezifische Konfiguration wiederherstellen kann. Clients können anhand der WM_POWERBROADCAST-Nachricht bestimmen, ob sich das Gerät und das System in einem funktionierenden Zustand befinden.
Der Client kann angeben, dass sich eine Schnittstelle im Leerlauf befindet, indem er WinUsb_SetPowerPolicy aufruft.