IWDFDevice2::AssignS0IdleSettings-Methode (wudfddi.h)

Artikel
08/08/2023

[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 in neueren 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 AssignS0IdleSettings-Methode stellt vom Treiber bereitgestellte Informationen bereit, die das Framework verwendet, wenn sich ein Gerät im Leerlauf befindet 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 typisierter Enumerator, der die Fähigkeit des Geräts angibt, sich selbst zu reaktivieren, nachdem es auf einen Low-Power-Zustand festgelegt wurde, während das System in seinem Arbeitszustand (S0) verbleibt.

[in] DxState

Ein DEVICE_POWER_STATE typisierter Enumerator, der den Zustand der geringen Geräteleistung identifiziert, den das Gerät nach Ablauf des Leerlauftimeouts erhält. DEVICE_POWER_STATE Werte werden in wdm.h definiert.

[in] IdleTimeout

Die Zeitspanne in Millisekunden, die das Gerät im Leerlauf verbleibt, bevor es vom Framework in den von DxState bereitgestellten Low-Power-Zustand versetzt wird. Um den Standardmäßigen Leerlauftimeoutwert des Frameworks zu verwenden, geben Sie IdleTimeoutDefaultValue an. Weitere Informationen finden Sie im Abschnitt Hinweise.

[in] UserControlOfIdleSettings

Ein WDF_POWER_POLICY_S0_IDLE_USER_CONTROL typisierter Enumerator, der angibt, ob Benutzer die Einstellungen im Leerlauf des Geräts ändern können.

[in] Enabled

Ein WDF_TRI_STATE typisierter Enumerator, der angibt, ob das Gerät ausgeschaltet wird, wenn es im Leerlauf bleibt und während die Systemleistung bei S0 liegt. Dieser Member kann einen der folgenden Werte aufweisen:

WdfTrue : Das Herunterschalten ist aktiviert.

WdfFalse : Das Herunterschalten ist deaktiviert.

WdfUseDefault : Das Herunterschalten ist zunächst standardmäßig aktiviert. Wenn der UserControlOfIdleSettings-Parameter jedoch auf IdleAllowUserControl festgelegt ist, überschreibt die Einstellung oder die INF-Datei des Treibers den Anfangswert.

Wenn das Herunterfahren aktiviert ist, das Gerät über eine Aktivierungsfunktion verfügt und der Wert für das Leerlauftimeout abläuft, ruft das Framework die Rückruffunktion IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 des Treibers 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 des Geräts.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	Der DxState-Parameter gibt einen ungültigen Gerätestromzustand an, oder der IdleCaps-Parameter gibt an, dass das Gerät selbst reaktiviert werden kann, aber der Bustreiber gibt an, dass das Gerät selbst nicht reaktiviert werden kann.

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

Hinweise

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

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

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

Wenn der Treiber in einem vorherigen Aufruf von AssignS0IdleSettings jemalsIdleCanWakeFromS0 für den Wert des IdleCaps-Parameters angegeben hat, kann er diesen Wert später nicht in IdleUsbSelectiveSuspend ändern.
Wenn der Treiber in einem vorherigen Aufruf von AssignS0IdleSettings jemalsIdleUsbSelectiveSuspend für den Wert des IdleCaps-Parameters angegeben hat, kann dieser Wert später nicht in IdleCanWakeFromS0 geändert werden.

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

Der Wert darf nicht PowerDeviceD0 sein.
Bei USB-Geräten darf der Wert nicht PowerDeviceD0 oder PowerDeviceD3 sein.
Wenn Sie DevicePowerMaximum angeben, verwendet das Framework den Wert, den der Kernelmodustreiber für den Gerätebus im DeviceWake-Member seiner WDF_DEVICE_POWER_CAPABILITIES-Struktur bereitgestellt hat.
Wenn der Wert des IdleCaps-ParametersIdleCanWakeFromS0 oder IdleUsbSelectiveSuspend ist, können Sie keinen Geräteleistungszustand angeben, der niedriger als der Geräteleistungszustand im DeviceWake-Member der WDF_DEVICE_POWER_CAPABILITIES-Struktur des Kernelmodus-Bustreibers ist. (Anders ausgedrückt: Wenn der DeviceWake-Wert des Bustreibers PowerDeviceD2 ist, kann der DxState-Wert ihres Funktionstreibers nicht PowerDeviceD3 sein.)

Wenn Sie IdleTimeoutDefaultValue für den IdleTimeout-Parameter angeben, beträgt das Timeout standardmäßig fünf Sekunden. Sie können die Ausgabe der Debuggererweiterungen !wudfext.wudfdevice und !wudfext.umdevstacks untersuchen, um die effektiven Einstellungen und Energieverweise anzuzeigen.

Informationen zu Registrierungseinträgen, mit denen die Leerlauffunktionen eines Geräts gesteuert werden, finden Sie unter Benutzersteuerung des Geräte-Idle- und Aktivierungsverhaltens 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. Im Beispiel wird die IWDFDevice2-Schnittstelle abgerufen und anschließend AssignS0IdleSettings aufgerufen.

    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
UMDF-Mindestversion	1.9
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Weitere Informationen

IWDFDevice2

IWDFDevice2::AssignSxWakeSettings

IWDFDevice3::AssignS0IdleSettingsEx

Freigeben über