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

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Метод WdfDeviceAssignS0IdleSettings предоставляет предоставленные драйвером сведения о том, что платформа использует, когда устройство неактивно, и система находится в состоянии работы (S0).

Синтаксис

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

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] Settings

Указатель на структуру, предоставляемую вызывающим WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS.

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

Если операция выполнена успешно, WdfDeviceAssignS0IdleSettings возвращает STATUS_SUCCESS. К дополнительным возвращаемым значениям относятся:

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_REQUEST	Вызывающий драйвер не является владельцем политики питания устройства.
STATUS_INVALID_PARAMETER	Обнаружено недопустимое значение параметра .
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS.
STATUS_POWER_STATE_INVALID	Это значение возвращается, если происходит одно из следующих действий: Структура WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS содержит недопустимое состояние питания устройства. Элемент IdleCaps структуры WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS указывает, что устройство может проснуться, но драйвер шины указывает, что устройство не может проснуться. Начиная с KMDF версии 1.11, работающей в Windows 8, платформа проверяет, может ли встроенное ПО системы обрабатывать сигнал пробуждения, пока система находится в полном состоянии питания (S0). Если этот флажок завершается ошибкой, WdfDeviceAssignS0IdleSettings возвращает STATUS_POWER_STATE_INVALID, а устройство остается полностью в состоянии питания (D0), пока система остается в S0. В этом случае драйвер не должен возвращать значение состояния ошибки из EvtDriverDeviceAdd или любого другого обратного вызова среды выполнения. В большинстве случаев драйвер может записать ошибку, указывающую, что устройство будет потреблять больше энергии, чем обычно.

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

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Если драйвер задает элемент IdleTimeoutTypeWDF_DEVICE_POWER_POLICY_IDLE_SETTINGSSystemManagedIdleTimeout или SystemManagedIdleTimeoutWithHint, он должен вызывать WdfDeviceAssignS0IdleSettings перед возвращением из EvtDeviceD0Entry. Как правило, драйвер сначала вызывает WdfDeviceAssignS0IdleSettings из EvtDriverDeviceAdd.

Дополнительные вызовы WdfDeviceAssignS0IdleSettings можно выполнять в любое время. Однако после того как драйвер задает значение элемента IdleTimeoutType в первом вызове WdfDeviceAssignS0IdleSettings, оно не должно изменять это значение в последующих вызовах этого метода.

Если драйвер регистрирует асинхронные уведомления в EvtDriverDeviceAdd (например, вызывая PoRegisterPowerSettingCallback или IoRegisterPlugPlayNotification), драйвер не должен вызывать WdfDeviceAssignS0IdleSettings из процедуры обратного вызова драйвера, которую он зарегистрировал.

Дополнительные сведения см. в поддержкебездействия.

Примеры

Следующий пример кода инициализирует структуру WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS, задает значение времени ожидания простоя в 10 секунд и вызывает WdfDeviceAssignS0IdleSettings.

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;
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
минимальная версия UMDF	2.0
заголовка	wdfdevice.h (include Wdf.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf), FDOPowerPolicyOwnerAPI(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NonFDONotPowerPolicyOwnerAPI(kmdf)

См. также

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS

WdfDeviceAssignSxWakeSettings

Поделиться через