FILTER_RESTART fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

Fungsi FilterRestart memulai operasi hidupkan ulang untuk modul filter yang ditentukan.

Catatan Anda harus mendeklarasikan fungsi dengan menggunakan jenis FILTER_RESTART . Untuk informasi selengkapnya, lihat bagian Contoh berikut ini.

Sintaks

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Parameter

[in] FilterModuleContext

Handel ke area konteks untuk modul filter yang harus dimulai ulang oleh driver filter. Driver filter membuat dan menginisialisasi area konteks ini dalam fungsi FilterAttach .

[in] RestartParameters

Penunjuk ke NDIS_FILTER_RESTART_PARAMETERS struktur yang menentukan parameter hidupkan ulang untuk modul filter.

Nilai kembali

FilterRestart mengembalikan salah satu nilai status berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	FilterRestart berhasil memulai ulang modul filter yang ditentukan.
NDIS_STATUS_PENDING	Driver filter akan menyelesaikan permintaan secara asinkron dengan panggilan ke fungsi NdisFRestartComplete setelah menyelesaikan operasi hidupkan ulang.
NDIS_STATUS_RESOURCES	FilterRestart gagal karena sumber daya yang tidak mencukup.
NDIS_STATUS_FAILURE	Tidak ada nilai status sebelumnya yang berlaku. Driver filter harus memanggil fungsi NdisWriteEventLogEntry bersama dengan parameter yang menentukan alasan kegagalan.

Keterangan

FilterRestart adalah fungsi yang diperlukan untuk driver filter. NDIS dapat memanggil FilterRestart saat modul filter berada dalam status Dijeda . Modul filter memasuki status Menghidupkan ulang pada awal eksekusi FilterRestart.

Saat NDIS memanggil FilterRestart, driver filter:

Harus menyelesaikan operasi yang diperlukan untuk memulai ulang operasi kirim dan terima normal.
Secara opsional membaca atau menulis parameter konfigurasi.
Secara opsional merealokasi kumpulan buffer.
Secara opsional memodifikasi atribut hidupkan ulang yang ditentukan dalam anggota RestartAttributes dari NDIS_FILTER_RESTART_PARAMETERS struktur. Jika penunjuk di RestartAttributes adalah NULL, driver filter tidak boleh mengubah atau menambahkan ke daftar atribut restart. Jika penunjuk di RestartAttributes bukan NULL, penunjuk menunjuk ke struktur NDIS_RESTART_ATTRIBUTES pertama dalam daftar atribut restart. Jika driver filter tidak dimulai ulang, seharusnya tidak mengubah atribut apa pun.
Secara opsional menggunakan permintaan OID untuk mengkueri atau mengatur informasi di driver yang mendasar. Driver filter tidak boleh mengeluarkan permintaan OID untuk informasi yang sudah disediakan dalam daftar atribut restart.
Mengembalikan NDIS_STATUS_SUCCESS atau status kegagalan.

Jika driver filter memodifikasi daftar atribut hidupkan ulang, driver filter:

Tidak boleh memodifikasi atribut khusus media jika tidak mengenali OID di anggota Oid NDIS_RESTART_ATTRIBUTES struktur.
Dapat menambahkan atribut khusus media baru ke daftar atribut hidupkan ulang. Dalam situasi ini, driver filter harus mengalokasikan struktur NDIS_RESTART_ATTRIBUTES baru--misalnya, dengan Fungsi NdisAllocateMemoryWithTagPriority --dan menyediakan ruang memori untuk atribut baru. Setelah menyebarkan atribut hidupkan ulang ke driver yang terlalu berlebihan, NDIS membebaskan memori atribut untuk driver filter.
Dapat mengubah atribut khusus media dalam daftar atribut hidupkan ulang. Jika driver filter membutuhkan lebih banyak ruang memori, itu dapat membebaskan struktur NDIS_RESTART_ATTRIBUTES dengan fungsi NdisFreeMemory dan mengalokasikan struktur baru untuk berisi informasi yang dimodifikasi. Setelah menyebarkan atribut hidupkan ulang ke driver yang terlalu berlebihan, NDIS membebaskan memori atribut untuk driver filter.
Haruskah, jika anggota Oid dalam struktur NDIS_RESTART_ATTRIBUTES OID_GEN_MINIPORT_RESTART_ATTRIBUTES, pastikan bahwa NDIS_RESTART_GENERAL_ATTRIBUTES struktur berisi informasi yang diperlukan driver filter. Untuk memastikan bahwa struktur NDIS_RESTART_GENERAL_ATTRIBUTES berisi informasi yang diperlukan, Anda harus memeriksa anggota Revisi dalam struktur NDIS_OBJECT_HEADER yang ditentukan dalam anggota Header struktur NDIS_RESTART_GENERAL_ATTRIBUTES.
Catatan Driver filter dapat mengubah anggota mana pun dalam struktur NDIS_RESTART_GENERAL_ATTRIBUTES. Jika beberapa atribut yang harus dimodifikasi driver filter tidak disertakan dalam revisi struktur yang disediakan NDIS, driver filter harus mengandalkan driver yang terlalu mengandalkan untuk mengeluarkan permintaan OID untuk atribut yang hilang. Driver filter dapat mengubah atribut ketika menyelesaikan permintaan OID.
Harus, jika driver filter mengubah atribut hidupkan ulang, berikan fungsi FilterOidRequest . Driver filter harus memastikan bahwa informasi yang diterima driver yang terlalu mengandalkan dalam atribut restart konsisten dengan informasi yang mereka terima sebagai respons terhadap permintaan OID.

Setelah driver filter mengembalikan statusnya atau memanggil fungsi NdisFRestartComplete , operasi hidupkan ulang selesai. Jika operasi berhasil diselesaikan, modul filter berada dalam status Berjalan dan pemrosesan kirim dan terima normal dilanjutkan. Jika operasi hidupkan ulang gagal, modul filter kembali ke status Dijeda .

NDIS memanggil FilterRestart di IRQL = PASSIVE_LEVEL.

Contoh

Untuk menentukan fungsi FilterRestart , Anda harus terlebih dahulu menyediakan deklarasi fungsi yang mengidentifikasi jenis fungsi yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi 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 fungsi FilterRestart yang diberi nama "MyRestart", gunakan jenis FILTER_RESTART seperti yang ditunjukkan dalam contoh kode ini:

FILTER_RESTART MyRestart;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

Jenis fungsi FILTER_RESTART didefinisikan dalam file header Ndis.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 FILTER_RESTART dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver NDIS.

Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung di NDIS 6.0 dan yang lebih baru.
Target Platform	Windows
Header	ndis.h (termasuk Ndis.h)
IRQL	PASSIVE_LEVEL