RTL_RUN_ONCE_INIT_FN fungsi panggilan balik (ntddk.h)
Rutinitas RunOnceInitialization melakukan operasi inisialisasi satu kali.
Sintaks
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
Parameter
[in, out] RunOnce
Penunjuk ke struktur inisialisasi satu kali RTL_RUN_ONCE yang sebelumnya diteruskan driver sebagai parameter ke rutinitas RtlRunOnceExecuteOnce yang menyebut rutinitas RunOnceInitialization ini.
[in, out] Parameter
Nilai Parameter yang diteruskan driver ke rutinitas RtlRunOnceExecuteOnce yang disebut rutinitas RunOnceInitialization ini.
[out] Context
Penunjuk ke variabel PVOID tempat rutin menulis data inisialisasi.
Nilai kembali
Rutinitas RunOnceInitialization mengembalikan nilai bukan nol untuk menunjukkan keberhasilan, dan mengembalikan nol untuk menunjukkan kegagalan.
Keterangan
Rutinitas RunOnceInitialization yang diterapkan driver melakukan inisialisasi khusus driver lalu menulis data inisialisasi ke lokasi memori yang ditunjuk parameter Konteks . Driver menggunakan rutinitas RtlRunOnceExecuteOnce untuk melakukan panggilan satu kali ke rutinitas RunOnceInitialization . Sistem operasi menjamin bahwa rutinitas RunOnceInitialization tidak dipanggil dua kali untuk nilai yang sama dari parameter RunOnce .
Sejumlah kecil bit berurutan rendah di lokasi yang diacu oleh parameter Konteks dicadangkan untuk digunakan oleh sistem operasi. Rutinitas RunOnceInitialization driver Anda harus mengatur bit yang dipesan ini ke nol dalam nilai output yang ditulisnya ke *Konteks. Konstanta RTL_RUN_ONCE_CTX_RESERVED_BITS yang ditentukan dalam Ntddk.h menentukan jumlah bit berurutan rendah yang dicadangkan. Saat ini, RTL_RUN_ONCE_CTX_RESERVED_BITS didefinisikan menjadi dua, yang berarti bahwa driver harus mengatur dua bit paling tidak signifikan dari nilai PVOID yang ditujukkan oleh Konteks ke nol.
Contoh
Untuk menentukan rutinitas panggilan balik RunOnceInitialization , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. 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 RunOnceInitialization yang diberi nama MyRunOnceInitialization, gunakan jenis RTL_RUN_ONCE_INIT_FN seperti yang ditunjukkan dalam contoh kode ini:
RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;
Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:
_Use_decl_annotations_
ULONG
MyRunOnceInitialization(
PRTL_RUN_ONCE RunOnce,
PVOID Parameter,
PVOID *Context
)
{
// Function body
}
Jenis fungsi RTL_RUN_ONCE_INIT_FN didefinisikan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan _Use_decl_annotations_ anotasi ke definisi fungsi Anda. Anotasi _Use_decl_annotations_ memastikan bahwa anotasi yang diterapkan ke jenis fungsi RTL_RUN_ONCE_INIT_FN 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 Menganotasi Perilaku Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Driver dapat menerapkan rutinitas RunOnceInitialization hanya pada Windows Vista dan versi Windows yang lebih baru. |
| Target Platform | Desktop |
| Header | ntddk.h (termasuk Ntddk.h, Ntifs.h) |
| IRQL | Dipanggil di IRQL <= APC_LEVEL. |