PROTOCOL_BIND_ADAPTER_EX fungsi panggilan balik (ndis.h)
NDIS memanggil fungsi ProtocolBindAdapterEx driver protokol untuk meminta driver mengikat adaptor miniport.
Sintaks
PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;
NDIS_STATUS ProtocolBindAdapterEx(
[in] NDIS_HANDLE ProtocolDriverContext,
[in] NDIS_HANDLE BindContext,
[in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}
Parameter
[in] ProtocolDriverContext
Handel ke area konteks yang dialokasikan driver tempat driver mempertahankan informasi status dan konfigurasi. Driver protokol meneruskan area konteks ini ke Fungsi NdisRegisterProtocolDriver .
[in] BindContext
Handel yang mengidentifikasi area konteks NDIS untuk operasi pengikatan ini.
[in] BindParameters
Penunjuk ke struktur NDIS_BIND_PARAMETERS yang dibuat NDIS.
Nilai kembali
ProtocolBindAdapterEx mengembalikan salah satu nilai status berikut:
| Menampilkan kode | Deskripsi |
|---|---|
|
ProtocolBindAdapterEx berhasil menyelesaikan pengikatan ke adaptor miniport yang mendasar. |
|
ProtocolBindAdapterEx tidak menyelesaikan operasi pengikatan dan operasi akan diselesaikan secara asinkron. Driver protokol harus memanggil Fungsi NdisCompleteBindAdapterEx saat operasi selesai. |
|
ProtocolBindAdapterEx tidak dapat mengalokasikan sumber daya yang diperlukan driver untuk melakukan operasi I/O jaringan. |
|
Upaya driver protokol untuk mengatur pengikatan gagal. Biasanya, status kesalahan seperti itu disebarluaskan dari fungsi NdisXxx atau rutinitas dukungan mode kernel. |
Keterangan
ProtocolBindAdapterEx adalah fungsi yang diperlukan. NDIS memanggil ProtocolBindAdapterEx untuk melakukan operasi pengikatan setiap kali adaptor miniport yang mendasar, yang dapat diikat driver protokol, menjadi tersedia.
ProtocolBindAdapterEx mengalokasikan memori yang cukup untuk mempertahankan informasi konteks pengikatan dan memanggil fungsi NdisOpenAdapterEx untuk mengikat dirinya sendiri ke adaptor miniport yang mendasar. ProtocolBindAdapterEx meneruskan penunjuk ke informasi konteks pengikatan pada parameter ProtocolBindingContext dari NdisOpenAdapterEx. ProtocolBindAdapterEx meneruskan nilai pada anggota AdapterName dari parameter BindParameters sebagai anggota AdapterName dari parameter OpenParametersNdisOpenAdapterEx.
Sebelum driver memanggil NdisOpenAdapterEx, driver dapat meneruskan pointer di BindParameters ke fungsi NdisOpenConfigurationEx untuk membaca parameter konfigurasi yang terkait dengan adaptor miniport.
Setelah berhasil membuka adaptor miniport, driver dapat meneruskan handel dari parameter NdisHandledari NdisOpenAdapterEx ke NdisOpenConfigurationEx untuk mendapatkan handel ke lokasi registri tempat parameter konfigurasi untuk pengikatan protokol disimpan.
ProtocolBindAdapterEx meneruskan NdisOpenAdapterEx penunjuk ke array nilai jenis menengah yang mencantumkan jenis media yang dapat didukung driver protokol. Daftar ini adalah subset dari jenis NDIS_MEDIUM . NDIS menunjukkan jenis sedang yang dipilih pada parameter SelectedMediumIndex struktur di OpenParameters.
Jika NdisOpenAdapterEx mengembalikan status kesalahan, ProtocolBindAdapterEx mengembalikan status kesalahan tersebut, merilis sumber daya per pengikatan apa pun yang dialokasikan driver protokol, dan segera mengembalikan kontrol.
Jika NdisOpenAdapterEx mengembalikan NDIS_STATUS_SUCCESS, ProtocolBindAdapterEx dapat mengalokasikan sumber daya yang tersisa yang dibutuhkan driver protokol untuk melakukan I/O jaringan pada pengikatan. Driver juga dapat mengonfigurasi informasi konteks khusus pengikatan yang digunakan driver untuk melacak operasi I/O jaringan.
Jika NdisOpenAdapterEx mengembalikan NDIS_STATUS_PENDING, NDIS akan memanggil driver protokol Fungsi ProtocolOpenAdapterCompleteEx setelah operasi terbuka selesai. ProtocolOpenAdapterCompleteEx dapat menyelesaikan operasi pengikatan. ProtocolBindAdapterEx dapat menyimpan handel BindContext di area konteks pengikatan. NDIS meneruskan ProtocolBindingContext sebagai parameter input ke fungsi ProtocolOpenAdapterCompleteEx driver.
Jika NdisOpenAdapterEx mengembalikan NDIS_STATUS_PENDING, NDIS menetapkan anggota SelectedMediumIndex dari struktur pada parameter OpenParameters dan nilai parameter NdisBindingHandle setelah NdisOpenAdapterEx kembali. NDIS menetapkan nilai-nilai ini sebelum memanggil ProtocolOpenAdapterCompleteEx. Oleh karena itu, driver protokol harus menyimpan struktur parameter terbuka, dan handel pengikatan protokol di area konteks di ProtocolBindingContext(atau lokasi apa pun yang valid sampai NDIS memanggil ProtocolOpenAdapterCompleteEx).
Driver protokol tidak dapat membuat permintaan OID pada pengikatan hingga operasi terbuka selesai. Karena pengikatan dalam status dijeda setelah operasi terbuka selesai, driver protokol tidak dapat membuat permintaan pengiriman sampai setelah NDIS memulai ulang pengikatan.
Setelah operasi terbuka selesai, ProtocolBindAdapterEx dapat mengembalikan NDIS_STATUS_SUCCESS untuk menyelesaikan operasi pengikatan. ProtocolBindAdapterEx dapat mengembalikan NDIS_STATUS_PENDING untuk menugaskan penyelesaian operasi pengikatan ke lain waktu. Jika ProtocolBindAdapterEx mengembalikan NDIS_STATUS_PENDING, driver harus memanggil Fungsi NdisCompleteBindAdapterEx setelah operasi pengikatan selesai.
Driver protokol harus menggunakan struktur NDIS_BIND_PARAMETERS untuk menentukan kemampuan adaptor miniport yang mendasar. Setelah operasi terbuka selesai, tergantung pada media yang mendasar, driver protokol dapat memanggil fungsi NdisOidRequest untuk mengkueri driver miniport (atau NDIS) yang mendasar tentang kemampuan adaptor miniport tambahan. Untuk informasi selengkapnya tentang permintaan OID, lihat Permintaan OID Driver Protokol.
NDIS dapat memanggil driver protokol Fungsi ProtocolReceiveNetBufferLists setelah driver menyiapkan filter paket untuk pengikatan dengan OID_GEN_CURRENT_PACKET_FILTER OID. Jika adaptor miniport yang mendasar tidak menggunakan filter paket untuk paket masuk, indikasi terima diaktifkan setelah operasi terbuka selesai. Driver protokol dapat menerima indikasi status di fungsi ProtocolStatusEx setelah operasi terbuka selesai.
Setiap driver protokol harus mengalokasikan kumpulan struktur NET_BUFFER dan NET_BUFFER_LIST yang memadai . Driver mengalokasikan deskriptor data jaringan dari kumpulan ini untuk operasi pengiriman berikutnya.
Jika ProtocolBindAdapterEx tidak dapat mengalokasikan sumber daya yang diperlukan untuk melakukan operasi I/O jaringan berikutnya, ia harus membebaskan semua sumber daya yang telah dialokasikan, dan mengembalikan nilai kesalahan yang sesuai.
NDIS memanggil driver protokol ProtocolUnbindAdapterEx berfungsi untuk meminta driver untuk membatalkan ikatan dari adaptor miniport yang mendasar.
Jika driver protokol berhasil membuka adaptor miniport tetapi operasi pengikatan gagal (misalnya, sebagai akibat dari permintaan OID yang gagal), driver harus menutup adaptor miniport dari dalam konteks ProtocolBindAdapterEx atau ProtocolUnbindAdapterEx. Misalnya, driver memanggil NdisCloseAdapterEx dari ProtocolBindAdapterEx dan menunggu operasi penutupan selesai sebelum driver kembali dari ProtocolBindAdapterEx. Sebagai alternatif, jika driver mengembalikan NDIS_STATUS_PENDING dari ProtocolBindAdapterEx, driver dapat memanggil fungsi NdisUnbindAdapter dan memanggil NdisCloseAdapterEx dalam fungsi ProtocolUnbindAdapterEx .
NDIS memanggil ProtocolBindAdapterEx di IRQL = PASSIVE_LEVEL.
Contoh
Untuk menentukan fungsi ProtocolBindAdapterEx , 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 ProtocolBindAdapterEx yang diberi nama "MyBindAdapterEx", gunakan jenis PROTOCOL_BIND_ADAPTER_EX seperti yang ditunjukkan dalam contoh kode ini:
PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;
Kemudian, terapkan fungsi Anda sebagai berikut:
_Use_decl_annotations_
NDIS_STATUS
MyBindAdapterEx(
NDIS_HANDLE ProtocolDriverContext,
NDIS_HANDLE BindContext,
PNDIS_BIND_PARAMETERS BindParameters
)
{...}
Jenis fungsi PROTOCOL_BIND_ADAPTER_EX 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 PROTOCOL_BIND_ADAPTER_EX 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 |