IWDFDevice2::AssignS0IdleSettings-Methode (wudfddi.h)

Artikel
02/07/2025

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

Die AssignS0IdleSettings--Methode stellt vom Treiber bereitgestellte Informationen bereit, die das Framework verwendet, wenn ein Gerät im Leerlauf ist und sich das System im Arbeitszustand (S0) befindet.

Syntax

HRESULT AssignS0IdleSettings(
  [in] WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps,
  [in] DEVICE_POWER_STATE                    DxState,
  [in] ULONG                                 IdleTimeout,
  [in] WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Parameter

[in] IdleCaps

Ein WDF_POWER_POLICY_S0_IDLE_CAPABILITIES-typd Enumerator, der die Fähigkeit des Geräts identifiziert, sich selbst zu reaktivieren, nachdem es auf einen Energiesparzustand festgelegt ist, während das System im Arbeitszustand (S0) verbleibt.

[in] DxState

Ein DEVICE_POWER_STATE-typed-Enumerator, der den niedrigen Gerätestromzustand identifiziert,, dass das Gerät nach Beendigung des Leerlauftimeouts eingibt. DEVICE_POWER_STATE Werte werden in wdm.h definiert.

[in] IdleTimeout

Die Zeitspanne in Millisekunden, die das Gerät im Leerlauf bleibt, bevor es im DxState-bereitgestellten Zustand mit niedriger Leistung platziert wird. Wenn Sie den Standard-Leerlauftimeoutwert des Frameworks verwenden möchten, geben Sie IdleTimeoutDefaultValue Weitere Informationen finden Sie im Abschnitt "Hinweise".

[in] UserControlOfIdleSettings

Ein WDF_POWER_POLICY_S0_IDLE_USER_CONTROL-typed-Enumerator, der angibt, ob Benutzer die Möglichkeit haben, die Leerlaufeinstellungen des Geräts zu ändern.

[in] Enabled

Ein WDF_TRI_STATE-typed-Enumerator, der angibt, ob das Gerät ausgeschaltet wird, wenn es im Leerlauf bleibt und die Systemleistung bei S0 liegt. Dieses Element kann einen der folgenden Werte aufweisen:

WdfTrue- – Das Herunterschalten ist aktiviert.

WdfFalse- – Das Herunterschalten ist deaktiviert.

WdfUseDefault- – Das Herunterschalten ist standardmäßig aktiviert; wenn der parameter UserControlOfIdleSettings jedoch auf IdleAllowUserControlfestgelegt ist, überschreibt die INF-Datei des Benutzers den Anfangswert.

Wenn das Einschalten aktiviert ist, verfügt das Gerät über eine Reaktivierungsfunktion, und der Leerlauftimeoutwert läuft ab, ruft das Framework die IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 Rückruffunktion auf, bevor das Gerät in einen Energiesparzustand wechselt.

Rückgabewert

AssignS0IdleSettings 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.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	Der parameter DxState gibt einen ungültigen Energiezustand des Geräts an, oder der IdleCaps Parameter gibt an, dass das Gerät selbst reaktiviert werden kann, der Bustreiber gibt jedoch an, dass das Gerät nicht selbst reaktiviert werden kann.

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

Bemerkungen

Wenn ein Treiber zum ersten Mal AssignS0IdleSettingsaufruft, treten die folgenden Aktionen auf:

Das Framework speichert die Werte aller Parameter.
Wenn der parameter UserControlOfIdleSettings auf IdleAllowUserControl festgelegt ist und der Parameter Enabled auf WdfUseDefaultfestgelegt ist, liest das Framework die Registrierung vor, um herauszufinden, ob der Benutzer das Einschalten des Geräts aktiviert hat, wenn es sich im Leerlauf befindet.

Bei nachfolgenden Aufrufen von AssignS0IdleSettingsspeichert das Framework nur die Werte der DxState, IdleTimeout-und Enabled Parameter. Außerdem speichert das Framework den Wert des IdleCaps Parameters, der den folgenden Regeln unterliegt:

Wenn der Treiber jemals IdleCanWakeFromS0 für den Wert des IdleCaps Parameter in einem vorherigen Aufruf von AssignS0IdleSettingsangegeben hat, kann dieser Wert anschließend nicht in IdleUsbSelectiveSuspendgeändert werden.
Wenn der Treiber jemals IdleUsbSelectiveSuspend für den Wert des IdleCaps Parameter in einem vorherigen Aufruf von AssignS0IdleSettingsangegeben hat, kann dieser Wert anschließend nicht in IdleCanWakeFromS0geändert werden.

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

Der Wert kann nicht PowerDeviceD0werden.
Für USB-Geräte kann der Wert nicht PowerDeviceD0 oder PowerDeviceD3-sein.
Wenn Sie DevicePowerMaximumangeben, verwendet das Framework den Wert, den der Kernelmodustreiber für den Im DeviceWake Member seiner WDF_DEVICE_POWER_CAPABILITIES Struktur bereitgestellten Bus des Geräts angibt.
Wenn der Wert des IdleCaps-Parameters IdleCanWakeFromS0 oder IdleUsbSelectiveSuspendist, können Sie keinen Gerätestromzustand angeben, der niedriger als der Gerätestromzustand im DeviceWake Mitglied der WDF_DEVICE_POWER_CAPABILITIES Struktur des Kernelmodusbustreibers ist. (Wenn der DeviceWake-Wert des Bustreibers Wert PowerDeviceD2ist, kann der DxState-Wert des Funktionstreibers nicht PowerDeviceD3.)

Wenn Sie IdleTimeoutDefaultValue- für den parameter IdleTimeout angeben, wird der Timeout standardmäßig auf fünf Sekunden festgelegt. Sie können die Ausgabe der !wudfext.wudfdevice und !wudfext.umdevstacks Debuggererweiterungen untersuchen, um die effektiven Einstellungen und Leistungsverweise anzuzeigen.

Informationen zu Registrierungseinträgen, die die Leerlauffunktionen eines Geräts steuern, finden Sie unter Benutzersteuerung des Geräte-Idle- und Wake-Verhaltens in UMDF-.

Weitere Informationen zur Unterstützung der Leerlauffunktionen eines Geräts finden Sie unter Unterstützen von Idle-Power-Down in UMDF-basierten Treibern.

Beispiele

Das folgende Codebeispiel basiert auf der UMDF-Version des Toasterbeispiels. Das Beispiel ruft die IWDFDevice2 Schnittstelle ab und ruft dann AssignS0IdleSettingsauf.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
    //
    // The toaster device is virtual, so we tell the framework that the 
    // device cannot wake if it sleeps while the system is in S0. The device 
    // can return to D0 only when the driver stack receives an I/O request.
    //
    hr = pIWDFDevice2->AssignS0IdleSettings(IdleCannotWakeFromS0,
                                            PowerDeviceD3,
                                            IDLEWAKE_TIMEOUT_MSEC,
                                            IdleAllowUserControl,
                                            WdfTrue);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Anforderungen

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

Siehe auch

IWDFDevice2-

IWDFDevice2::AssignSxWakeSettings

IWDFDevice3::AssignS0IdleSettingsEx

Freigeben über