Функция WdfDeviceWdmAssignPowerFrameworkSettings (wdfdevice.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfDeviceWdmAssignPowerFrameworkSettings регистрирует параметры платформы управления питанием (PoFx) для однокомпонентных устройств.

Синтаксис

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

Параметры

[in] Device

Дескриптор объекта устройства платформы, для которого задаются параметры PoFx.

[in] PowerFrameworkSettings

Указатель на структуру WDF_POWER_FRAMEWORK_SETTINGS , описывающую параметры PoFx клиентского драйвера.

Возвращаемое значение

Метод WdfDeviceWdmAssignPowerFrameworkSettings возвращает значение NTSTATUS, указывающее на успешное или неудачное выполнение операции.

Код возврата	Описание
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS .
STATUS_INVALID_DEVICE_REQUEST	Вызывающий драйвер не является владельцем политики питания устройства.
STATUS_INVALID_PARAMETER	Обнаружено недопустимое значение параметров .

Этот метод также может возвращать другие значения NTSTATUS.

Перед вызовом этого метода драйвер клиента должен успешно вызвать WdfDeviceAssignS0IdleSettings и задать для поля IdleTimeoutType структуры WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS значение SystemManagedIdleTimeout или SystemManagedIdleTimeoutWithHint.

Драйвер должен вызывать WdfDeviceWdmAssignPowerFrameworkSettings до или во время первого запуска устройства. Так как устройство может запускаться несколько раз, например при повторной балансировке ресурсов, драйвер может вызвать этот метод из evtDriverDeviceAdd или EvtDeviceSelfManagedIoInit. Платформа вызывает эти функции только один раз, даже если устройство запускается несколько раз.

Кроме того, драйвер может отслеживать, вызывал ли он уже WdfDeviceWdmAssignPowerFrameworkSettings, и вызывать его из одной из следующих функций обратного вызова: EvtDevicePrepareHardware, EvtDeviceD0Entry, EvtDeviceD0EntryPostInterruptsEnabled или EvtDeviceSelfManagedIoRestart.

Если драйвер вызывает WdfDeviceWdmAssignPowerFrameworkSettings несколько раз, платформа создает ошибку средства проверки.

Платформа управления питанием (PoFx) доступна только в Windows 8 и более поздних версиях. При запуске в операционной системе, которая не поддерживает PoFx, WdfDeviceWdmAssignPowerFrameworkSettings не выполняет никаких действий и возвращает STATUS_SUCCESS.

Дополнительные сведения см. в разделах Поддержка функциональных состояний питания и Обзор платформы управления питанием.

Примеры

В следующем примере кода драйвер инициализирует структуру WDF_POWER_FRAMEWORK_SETTINGS путем вызова функции WDF_POWER_FRAMEWORK_SETTINGS_INIT . Затем драйвер вручную задает некоторые элементы структуры, а затем вызывает 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);

Требования

Требование	Значение
Минимальная версия клиента	Windows 8
Целевая платформа	Универсальное
Минимальная версия KMDF	1.11
Минимальная версия UMDF	2.33
Верхняя часть	wdfdevice.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки платформы).
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf)