PROTOCOL_BIND_ADAPTER_EX fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

NDIS memanggil fungsi ProtocolBindAdapterEx driver protokol untuk meminta driver mengikat adaptor miniport.

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

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
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx berhasil menyelesaikan pengikatan ke adaptor miniport yang mendasar.
NDIS_STATUS_PENDING	ProtocolBindAdapterEx tidak menyelesaikan operasi pengikatan dan operasi akan diselesaikan secara asinkron. Driver protokol harus memanggil Fungsi NdisCompleteBindAdapterEx saat operasi selesai.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx tidak dapat mengalokasikan sumber daya yang diperlukan driver untuk melakukan operasi I/O jaringan.
NDIS_STATUS_XXX atau NTSTATUS_XXX	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