IWDFDevice2：：AssignS0IdleSettings 方法 (wudfddi.h)

项目
08/08/2023

[警告： 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。否则，该方法可能会返回以下值之一：

返回代码	说明
E_INVALIDARG	调用方为输入参数指定了无效值。
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_REQUEST)	调用驱动程序不是设备的电源策略所有者。
HRESULT_FROM_NT (STATUS_POWER_STATE_INVALID)	DxState 参数指定无效的设备电源状态，或 IdleCaps 参数指示设备可以自行唤醒，但总线驱动程序指示设备无法自行唤醒。

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

注解

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

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

在后续调用 AssignS0IdleSettings 期间，框架仅存储 DxState、 IdleTimeout 和 Enabled 参数的值。此外，框架根据以下规则存储 IdleCaps 参数的值：

如果驱动程序在上一次调用 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.)

如果为 IdleTimeout 参数指定 IdleTimeoutDefaultValue，则超时默认为 5 秒。可以检查！wudfext.wudfdevice 和！wudfext.umdevstacks 调试器扩展的输出，以查看有效的设置和电源引用。

有关控制设备空闲功能的注册表项的信息，请参阅 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);

要求

要求	值
结束支持	在 UMDF 2.0 及更高版本中不可用。
目标平台	桌面
最低 UMDF 版本	1.9
标头	wudfddi.h (包括 Wudfddi.h)
DLL	WUDFx.dll

另请参阅

IWDFDevice2

IWDFDevice2：：AssignSxWakeSettings

IWDFDevice3：：AssignS0IdleSettingsEx

通过

IWDFDevice2：：AssignS0IdleSettings 方法 (wudfddi.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

其他资源