IWDFDevice2：：AssignS0IdleSettings 方法（wudfddi.h）

项目
02/07/2025

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。没有将新功能添加到 UMDF 1，并且对较新版本的 Windows 10 上的 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅 UMDF入门。]

AssignS0IdleSettings 方法提供驱动程序提供的信息，框架在设备处于空闲状态且系统处于其工作状态时所使用的驱动程序提供的信息。

语法

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和 已启用 参数的值。此外，框架还存储 IdleCaps 参数的值，但遵循以下规则：

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

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

该值不能 PowerDeviceD0。
对于 USB 设备，该值不能 PowerDeviceD0 或 PowerDeviceD3。
如果指定 DevicePowerMaximum，则框架将使用 DeviceWake 中提供的设备的总线内核模式驱动程序的值 其 WDF_DEVICE_POWER_CAPABILITIES 结构的成员。
如果 IdleCaps 参数的值 IdleCanWakeFromS0 或 IdleUsbSelectiveSuspend，则不能指定低于 DeviceWake 内核模式总线驱动程序 WDF_DEVICE_POWER_CAPABILITIES 结构中的设备电源状态的设备电源状态。（换句话说，如果总线驱动程序的 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）

语法

参数

返回值

言论

例子

要求

另请参阅

反馈

其他资源