EX_CALLBACK_FUNCTION fungsi panggilan balik (wdm.h)
Rutinitas RegistryCallback driver filter dapat memantau, memblokir, atau memodifikasi operasi registri.
Sintaks
EX_CALLBACK_FUNCTION ExCallbackFunction;
NTSTATUS ExCallbackFunction(
[in] PVOID CallbackContext,
[in, optional] PVOID Argument1,
[in, optional] PVOID Argument2
)
{...}
Parameter
[in] CallbackContext
Nilai yang diteruskan driver sebagai parameter Konteks ke CmRegisterCallback atau CmRegisterCallbackEx ketika mendaftarkan rutinitas RegistryCallback ini.
[in, optional] Argument1
Nilai jenis REG_NOTIFY_CLASS yang mengidentifikasi jenis operasi registri yang sedang dilakukan dan apakah rutinitas RegistryCallback dipanggil sebelum atau sesudah operasi registri dilakukan.
[in, optional] Argument2
Penunjuk ke struktur yang berisi informasi yang khusus untuk jenis operasi registri. Jenis struktur bergantung pada nilai REG_NOTIFY_CLASS-typed untuk Argument1, seperti yang diperlihatkan dalam tabel berikut. Untuk informasi tentang nilai REG_NOTIFY_CLASS-jenis mana yang tersedia untuk versi sistem operasi mana, lihat REG_NOTIFY_CLASS.
Dimulai dengan Windows 7, struktur data aktual yang diteruskan ketika kelas beri tahu adalah RegNtPreCreateKeyEx atau RegNtPreOpenKeyEx adalah versi V1 dari struktur ini, masing-masing REG_CREATE_KEY_INFORMATION_V1 atau REG_OPEN_KEY_INFORMATION_V1. Periksa anggota Khusus untuk menentukan versi struktur.
| Nomor Versi | Nama struktur |
|---|---|
| 0 | REG_CREATE_KEY_INFORMATION dan REG_OPEN_KEY_INFORMATION |
| 1 | REG_CREATE_KEY_INFORMATION_V1 dan REG_OPEN_KEY_INFORMATION_V1 |
Mengembalikan nilai
Untuk informasi selengkapnya tentang kapan rutinitas RegistryCallback harus mengembalikan masing-masing nilai status ini, lihat Memfilter Panggilan Registri.
Keterangan
Untuk diberi tahu tentang operasi registri, komponen mode kernel (seperti komponen driver paket perangkat lunak antivirus) dapat memanggil CmRegisterCallback atau CmRegisterCallbackEx untuk mendaftarkan rutinitas RegistryCallback .
Rutinitas RegistryCallback dapat memeriksa konten buffer input dan output yang disediakan untuk operasi registri. Operasi registri dapat dimulai oleh aplikasi mode pengguna yang memanggil rutinitas registri mode pengguna (seperti RegCreateKeyEx atau RegOpenKeyEx) atau oleh driver yang memanggil rutinitas registri mode kernel (seperti ZwCreateKey atau ZwOpenKey). Buffer input adalah buffer memori yang disediakan oleh inisiator tempat registri membaca data input untuk operasi. Buffer output adalah buffer yang disediakan oleh inisiator tempat registri menulis data output yang diminta oleh inisiator.
Sebelum memanggil rutinitas RegistryCallback , pemeriksaan kernel (untuk memverifikasi perataan dan aksesibilitas) semua anggota struktur Argument2 yang menunjuk ke buffer output dalam memori mode pengguna, tetapi tidak menangkap buffer output mode pengguna dalam memori sistem. Rutinitas panggilan balik harus mengapit akses apa pun dari buffer output dalam blok coba/kecuali . Jika rutinitas panggilan balik perlu meneruskan penunjuk buffer output ke rutinitas sistem (misalnya, ZwOpenKey), dan buffer berada dalam memori mode pengguna, rutinitas panggilan balik harus terlebih dahulu menangkap buffer.
Penanganan buffer input tergantung pada versi Windows. Dimulai dengan Windows 8, kernel menangkap semua buffer input yang ditunjukkan oleh anggota struktur Argument2 dalam memori sistem sebelum memanggil rutinitas RegistryCallback. Dalam versi Windows sebelum Windows 8, kernel memeriksa semua anggota struktur Argument2 yang menunjuk ke buffer input dalam memori mode pengguna, tetapi hanya menangkap beberapa buffer ini dalam memori sistem. Dalam versi Windows sebelumnya ini, rutinitas panggilan balik harus mengapit akses apa pun dari buffer input dalam blok coba/kecuali . Selain itu, jika rutinitas panggilan balik perlu meneruskan penunjuk buffer input ke rutinitas sistem (misalnya, ZwOpenKey), dan buffer berada dalam memori mode pengguna, rutinitas panggilan balik harus terlebih dahulu menangkap buffer.
Tabel berikut ini meringkas persyaratan untuk akses buffer oleh rutinitas RegistryCallback .
| Jenis buffer | Versi Windows | Penunjuk buffer diteruskan ke rutinitas panggilan balik | Aman untuk rutinitas panggilan balik untuk akses langsung? | Aman untuk diteruskan ke rutinitas sistem (seperti ZwOpenKey)? |
|---|---|---|---|---|
| Input mode pengguna | Windows 8 dan yang lebih baru | Menunjuk ke data yang diambil. | Ya | Ya |
| Input mode pengguna | Windows 7 dan versi sebelumnya | Menunjuk ke data yang diambil atau buffer mode pengguna asli. | Nomor. Harus dibaca di bawah coba/kecuali. | Nomor. Harus mengalokasikan memori kernel, menyalin data dari buffer asli di bawah try/except, dan meneruskan data yang disalin ke rutinitas sistem. |
| Output mode pengguna | Semua | Menunjuk ke buffer mode pengguna asli. | Nomor. Harus menulis di bawah coba/kecuali. | Nomor. Harus mengalokasikan memori kernel, meneruskan memori kernel ke rutinitas sistem, dan menyalin hasilnya kembali ke buffer asli di bawah try/except. |
| Input dan output mode kernel | Semua | Menunjuk ke buffer mode kernel asli. | Ya | Ya |
Untuk informasi selengkapnya tentang rutinitas RegistryCallback dan driver filter registri, lihat Memfilter Panggilan Registri.
RegistryCallback dijalankan di IRQL = PASSIVE_LEVEL dan dalam konteks utas yang melakukan operasi registri.
Contoh
Untuk menentukan rutinitas panggilan balik RegistryCallback , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas 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 RegistryCallback yang diberi nama MyRegistryCallback, gunakan jenis EX_CALLBACK_FUNCTION seperti yang ditunjukkan dalam contoh kode ini:
EX_CALLBACK_FUNCTION MyRegistryCallback;
Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:
_Use_decl_annotations_
NTSTATUS
MyRegistryCallback(
PVOID CallbackContext,
PVOID Argument1,
PVOID Argument2
)
{
// Function body
}
Jenis fungsi EX_CALLBACK_FUNCTION didefinisikan 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 EX_CALLBACK_FUNCTION 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 | Didukung dimulai dengan Windows XP (lihat bagian Nilai Hasil). |
| Target Platform | Desktop |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Dipanggil di PASSIVE_LEVEL (lihat bagian Keterangan). |