FILTER_ATTACH fungsi panggilan balik (ndis.h)

Artikel
03/08/2023

NDIS memanggil fungsi FilterAttach driver filter untuk mengalokasikan dan menginisialisasi struktur data modul filter.

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

Sintaks

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Parameter

[in] NdisFilterHandle

Handel NDIS yang mengidentifikasi modul filter. Pengandar filter harus menyimpan handel ini. Handel diperlukan dalam panggilan berikutnya ke fungsi NdisFXxx .

[in] FilterDriverContext

Handel yang diteruskan driver ke Fungsi NdisFRegisterFilterDriver yang mengidentifikasi area konteks driver.

[in] AttachParameters

Penunjuk ke NDIS_FILTER_ATTACH_PARAMETERS struktur yang menentukan parameter inisialisasi untuk modul filter.

Mengembalikan nilai

FilterAttach mengembalikan salah satu nilai status berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	FilterAttach berhasil dialokasikan dan menginisialisasi struktur data untuk modul filter ini.
NDIS_STATUS_RESOURCES	FilterAttach gagal karena sumber daya yang tidak mencukup.
NDIS_STATUS_FAILURE	FilterAttach mengembalikan NDIS_STATUS_FAILURE jika tidak ada nilai sebelumnya yang berlaku. Driver filter harus memanggil fungsi NdisWriteEventLogEntry bersama dengan parameter yang menentukan alasan kegagalan.

Keterangan

FilterAttach adalah fungsi yang diperlukan. NDIS memanggil fungsi FilterAttach driver filter saat modul filter yang ditentukan dalam status Dilepas . NDIS dapat memanggil FilterAttach kapan saja setelah panggilan ke fungsi FilterSetOptions kembali.

Pada awal eksekusi di FilterAttach, modul filter memasuki status Melampirkan .

Driver filter harus menghindari penerbitan kueri OID yang tidak perlu. Sebagai gantinya, gunakan informasi di NDIS_FILTER_ATTACH_PARAMETERS, jika tersedia, untuk mendapatkan informasi tentang driver yang mendasar.

Driver filter melakukan operasi berikut saat NDIS memanggil FilterAttach.

Membuat area konteks untuk modul filter dan mengalokasikan kumpulan buffer dan sumber daya lainnya.
Memanggil fungsi NdisFSetAttributes bersama dengan NdisFilterHandle yang diteruskan NDIS ke FilterAttach. Parameter FilterModuleContextdari NdisFSetAttributes menentukan area konteks driver filter untuk modul filter ini. NDIS meneruskan area konteks ini ke fungsi FilterXxx driver filter.
Secara opsional membaca parameter konfigurasi dari registri.
Jika operasi sebelumnya berhasil diselesaikan, modul filter memasuki status Dijeda .
Jika operasi sebelumnya gagal, driver filter harus merilis sumber daya apa pun yang dialokasikan dalam fungsi FilterAttach dan mengembalikan modul filter ke status Dilepas .
Mengembalikan NDIS_STATUS_SUCCESS atau kode kegagalan yang sesuai.

Driver filter tidak boleh membuat permintaan pengiriman, menunjukkan data yang diterima, membuat permintaan OID, atau membuat indikasi status dari status Melampirkan .

NDIS memanggil fungsi FilterDetach driver filter untuk merilis semua sumber daya yang terkait dengan modul filter dan mengembalikan modul filter ke status Dilepas .

NDIS memanggil FilterAttach di IRQL = PASSIVE_LEVEL.

Contoh

Untuk menentukan fungsi FilterAttach , Anda harus terlebih dahulu memberikan 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 FilterAttach yang diberi nama "MyAttach", gunakan jenis FILTER_ATTACH seperti yang ditunjukkan dalam contoh kode ini:

FILTER_ATTACH MyAttach;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

Jenis fungsi FILTER_ATTACH ditentukan 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_ATTACH 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