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

システムが動作 (S0) 状態のまま、低電力状態に設定された後にデバイスがスリープ解除する機能を識別する、 WDF_POWER_POLICY_S0_IDLE_CAPABILITIES型の列挙子。

[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

アイドル状態のままでシステム電源が S0 の間にデバイスの電源が切れるかどうかを示す、 WDF_TRI_STATE型指定の列挙子。このメンバーには、次のいずれかの値を指定できます。

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
Header	wudfddi.h (Wudfddi.h を含む)
[DLL]	WUDFx.dll

こちらもご覧ください

IWDFDevice2

IWDFDevice2::AssignSxWakeSettings

IWDFDevice3::AssignS0IdleSettingsEx

IWDFDevice2::AssignS0IdleSettings メソッド (wudfddi.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース