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
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的呼叫中指定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.)
如果您為IdleTimeout參數指定IdleTimeoutDefaultValue，逾時預設為五秒。 您可以檢查 ！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