Метод IWDFDevice2::AssignS0IdleSettings (wudfddi.h)

Статья
08/08/2023

[Предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. В UMDF 1 новые функции не добавляются, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе начало работы с UMDF.]

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

Синтаксис

HRESULT AssignS0IdleSettings(
  [in] WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps,
  [in] DEVICE_POWER_STATE                    DxState,
  [in] ULONG                                 IdleTimeout,
  [in] WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Параметры

[in] IdleCaps

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

[in] DxState

DEVICE_POWER_STATE типизированный перечислитель, определяющий низкое состояние питания устройства, которое будет введено устройством после истечения периода ожидания простоя. DEVICE_POWER_STATE значения определяются в wdm.h.

[in] IdleTimeout

Время в миллисекундах, в течение которого устройство будет оставаться в состоянии простоя, прежде чем платформа переместит его в состояние с низким энергопотреблением DxState. Чтобы использовать значение времени ожидания бездействия платформы по умолчанию, укажите IdleTimeoutDefaultValue Дополнительные сведения см. в разделе Примечания.

[in] UserControlOfIdleSettings

WDF_POWER_POLICY_S0_IDLE_USER_CONTROL типизированный перечислитель, который указывает, имеют ли пользователи возможность изменять параметры простоя устройства.

[in] Enabled

WDF_TRI_STATE типизированный перечислитель, который указывает, будет ли устройство выключено, если оно остается бездействующим и пока питание системы находится на уровне S0. Этот элемент может иметь одно из следующих значений:

WdfTrue — выключение питания включено.

WdfFalse — выключение питания отключено.

WdfUseDefault — выключение питания изначально включено по умолчанию; но если параметру UserControlOfIdleSettings присвоено значение IdleAllowUserControl, то параметр пользователя или INF-файл драйвера переопределяет начальное значение.

Если выключение включено, устройство имеет возможность пробуждения и истекает время ожидания простоя, платформа вызывает функцию обратного вызова IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 , прежде чем устройство перейдет в состояние с низким энергопотреблением.

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

Функция AssignS0IdleSettings возвращает S_OK, если операция выполнена успешно. В противном случае метод может вернуть одно из следующих значений:

Код возврата	Описание
E_INVALIDARG	Вызывающий объект указал недопустимое значение для входного параметра.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	Вызывающий драйвер не является владельцем политики питания устройства.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	Параметр DxState указывает недопустимое состояние питания устройства, или параметр IdleCaps указывает, что устройство может самостоятельно проснуться, но драйвер шины указывает, что устройство не может пробуждение.

Этот метод может возвращать одно из других значений, содержащихся в Winerror.h.

Платформа хранит значения всех параметров.
Если для параметра UserControlOfIdleSettings задано значение IdleAllowUserControl , а для параметра Enabled задано значение WdfUseDefault, платформа считывает реестр, чтобы узнать, включил ли пользователь выключение устройства при его простое.

Во время последующих вызовов AssignS0IdleSettings платформа хранит только значения параметров DxState, IdleTimeout и Enabled . Кроме того, платформа хранит значение параметра IdleCaps в соответствии со следующими правилами:

Если драйвер когда-либо указывал IdleCanWakeFromS0 для значения параметра IdleCaps в предыдущем вызове AssignS0IdleSettings, он не сможет впоследствии изменить это значение на IdleUsbSelectiveSuspend.
Если драйвер когда-либо указывал IdleUsbSelectiveSuspend для значения параметра IdleCaps в предыдущем вызове AssignS0IdleSettings, он не сможет впоследствии изменить это значение на IdleCanWakeFromS0.

Следующие правила применяются к значению, указанному для параметра DxState :

Значение не может быть PowerDeviceD0.
Для USB-устройств значением не может быть PowerDeviceD0 или PowerDeviceD3.
Если указать DevicePowerMaximum, платформа использует значение драйвера режима ядра для шины устройства, указанное в элементе DeviceWake структуры WDF_DEVICE_POWER_CAPABILITIES .
Если параметр IdleCaps имеет значение IdleCanWakeFromS0 или IdleUsbSelectiveSuspend, нельзя указать состояние питания устройства, которое ниже состояния питания устройства в элементе DeviceWakeWDF_DEVICE_POWER_CAPABILITIES структуры драйвера шины режима ядра. (Другими словами, если значение DeviceWake драйвера шины равно PowerDeviceD2, значение DxState драйвера функции не может быть PowerDeviceD3.)

Если указать IdleTimeoutDefaultValue для параметра IdleTimeout , время ожидания по умолчанию будет пять секунд. Вы можете изучить выходные данные расширений отладчика !wudfext.wudfdevice и !wudfext.umdevstacks , чтобы просмотреть действующие параметры и ссылки на питание.

Сведения о записях реестра, которые управляют возможностями простоя устройства, см. в статье Управление пользователем простоя устройства и поведение пробуждения в UMDF.

Дополнительные сведения о поддержке бездействующих возможностей устройства см. в статье Поддержка Power-Down бездействия в драйверах на основе UMDF.

Примеры

Следующий пример кода основан на версии UMDF примера тостера. В примере получается интерфейс IWDFDevice2 , а затем вызывается метод AssignS0IdleSettings.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
    //
    // The toaster device is virtual, so we tell the framework that the 
    // device cannot wake if it sleeps while the system is in S0. The device 
    // can return to D0 only when the driver stack receives an I/O request.
    //
    hr = pIWDFDevice2->AssignS0IdleSettings(IdleCannotWakeFromS0,
                                            PowerDeviceD3,
                                            IDLEWAKE_TIMEOUT_MSEC,
                                            IdleAllowUserControl,
                                            WdfTrue);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Требования

Требование	Значение
Дата окончания поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
Целевая платформа	Персональный компьютер
Минимальная версия UMDF	1,9
Верхняя часть	wudfddi.h (включая Wudfddi.h)
DLL	WUDFx.dll

См. также раздел

IWDFDevice2

IWDFDevice2::AssignSxWakeSettings

IWDFDevice3::AssignS0IdleSettingsEx