WdfDeviceAssignS0IdleSettings-Funktion (wdfdevice.h)

Artikel
02/29/2024

[Gilt für KMDF und UMDF]

Die WdfDeviceAssignS0IdleSettings-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

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

Parameter

[in] Device

Ein Handle für ein 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	Ein ungültiger Einstellungswert wird 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 Fehler auftritt: Die WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur enthält einen ungültigen Gerätestromzustand. Der IdleCaps-Member der WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur gibt an, dass das Gerät selbst reaktiviert werden kann, aber der Bustreiber gibt an, dass das Gerät selbst nicht reaktiviert werden kann. Ab KMDF-Version 1.11 unter Windows 8 überprüft das Framework, ob die Firmware des Systems ein Aktivierungssignal verarbeiten kann, während sich das System in einem vollständig eingeschalteten (S0)-Stromzustand befindet. Wenn diese Überprüfung auf dem Computer fehlschlägt, gibt WdfDeviceAssignS0IdleSettingsSTATUS_POWER_STATE_INVALID zurück, und das Gerät verbleibt im Zustand "Vollständig eingeschaltet" (D0), solange das System in S0 verbleibt. In diesem Fall sollte der Treiber keinen Fehler status Wert von EvtDriverDeviceAdd oder einem anderen Laufzeitrückruf zurückgeben. Der Treiber kann höchstens einen Fehler protokollieren, der angibt, dass das Gerät mehr Strom verbraucht als normalerweise.

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

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Wenn der Treiber das IdleTimeoutType-Element von WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS auf SystemManagedIdleTimeoutout oder SystemManagedIdleTimeoutWithHint festlegt, muss er WdfDeviceAssignS0IdleSettings aufrufen, bevor er von EvtDeviceD0Entry zurückgibt. In der Regel ruft ein Treiber zuerst WdfDeviceAssignS0IdleSettings von EvtDriverDeviceAdd auf.

Zusätzliche Aufrufe von WdfDeviceAssignS0IdleSettings können jederzeit durchgeführt werden. Nachdem der Treiber jedoch den Wert des IdleTimeoutType-Elements in seinem ersten Aufruf von WdfDeviceAssignS0IdleSettings festgelegt hat, darf er diesen Wert in späteren Aufrufen dieser Methode nicht ändern.

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

Weitere Informationen finden Sie unter Unterstützung des Herunterschaltens im Leerlauf.

Beispiele

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

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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfdevice.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), FDOPowerPolicyOwnerAPI(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NonFDONotPowerPolicyOwnerAPI(kmdf)

Weitere Informationen

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS

WdfDeviceAssignSxWakeSettings

Freigeben über