IWDFDevice2::AssignSxWakeSettings-Methode (wudfddi.h)

Artikel
03/01/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 für neuere Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die AssignSxWakeSettings-Methode bietet vom Treiber bereitgestellte Informationen über die Fähigkeit eines Geräts, ein Aktivierungssignal auszulösen, während sich sowohl das Gerät als auch das System in einem Energiesparzustand befinden.

Syntax

HRESULT AssignSxWakeSettings(
  [in] DEVICE_POWER_STATE                    DxState,
  [in] WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Parameter

[in] DxState

Ein DEVICE_POWER_STATE typisierter Enumerator, der den Zustand mit niedriger Geräteleistung identifiziert, in den das Gerät eintritt, wenn der Systemstromzustand in einen reaktivierbaren Energiesparzustand fällt. Der Wert von DxState darf nicht PowerDeviceD0 sein. DEVICE_POWER_STATE Werte werden in wdm.h definiert.

[in] UserControlOfWakeSettings

Ein WDF_POWER_POLICY_SX_WAKE_USER_CONTROL typisiertes Enumerator, der angibt, ob Benutzer die Möglichkeit haben, die Aktivierungseinstellungen des Geräts zu ändern.

[in] Enabled

Ein WDF_TRI_STATE typisierter Enumerator, der angibt, ob das Gerät das System reaktivieren kann (d. h. das System auf S0 wiederherstellen), wenn sich das System in einem Zustand mit geringer Leistung befindet. Dieses Element kann über einen der folgenden Werte verfügen:

WdfTrue : Das Aktivieren des Systems ist aktiviert.

WdfFalse : Das Aufwachen des Systems ist deaktiviert.

WdfUseDefault : Das Aktivieren des Systems ist zunächst standardmäßig aktiviert. Wenn das UserControlOfWakeSettings-Element jedoch auf WakeAllowUserControl festgelegt ist, überschreibt die Einstellung oder die INF-Datei des Treibers den Anfangswert.

Wenn das Aufwecken des Systems aktiviert ist und das System in einen Energiesparzustand versetzt wird, ruft das Framework die Rückruffunktion IPowerPolicyCallbackWakeFromSx::OnArmWakeFromSx des Treibers auf, bevor das Gerät in einen Energiesparzustand wechselt.

Rückgabewert

AssignSxWakeSettings gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
E_INVALIDARG	Der Aufrufer hat einen ungültigen Wert für einen Eingabeparameter angegeben.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	Der aufrufende Treiber ist nicht der Besitzer der Energierichtlinie des Geräts.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	Der DxState-Parameter gibt einen ungültigen Gerätestromzustand an, oder der Bustreiber gibt an, dass das Gerät kein Aktivierungssignal auslösen kann.

Diese Methode gibt möglicherweise einen der anderen Werte zurück, die Winerror.h enthält.

Hinweise

Wenn ein Treiber AssignSxWakeSettings zum ersten Mal aufruft, werden die folgenden Aktionen ausgeführt:

Das Framework speichert die Parameterwerte.
Wenn der Parameter UserControlOfWakeSettings auf WakeAllowUserControl festgelegt ist und der Enabled-Parameter auf WdfUseDefault festgelegt ist, liest das Framework die Registrierung, um herauszufinden, ob der Benutzer die Aktivierung des Systems aktiviert hat.

Bei nachfolgenden Aufrufen von AssignSxWakeSettings speichert das Framework den Wert des Parameters UserControlOfWakeSettings nicht. Mit anderen Worten, das Framework führt die folgenden Schritte aus, wenn der Treiber Zum ersten Mal AssignSxWakeSettings aufruft , aber nicht bei späteren Aufrufen:

Speichert den Wert des Parameters UserControlOfWakeSettings .
Sucht nach einer Benutzereinstellung in der Registrierung, wenn der Wert des Enabled-ParametersWdfUseDefault ist.

Die folgenden Regeln gelten für den Wert, den Sie für den DxState-Parameter angeben:

Der Wert darf nicht PowerDeviceD0 sein.
Wenn Sie DevicePowerMaximum angeben, verwendet das Framework den Wert, den der Kernelmodustreiber für den Bus des Geräts im DeviceWake-Member seiner WDF_DEVICE_POWER_CAPABILITIES-Struktur bereitgestellt hat.
Sie können keinen Geräteleistungsstatus angeben, der niedriger ist als der Geräteleistungszustand im DeviceWake-Member der WDF_DEVICE_POWER_CAPABILITIES-Struktur des Kernelmodus-Bustreibers. (Anders ausgedrückt: Wenn der DeviceWake-Wert des Bustreibers PowerDeviceD2 ist, darf der DxState-Wert Ihres Funktionstreibers nicht PowerDeviceD3 sein.)

Informationen zu Registrierungseinträgen, die die Aktivierungsfunktionen eines Geräts steuern, finden Sie unter Benutzersteuerung des Geräteleidle- und Reaktivverhaltens in UMDF.

Weitere Informationen zur Unterstützung der Aktivierungsfunktionen eines Geräts finden Sie unter Unterstützen von System-Wake-Up in UMDF-basierten Treibern.

Im folgenden Codebeispiel wird die IWDFDevice2-Schnittstelle abgerufen und dann AssignSxWakeSettings aufgerufen.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
        hr = pIWDFDevice2->AssignSxWakeSettings(PowerDeviceMaximum,
                                                WakeAllowUserControl,
                                                WdfUseDefault);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.9
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Weitere Informationen

IWDFDevice2

IWDFDevice2::AssignS0IdleSettings

Freigeben über