Fungsi PoRegisterPowerSettingCallback (ntifs.h)

Artikel
07/11/2023

Rutinitas PoRegisterPowerSettingCallback mendaftarkan rutinitas panggilan balik pengaturan daya untuk menerima pemberitahuan perubahan dalam pengaturan daya yang ditentukan.

Sintaks

NTSTATUS PoRegisterPowerSettingCallback(
  [in, optional] PDEVICE_OBJECT          DeviceObject,
  [in]           LPCGUID                 SettingGuid,
  [in]           PPOWER_SETTING_CALLBACK Callback,
  [in, optional] PVOID                   Context,
  [out]          PVOID                   *Handle
);

Parameter

[in, optional] DeviceObject

Penunjuk ke struktur DEVICE_OBJECT yang terkait dengan pemanggil rutinitas ini. Parameter ini bersifat opsional. Ini digunakan secara internal hanya untuk tujuan penelusuran kesalahan. Jika parameter ini tidak disediakan, parameter harus diatur ke NULL.

[in] SettingGuid

Penunjuk ke GUID yang mewakili pengaturan daya untuk pendaftaran ini. Ketika pengaturan daya yang ditentukan berubah, manajer daya memanggil rutinitas panggilan balik untuk memberi tahu driver tentang perubahan dan untuk menyediakan nilai baru pengaturan. Untuk informasi selengkapnya, lihat Keterangan.

[in] Callback

Penunjuk ke rutinitas panggilan balik pengaturan daya yang diterapkan penelepon yang dipanggil manajer daya saat pengaturan daya yang ditentukan berubah. Untuk prototipe fungsional untuk rutinitas panggilan balik, lihat Panggilan Balik Pengaturan Daya, di bawah ini.

[in, optional] Context

Penunjuk ke konteks untuk rutinitas panggilan balik. Parameter ini bersifat opsional. Ini disediakan sehingga konteks driver atau perangkat dapat diteruskan ke rutinitas panggilan balik. Jika parameter ini tidak digunakan, parameter harus diatur ke NULL.

[out] Handle

Handel yang digunakan manajer daya untuk mewakili rutinitas panggilan balik. Driver kemudian harus menyediakan handel ini dalam panggilan ke PoUnregisterPowerSettingCallback untuk membatalkan pendaftaran rutinitas panggilan balik.

Mengembalikan nilai

PoRegisterPowerSettingCallback mengembalikan salah satu hal berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Rutinitas mendaftarkan rutinitas panggilan balik.
STATUS_ INSUFFICIENT_RESOURCES	Rutinitas tidak dapat mengalokasikan sumber daya sistem yang diperlukan untuk mendaftarkan rutinitas panggilan balik.

Keterangan

Driver memanggil PoRegisterPowerSettingCallback untuk mendaftarkan rutinitas panggilan balik dengan manajer daya. Manajer daya kemudian memanggil rutinitas panggilan balik ini untuk memberi tahu driver setelah ada perubahan pada pengaturan daya yang ditentukan. Selain itu, manajer daya menginisialisasi pengaturan daya driver dengan segera memanggil rutinitas panggilan balik dan melewati nilai pengaturan daya saat ini. Manajer daya menginisialisasi pengaturan daya driver dengan cara ini terlepas dari apakah pengaturan daya benar-benar berubah.

Driver harus memanggil PoRegisterPowerSettingCallback untuk setiap pengaturan daya yang perlu dipantau driver. Driver harus memanggil rutinitas ini dalam rutinitas DriverEntry mereka selama inisialisasi. Biasanya, sebagian besar driver meneruskan pointer ke ekstensi perangkat dalam parameter Konteks .

Untuk membatalkan pendaftaran panggilan balik pengaturan daya, panggil rutinitas PoUnregisterPowerSettingCallback .

Biasanya, driver Kernel-Mode Driver Framework (KMDF) harus memanggil PoRegisterPowerSettingCallback dari fungsi panggilan balik EvtDeviceSelfManagedIoInit mereka, dan harus memanggil PoUnregisterPowerSettingCallback dari fungsi panggilan balik EvtDeviceSelfManagedIoCleanup mereka. Driver ini tidak boleh memanggil PoRegisterPowerSettingCallback dari fungsi panggilan balik EvtDriverDeviceAdd mereka; jika tidak, rutinitas panggilan balik pengaturan daya mungkin dipanggil sebelum tumpukan driver benar-benar dibangun.

Rutinitas panggilan balik yang terdaftar untuk pengaturan daya tertentu dipanggil ketika transisi dalam status daya terjadi yang mengubah nilai pengaturan, atau ketika manajer daya mengubah nilai pengaturan. Misalnya, jika SettingGuid menunjuk ke nilai GUID GUID_LIDSWITCH_STATE_CHANGE, rutinitas panggilan balik dipanggil saat penutup ke komputer laptop mengklik buka atau ditutup. Parameter Nilai diteruskan ke rutinitas panggilan balik dalam contoh ini menunjuk ke nilai ULONG yaitu 1 jika status sakelar tutup berubah dari tertutup menjadi terbuka, dan adalah 0 jika status sakelar tutup berubah dari terbuka menjadi tertutup. Untuk informasi selengkapnya, lihat definisi GUID pengaturan daya dan komentar ekstensif dalam file header Wdm.h.

Panggilan awal ke rutinitas panggilan balik mungkin segera terjadi, sebelum panggilan PoRegisterPowerSettingCallback yang mendaftarkan pengembalian rutin.

PoRegisterPowerSettingCallback hanya dapat dipanggil di IRQL = PASSIVE_LEVEL.

Panggilan Balik Power-Setting

Prototipe fungsi dari rutinitas panggilan balik pengaturan daya dan parameternya adalah sebagai berikut. Manajer daya memanggil panggilan balik pengaturan daya di IRQL = PASSIVE_LEVEL.

NTSTATUS
POWER_SETTING_CALLBACK (
  _In_ LPCGUID SettingGuid,
  _In_ PVOID Value,
  _In_ ULONG ValueLength,
  _Inout_opt_ PVOID Context
);

Parameter	Deskripsi
SettingGuid	Penunjuk ke GUID yang mewakili pengaturan daya yang berubah. Pengaturan daya dan GUID yang sesuai ditentukan dalam Wdm.h.
Nilai	Penunjuk ke nilai baru pengaturan daya yang berubah.
ValueLength	Nilai jenis ULONG yang menentukan ukuran, dalam byte, dari nilai pengaturan daya baru.
Konteks	Penunjuk ke konteks yang disediakan driver dalam panggilan ke PoRegisterPowerSettingCallback yang mendaftarkan rutinitas panggilan balik.

Contoh

Untuk menentukan rutinitas panggilan balik pengaturan daya, Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan rutinitas panggilan balik pengaturan daya yang diberi nama MyPowerSettingCallback, gunakan jenis POWER_SETTING_CALLBACK seperti yang ditunjukkan dalam contoh kode ini:

POWER_SETTING_CALLBACK MyPowerSettingCallback;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
NTSTATUS
  MyPowerSettingCallback(
    LPCGUID SettingGuid,
    PVOID Value,
    ULONG ValueLength,
    PVOID Context 
    )
  {
      // Function body
  }

Jenis fungsi POWER_SETTING_CALLBACK ditentukan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi POWER_SETTING_CALLBACK dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Target Platform	Universal
Header	ntifs.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)