Fungsi ExRegisterCallback (wdm.h)

Artikel
02/29/2024

Rutinitas ExRegisterCallback mendaftarkan rutinitas panggilan balik tertentu dengan objek panggilan balik tertentu.

Sintaks

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

Parameter

[in, out] CallbackObject

Penunjuk ke objek panggilan balik yang diperoleh dari rutinitas ExCreateCallback .

[in] CallbackFunction

Penunjuk ke rutinitas panggilan balik yang diimplementasikan driver, yang harus tidak dapat dicabut. Rutinitas panggilan balik harus sesuai dengan prototipe berikut:

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

Parameter rutin panggilan balik adalah sebagai berikut:

CallbackContext

Penunjuk ke area konteks yang disediakan driver seperti yang ditentukan dalam parameter CallbackContextexRegisterCallback.

Argumen1

Penunjuk ke parameter yang ditentukan oleh objek panggilan balik.

Argumen2

Penunjuk ke parameter yang ditentukan oleh objek panggilan balik.

[in, optional] CallbackContext

Penunjuk ke struktur item data yang ditentukan penelepon untuk diteruskan sebagai parameter konteks rutin panggilan balik setiap kali dipanggil. Biasanya konteks adalah bagian dari ekstensi objek perangkat pemanggil.

Nilai kembali

ExRegisterCallback mengembalikan pointer ke handel pendaftaran panggilan balik yang harus diperlakukan sebagai buram dan dicadangkan untuk penggunaan sistem. Pointer ini ADALAH NULL jika ExRegisterCallback selesai dengan kesalahan.

Keterangan

Driver memanggil ExRegisterCallback untuk mendaftarkan rutinitas panggilan balik dengan objek panggilan balik tertentu.

Jika objek hanya mengizinkan satu rutinitas panggilan balik terdaftar, dan rutinitas seperti itu sudah terdaftar, ExRegisterCallback mengembalikan NULL.

Penelepon ExRegisterCallback harus menyimpan penunjuk yang dikembalikan untuk digunakan nanti dalam panggilan ke ExUnregisterCallback. Penunjuk diperlukan saat menghapus rutinitas panggilan balik dari daftar rutinitas panggilan balik terdaftar untuk objek panggilan balik.

Arti Argumen1 dan Argumen2 dari rutinitas panggilan balik terdaftar bergantung pada objek panggilan balik dan didefinisikan oleh komponen yang membuatnya. Berikut ini adalah parameter untuk objek panggilan balik yang ditentukan sistem:

\Callback\SetSystemTime

Argumen1 (SetSystemTime)

Tidak digunakan.

Argumen2 (SetSystemTime)

Tidak digunakan.

\Callback\PowerState**

Argumen1 (PowerState)

Nilai konstanta PO_CB_XXX yang dilemparkan untuk mengetik PVOID.
PO_CB_AC_STATUS — Menunjukkan bahwa sistem telah berubah dari A/C menjadi daya baterai, atau sebaliknya.
PO_CB_LID_SWITCH_STATE — Menunjukkan bahwa sakelar tutup telah berubah status.
PO_CB_PROCESSOR_POWER_POLICY — Menunjukkan bahwa kebijakan daya prosesor sistem telah berubah.
PO_CB_SYSTEM_POWER_POLICY — Menunjukkan bahwa kebijakan daya sistem telah berubah.
PO_CB_SYSTEM_STATE_LOCK — Menunjukkan bahwa perubahan status daya sistem akan segera terjadi. Driver di jalur penomoran dapat mendaftar untuk panggilan balik ini untuk menerima peringatan dini tentang perubahan tersebut, memungkinkan mereka kesempatan untuk mengunci kode mereka dalam memori sebelum status daya berubah.

Argumen2 (PowerState)

Nilai TRUE atau FALSE yang dilemparkan untuk mengetik PVOID.

Jika Argumen1 PO_CB_AC_STATUS, Argumen2TRUE jika komputer saat ini menggunakan catu daya A/C, dan FALSE jika komputer berjalan pada daya baterai.
Jika Argumen1 PO_CB_LID_SWITCH_STATE, Argumen2adalah TRUE jika tutup saat ini terbuka, dan FALSE jika tutupnya ditutup.
Jika Argumen1 PO_CB_PROCESSOR_POWER_POLICY, Argumen2 tidak digunakan.
Jika Argumen1 PO_CB_SYSTEM_POWER_POLICY, Argumen2 tidak digunakan.
Jika Argumen1 PO_CB_SYSTEM_STATE_LOCK, Argumen2FALSE jika komputer akan keluar dari status daya sistem S0, dan TRUE jika komputer baru saja masuk kembali S0.

\Callback\ProcessorAdd

Argumen1 (ProcessorAdd)

Penunjuk ke struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang menjelaskan peristiwa pemberitahuan perubahan prosesor. Pointer ini dilemparkan untuk mengetik PVOID. Rutinitas panggilan balik tidak boleh mengubah isi struktur ini.

Argumen2 (ProcessorAdd)

Penunjuk ke variabel yang berisi nilai NTSTATUS. Pointer ini dilemparkan untuk mengetik PVOID. Dalam kondisi tertentu, rutinitas panggilan balik dapat menulis nilai status kesalahan ke variabel ini untuk menunjukkan mengapa prosesor baru tidak boleh ditambahkan. Driver perangkat tidak boleh mengubah nilai variabel ini kecuali ketiga kondisi berikut ini benar:

Kesalahan terjadi selama pemrosesan rutinitas panggilan balik yang seharusnya mencegah prosesor baru ditambahkan.
Nilai anggota Status dari struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang dirujuk Argumen1 adalah KeProcessorAddStartNotify.
Variabel NSTATUS yang dituju argumen2 berisi nilai STATUS_SUCCESS. Artinya, rutinitas panggilan balik tidak boleh menimpa nilai status kesalahan yang sebelumnya ditulis oleh klien pemberitahuan panggilan balik lain.

Dimulai dengan Windows Vista, objek panggilan balik \Callback\ProcessorAdd tersedia untuk melacak perubahan populasi prosesor secara dinamis. Rutinitas KeRegisterProcessorChangeCallback menyediakan informasi serupa, tetapi juga mendukung bendera KE_PROCESSOR_CHANGE_ADD_EXISTING yang dapat digunakan driver untuk menghitung prosesor dalam konfigurasi sistem multiprosesor awal. Untuk driver yang berjalan di Windows Server 2008 dan versi Windows yang lebih baru, gunakan KeRegisterProcessorChangeCallback alih-alih objek panggilan balik \Callback\ProcessorAdd , jika memungkinkan.

Untuk informasi selengkapnya tentang objek panggilan balik, lihat Objek Panggilan Balik.

Sistem operasi memanggil rutinitas panggilan balik terdaftar di IRQL yang sama di mana driver yang membuat panggilan balik yang disebut rutinitas ExNotifyCallback .

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)