IWDFDevice2：：AssignS0IdleSettings 方法 (wudfddi.h)
[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。 所有新的UMDF驅動程式都應該使用UMDF 2撰寫。 未將新功能新增至 UMDF 1，且較新版本的 #D6DA99D0C77694B13BF623E0850D6F2AD 上，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。 否則，方法可能會傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
|
呼叫端為輸入參數指定了無效的值。 |
|
呼叫驅動程式不是裝置的 電源原則擁有者。 |
|
DxState 參數會指定無效的裝置電源狀態，或 IdleCaps 參數表示裝置可以自行喚醒，但總線驅動程式表示裝置無法喚醒本身。 |
這個方法可能會傳回 Winerror.h 包含的其他其中一個值。
備註
驅動程式第一次呼叫 AssignS0IdleSettings 時，會發生下列動作：
- 架構會儲存所有參數的值。
- 如果 UserControlOfIdleSettings 參數設定為 IdleAllowUserControl ，而且 Enabled 參數設定為 WdfUseDefault，則架構會讀取登錄，以瞭解使用者在閑置時是否已啟用關閉裝置電源。
- 如果驅動程式先前對AssignS0IdleSettings的呼叫中指定IdleCanWakeFromS0的IdleCaps 參數值，則後續無法將該值變更為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);
規格需求
| 需求 | 值 |
|---|---|
| 終止支援 | 在 UMDF 2.0 和更新版本中無法使用。 |
| 目標平台 | 桌面 |
| 最低UMDF版本 | 1.9 |
| 標頭 | wudfddi.h (包含 Wudfddi.h) |
| Dll | WUDFx.dll |