Funzione WdfDeviceWdmAssignPowerFrameworkSettings (wdfdevice.h)

Articolo
02/29/2024

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceWdmAssignPowerFrameworkSettings registra le impostazioni del framework di gestione energia (PoFx) per i dispositivi a componente singolo.

Sintassi

NTSTATUS WdfDeviceWdmAssignPowerFrameworkSettings(
  [in] WDFDEVICE                     Device,
  [in] PWDF_POWER_FRAMEWORK_SETTINGS PowerFrameworkSettings
);

Parametri

[in] Device

Handle per l'oggetto dispositivo framework per cui vengono specificate le impostazioni di PoFx.

[in] PowerFrameworkSettings

Puntatore a una struttura WDF_POWER_FRAMEWORK_SETTINGS che descrive le impostazioni PoFx del driver client.

Valore restituito

Il metodo WdfDeviceWdmAssignPowerFrameworkSettings restituisce un valore NTSTATUS che indica l'esito positivo o negativo dell'operazione.

Codice restituito	Descrizione
STATUS_INFO_LENGTH_MISMATCH	Le dimensioni della struttura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS non sono corrette.
STATUS_INVALID_DEVICE_REQUEST	Il driver chiamante non è il proprietario del criterio di alimentazione del dispositivo.
STATUS_INVALID_PARAMETER	Viene rilevato un valore Impostazioni non valido.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

Il metodo WdfDeviceWdmAssignPowerFrameworkSettings si applica solo ai dispositivi a componente singolo.

Prima di chiamare questo metodo, il driver client deve prima chiamare correttamente WdfDeviceAssignS0IdleSettings e impostare il campo IdleTimeoutType della struttura WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS su SystemManagedIdleTimeout o SystemManagedIdleTimeoutWithHint.

Un driver deve chiamare WdfDeviceWdmAssignPowerFrameworkSettings prima o durante la prima avvio di un dispositivo. Poiché un dispositivo può iniziare più volte, ad esempio se si verifica il ribilanciamento delle risorse, un driver potrebbe chiamare questo metodo dall'interno di EvtDriverDeviceAdd o EvtDeviceSelfManagedIoInit. Il framework chiama queste funzioni una sola volta, anche se il dispositivo viene avviato più volte.

In alternativa, il driver potrebbe tenere traccia del fatto che abbia già chiamato WdfDeviceWdmAssignPowerFrameworkSettings e chiamarlo da una delle seguenti funzioni di callback: EvtDevicePrepareHardware, EvtDeviceD0Entry, EvtDeviceD0EntryPostInterruptsEnruptsEnabled o EvtDeviceSelfManagedIoRestart.

Se il driver chiama WdfDeviceWdmAssignPowerFrameworkSettings più volte, il framework genera un errore di verifica.

Il framework di gestione energia (PoFx) è disponibile solo in Windows 8 e versioni successive. Quando viene eseguito in un sistema operativo che non supporta PoFx, WdfDeviceWdmAssignPowerFrameworkSettings non esegue alcuna azione e restituisce STATUS_SUCCESS.

Per altre informazioni, vedere Supporto degli stati di alimentazione funzionale e panoramica di Power Management Framework.

Esempio

Nell'esempio di codice seguente il driver inizializza una struttura WDF_POWER_FRAMEWORK_SETTINGS chiamando la funzione WDF_POWER_FRAMEWORK_SETTINGS_INIT . Il driver imposta quindi manualmente alcuni dei membri della struttura e quindi chiama WdfDeviceWdmAssignPowerFrameworkSettings.

NTSTATUS status;
WDF_POWER_FRAMEWORK_SETTINGS poFxSettings;

WDF_POWER_FRAMEWORK_SETTINGS_INIT(&poFxSettings);

poFxSettings.EvtDeviceWdmPostPoFxRegisterDevice = 
                        SingleCompWdmEvtDeviceWdmPostPoFxRegisterDevice;
poFxSettings.EvtDeviceWdmPrePoFxUnregisterDevice =
                        SingleCompWdmEvtDeviceWdmPrePoFxUnregisterDevice;

poFxSettings.Component = &component;
poFxSettings.ComponentIdleStateCallback = 
                        SingleCompWdmIdleStateCallback;
poFxSettings.PoFxDeviceContext = (PVOID) Device;
    
status = WdfDeviceWdmAssignPowerFrameworkSettings(Device, &poFxSettings);

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Piattaforma di destinazione	Universale
Versione KMDF minima	1.11
Versione UMDF minima	2.33
Intestazione	wdfdevice.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf)