Metode IWDFDevice2::AssignS0IdleSettings (wudfddi.h)

Artikel
08/08/2023

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode AssignS0IdleSettings menyediakan informasi yang disediakan driver yang digunakan kerangka kerja saat perangkat menganggur dan sistem dalam status berfungsi (S0).

Sintaks

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
);

Parameter

[in] IdleCaps

Enumerator berjenis WDF_POWER_POLICY_S0_IDLE_CAPABILITIES yang mengidentifikasi kemampuan perangkat untuk membangunkan dirinya sendiri setelah diatur ke status daya rendah, sementara sistem tetap dalam status berfungsi (S0).

[in] DxState

Enumerator jenis DEVICE_POWER_STATE yang mengidentifikasi status daya perangkat rendah yang akan dimasukkan perangkat setelah periode batas waktu diam berakhir. nilai DEVICE_POWER_STATE didefinisikan dalam wdm.h.

[in] IdleTimeout

Jumlah waktu, dalam milidetik, bahwa perangkat akan tetap menganggur sebelum kerangka kerja menempatkannya dalam status daya rendah yang disediakan DxState. Untuk menggunakan nilai batas waktu menganggur default kerangka kerja, tentukan IdleTimeoutDefaultValue Untuk informasi selengkapnya, lihat bagian Keterangan.

[in] UserControlOfIdleSettings

Enumerator yang diketik WDF_POWER_POLICY_S0_IDLE_USER_CONTROL yang menunjukkan apakah pengguna memiliki kemampuan untuk mengubah pengaturan diam perangkat.

[in] Enabled

Enumerator jenis WDF_TRI_STATE yang menunjukkan apakah perangkat akan dimatikan jika tetap menganggur dan saat daya sistem berada di S0. Anggota ini bisa memiliki salah satu nilai berikut ini:

WdfTrue - Mematikan diaktifkan.

WdfFalse - Mematikan dinonaktifkan.

WdfUseDefault - Powering down awalnya diaktifkan secara default; tetapi jika parameter UserControlOfIdleSettings diatur ke IdleAllowUserControl, pengaturan pengguna atau file INF driver akan mengambil alih nilai awal.

Jika daya mati diaktifkan, perangkat memiliki kemampuan bangun, dan nilai batas waktu diam kedaluwarsa, kerangka kerja memanggil fungsi panggilan balik IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 driver sebelum perangkat memasuki status daya rendah.

Nilai kembali

AssignS0IdleSettings mengembalikan S_OK jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
E_INVALIDARG	Pemanggil menentukan nilai yang tidak valid untuk parameter input.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	Driver panggilan bukan pemilik kebijakan daya perangkat.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	Parameter DxState menentukan status daya perangkat yang tidak valid, atau parameter IdleCaps menunjukkan perangkat dapat bangun sendiri, tetapi driver bus menunjukkan perangkat tidak dapat bangun sendiri.

Metode ini mungkin mengembalikan salah satu nilai lain yang dikandung Winerror.h.

Keterangan

Pertama kali driver memanggil AssignS0IdleSettings, tindakan berikut terjadi:

Kerangka kerja menyimpan nilai semua parameter.
Jika parameter UserControlOfIdleSettings diatur ke IdleAllowUserControl dan jika parameter Diaktifkan diatur ke WdfUseDefault, kerangka kerja membaca registri untuk mengetahui apakah pengguna telah mengaktifkan daya perangkat saat diam.

Selama panggilan berikutnya ke AssignS0IdleSettings, kerangka kerja hanya menyimpan nilai parameter DxState, IdleTimeout, dan Enabled . Selain itu, kerangka kerja menyimpan nilai parameter IdleCaps yang tunduk pada aturan berikut:

Jika driver pernah menentukan IdleCanWakeFromS0 untuk nilai parameter IdleCaps dalam panggilan sebelumnya ke AssignS0IdleSettings, itu tidak dapat mengubah nilai tersebut menjadi IdleUsbSelectiveSuspend.
Jika driver pernah menentukan IdleUsbSelectiveSuspend untuk nilai parameter IdleCaps dalam panggilan sebelumnya ke AssignS0IdleSettings, itu kemudian tidak dapat mengubah nilai tersebut menjadi IdleCanWakeFromS0.

Aturan berikut berlaku untuk nilai yang Anda tentukan untuk parameter DxState :

Nilai tidak boleh PowerDeviceD0.
Untuk perangkat USB, nilainya tidak boleh PowerDeviceD0 atau PowerDeviceD3.
Jika Anda menentukan DevicePowerMaximum, kerangka kerja menggunakan nilai driver mode kernel untuk bus perangkat yang disediakan di anggota DeviceWake dari struktur WDF_DEVICE_POWER_CAPABILITIES-nya .
Jika nilai parameter IdleCaps adalah IdleCanWakeFromS0 atau IdleUsbSelectiveSuspend, Anda tidak dapat menentukan status daya perangkat yang lebih rendah dari status daya perangkat di anggota DeviceWake dari struktur WDF_DEVICE_POWER_CAPABILITIES driver bus mode kernel. (Dengan kata lain, jika nilai DeviceWake driver bus adalah PowerDeviceD2, nilai DxState driver fungsi Anda tidak boleh PowerDeviceD3.)

Jika Anda menentukan IdleTimeoutDefaultValue untuk parameter IdleTimeout , batas waktu defaultnya adalah lima detik. Anda dapat memeriksa output dari ekstensi debugger !wudfext.wudfdevice dan !wudfext.umdevstacks untuk melihat pengaturan efektif dan referensi daya.

Untuk informasi tentang entri registri yang mengontrol kemampuan diam perangkat, lihat Kontrol Pengguna Perilaku Menganggur dan Bangun Perangkat di UMDF.

Untuk informasi selengkapnya tentang mendukung kemampuan diam perangkat, lihat Mendukung Power-Down menganggur di Driver berbasis UMDF.

Contoh

Contoh kode berikut didasarkan pada versi UMDF dari sampel pemangsa toaster. Contohnya mendapatkan antarmuka IWDFDevice2 lalu memanggil 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);

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1.9
Header	wudfddi.h (termasuk Wudfddi.h)
DLL	WUDFx.dll

Lihat juga

IWDFDevice2

IWDFDevice2::AssignSxWakeSettings

IWDFDevice3::AssignS0IdleSettingsEx

Bagikan melalui