WdfDeviceAssignS0IdleSettings-Funktion (wdfdevice.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

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

Syntax

NTSTATUS WdfDeviceAssignS0IdleSettings(
  [in] WDFDEVICE                              Device,
  [in] PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Settings
);

Parameter

[in] Device

Ein Handle zu einem Framework-Geräteobjekt.

[in] Settings

Ein Zeiger auf eine vom Aufrufer bereitgestellte WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Struktur.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt WdfDeviceAssignS0IdleSettings STATUS_SUCCESS zurück. Weitere Rückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	Der aufrufende Treiber ist nicht der Besitzer der Energierichtlinie des Geräts.
STATUS_INVALID_PARAMETER	Es wird ein ungültiger Einstellungen Wert erkannt.
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Struktur ist falsch.
STATUS_POWER_STATE_INVALID	Dieser Wert wird zurückgegeben, wenn einer der folgenden Aktionen auftritt: Die WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur enthält einen ungültigen Gerätestromzustand. Das IdleCaps Mitglied der WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur gibt an, dass das Gerät selbst reaktiviert werden kann, der Bustreiber gibt jedoch an, dass das Gerät nicht selbst reaktiviert werden kann. Ab KMDF Version 1.11 unter Windows 8 überprüft das Framework, ob die Firmware des Systems ein Wakesignal verarbeiten kann, während sich das System im Vollbetriebszustand (S0) befindet. Wenn die Überprüfung auf dem Computer fehlschlägt, gibt WdfDeviceAssignS0IdleSettingsSTATUS_POWER_STATE_INVALIDzurück, und das Gerät verbleibt in seinem vollständigen Energiezustand (D0), solange das System in S0 verbleibt. In diesem Fall sollte der Treiber keinen Fehlerstatuswert von EvtDriverDeviceAdd oder einem anderen Laufzeitrückruf zurückgeben. Der Treiber protokolliert höchstens einen Fehler, der angibt, dass das Gerät mehr Energie verbraucht als normalerweise.

Die Methode gibt möglicherweise andere NTSTATUS-Wertezurück.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Wenn der Treiber den IdleTimeoutType Member von WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS auf SystemManagedIdleTimeout oder SystemManagedIdleTimeoutWithHintfestlegt, muss er WdfDeviceAssignS0IdleSettings aufrufen, bevor er von EvtDeviceD0Entryzurückgegeben wird. In der Regel ruft ein Treiber zuerst WdfDeviceAssignS0IdleSettings von EvtDriverDeviceAddauf.

Zusätzliche Aufrufe von WdfDeviceAssignS0IdleSettings können jederzeit erfolgen. Nachdem der Treiber jedoch den Wert des IdleTimeoutType Members im ersten Aufruf von WdfDeviceAssignS0IdleSettingsfestgelegt hat, darf dieser Wert in späteren Aufrufen dieser Methode nicht geändert werden.

Wenn sich der Treiber für asynchrone Benachrichtigungen in EvtDriverDeviceAdd registriert (z. B. durch Aufrufen PoRegisterPowerSettingCallback oder IoRegisterPlugPlayNotification), darf der Treiber nicht anschließend WdfDeviceAssignS0IdleSettings innerhalb der registrierten Treiberrückrufroutine aufrufen.

Weitere Informationen finden Sie unter Unterstützen von Power-Down-im Leerlauf.

Beispiele

Im folgenden Codebeispiel wird eine WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Struktur initialisiert, ein Leerlauftimeoutwert von 10 Sekunden festgelegt und WdfDeviceAssignS0IdleSettingsaufgerufen.

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS  idleSettings;
NTSTATUS  status = STATUS_SUCCESS;

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT(
                                           &idleSettings,
                                           IdleCanWakeFromS0
                                           );
idleSettings.IdleTimeout = 10000;

status = WdfDeviceAssignS0IdleSettings(
                                       device,
                                       &idleSettings
                                       );
if (!NT_SUCCESS(status)) {
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfdevice.h (einschließen Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), FDOPowerPolicyOwnerAPI(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NonFDONotPowerPolicyOwnerAPI(kmdf)

Siehe auch

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS

WdfDeviceAssignSxWakeSettings

Freigeben über