IWDFDevice2：：AssignS0IdleSettings 方法 (wudfddi.h)

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 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。 否则，该方法可能会返回以下值之一：

此方法可能会返回 Winerror.h 包含的其他值之一。

注解

驱动程序首次调用 AssignS0IdleSettings 时，将执行以下操作：

• 框架存储所有参数的值。
• 如果 UserControlOfIdleSettings 参数设置为 IdleAllowUserControl ，并且 Enabled 参数设置为 WdfUseDefault，框架将读取注册表，以确定用户是否已启用在空闲时关闭设备。

• 如果驱动程序在上一次调用 AssignS0IdleSettings 时曾为 IdleCaps 参数的值指定 IdleCanWakeFromS0，则它随后无法将该值更改为 IdleUsbSelectiveSuspend。
• 如果驱动程序在上次调用 AssignS0IdleSettings 时曾为 IdleCaps 参数的值指定 IdleUsbSelectiveSuspend，则它随后无法将该值更改为 IdleCanWakeFromS0。

以下规则适用于为 DxState 参数指定的值：

• 该值不能为 PowerDeviceD0。
• 对于 USB 设备，该值不能为 PowerDeviceD0 或 PowerDeviceD3。
• 如果指定 DevicePowerMaximum，框架将使用设备总线内核模式驱动程序在其WDF_DEVICE_POWER_CAPABILITIES结构的 DeviceWake 成员中提供的值。
• 如果 IdleCaps 参数的值为 IdleCanWakeFromS0 或 IdleUsbSelectiveSuspend，则无法在内核模式总线驱动程序WDF_DEVICE_POWER_CAPABILITIES结构的 DeviceWake 成员中指定低于设备电源状态的设备电源状态。 (换言之，如果总线驱动程序的 DeviceWake 值为 PowerDeviceD2，则函数驱动程序的 DxState 值不能为 PowerDeviceD3.)

有关控制设备空闲功能的注册表项的信息，请参阅 UMDF 中的设备空闲和唤醒行为的用户控制。

有关支持设备空闲功能的详细信息，请参阅 支持基于 UMDF 的驱动程序中的空闲 Power-Down。

示例

下面的代码示例基于 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);

要求

另请参阅

IWDFDevice2

IWDFDevice2：：AssignSxWakeSettings

IWDFDevice3：：AssignS0IdleSettingsEx