Fungsi NdisRegisterProtocol (ndis.h)

Artikel
08/07/2023

Catatan NDIS 5. x telah ditolak dan digantikan oleh NDIS 6. x. Untuk pengembangan driver NDIS baru, lihat Driver Jaringan Yang Dimulai dengan Windows Vista. Untuk informasi tentang port NDIS 5. x driver ke NDIS 6. x, lihat Memindahkan Driver NDIS 5.x ke NDIS 6.0.

NdisRegisterProtocol mendaftarkan titik entri ProtocolXxx driver NDIS dan nama dengan pustaka NDIS saat driver menginisialisasi.

Sintaks

void NdisRegisterProtocol(
  [out] PNDIS_STATUS                   Status,
  [out] PNDIS_HANDLE                   NdisProtocolHandle,
  [in]  PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
  [in]  UINT                           CharacteristicsLength
);

Parameter

[out] Status

Penunjuk ke variabel yang disediakan penelepon yang bisa menjadi salah satu nilai berikut saat dikembalikan dari fungsi ini:

NDIS_STATUS_SUCCESS
Pustaka NDIS mendaftarkan penelepon sebagai driver protokol.
NDIS_STATUS_BAD_CHARACTERISTICS
CharacteristicsLength terlalu kecil untuk MajorNdisVersion yang ditentukan dalam buffer di ProtocolCharacteristics.
NDIS_STATUS_BAD_VERSION
MajorNdisVersion yang ditentukan dalam buffer di ProtocolCharacteristics tidak valid.
NDIS_STATUS_RESOURCES
Kekurangan sumber daya, mungkin memori, mencegah pustaka NDIS mendaftarkan pemanggil.

[out] NdisProtocolHandle

Penunjuk ke variabel yang disediakan penelepon di mana fungsi ini mengembalikan handel yang mewakili driver terdaftar.

[in] ProtocolCharacteristics

Penunjuk ke struktur NDIS_PROTOCOL_CHARACTERISTICS yang disiapkan oleh pemanggil. Struktur di ProtocolCharacteristics didefinisikan sebagai berikut:

        typedef struct _NDIS_PROTOCOL_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            OPEN_ADAPTER_COMPLETE_HANDLER OpenAdapterCompleteHandler;
            CLOSE_ADAPTER_COMPLETE_HANDLER CloseAdapterCompleteHandler;
            SEND_COMPLETE_HANDLER SendCompleteHandler;
            TRANSFER_DATA_COMPLETE_HANDLER TransferDataCompleteHandler;
            RESET_COMPLETE_HANDLER ResetCompleteHandler;
            REQUEST_COMPLETE_HANDLER RequestCompleteHandler;
            RECEIVE_HANDLER ReceiveHandler;
            RECEIVE_COMPLETE_HANDLER ReceiveCompleteHandler;
            STATUS_HANDLER StatusHandler;
            STATUS_COMPLETE_HANDLER StatusCompleteHandler;
            NDIS_STRING Name;
        //
        // MajorNdisVersion must be set to 0x04 or 0x05
        // with any of the following members.
        //
            RECEIVE_PACKET_HANDLER ReceivePacketHandler;
            BIND_HANDLER BindAdapterHandler;
            UNBIND_HANDLER UnbindAdapterHandler;
            PNP_EVENT_HANDLER PnPEventHandler;
            UNLOAD_PROTOCOL_HANDLER UnloadHandler;
        //
        // MajorNdisVersion must be set to 0x05 
        // with any of the following members.
        //
            CO_SEND_COMPLETE_HANDLER CoSendCompleteHandler;
            CO_STATUS_HANDLER CoStatusHandler;
            CO_RECEIVE_PACKET_HANDLER CoReceivePacketHandler;
            CO_AF_REGISTER_NOTIFY_HANDLER CoAfRegisterNotifyHandler;
        } NDIS_PROTOCOL_CHARACTERISTICS, *PNDIS_PROTOCOL_CHARACTERISTICS;

Driver harus menginisialisasi struktur ini dengan nol sebelum menyiapkan anggota berikut:

MajorNdisVersion
Menentukan versi utama pustaka NDIS yang digunakan driver. Nilai saat ini 0x05, meskipun pustaka NDIS terus mendukung driver yang ada yang dikembangkan untuk NDIS V4.0. NDIS tidak lagi mendukung protokol V3.0.
MinorNdisVersion
Menentukan versi NDIS minor. Nilai saat ini adalah 0x00.
Dicadangkan
Anggota ini dicadangkan untuk penggunaan sistem.
OpenAdapterCompleteHandler
Menentukan titik masuk fungsi ProtocolOpenAdapterComplete pemanggil.
CloseAdapterCompleteHandler
Menentukan titik masuk fungsi ProtocolCloseAdapterComplete penelepon .
SendCompleteHandler
Menentukan titik masuk fungsi ProtocolSendComplete penelepon , jika ada.
TransferDataCompleteHandler
Menentukan titik masuk fungsi ProtocolTransferDataComplete penelepon, jika ada.
ResetCompleteHandler
Menentukan titik masuk fungsi ProtocolResetComplete penelepon.
RequestCompleteHandler
Menentukan titik masuk fungsi ProtocolRequestComplete penelepon.
ReceiveHandler
Menentukan titik masuk fungsi ProtocolReceive penelepon, jika ada.
ReceiveCompleteHandler
Menentukan titik masuk fungsi ProtocolReceiveComplete penelepon.
StatusHandler
Menentukan titik masuk fungsi ProtocolStatus penelepon, jika ada.
StatusCompleteHandler
Menentukan titik masuk fungsi ProtocolStatusComplete penelepon .
Nama
Jenis NDIS_STRING yang berisi string terhitung yang diinisialisasi pemanggil, dalam set karakter default sistem, menamai driver. Untuk driver Windows 2000 dan yang lebih baru, string ini berisi karakter Unicode. Artinya, untuk Windows 2000 dan yang lebih baru, NDIS mendefinisikan jenis NDIS_STRING sebagai jenis UNICODE_STRING . String ini harus cocok dengan yang ditentukan dalam registri (di bawah Layanan) ketika protokol diinstal.

NdisRegisterProtocol mengonversi string yang disediakan ke huruf besar, sehingga penulis driver protokol tidak dapat berasumsi bahwa mengubah kasus nama protokol yang sudah terdaftar membuat nama unik untuk driver.
ReceivePacketHandler
Menentukan titik masuk fungsi ProtocolReceivePacket penelepon, jika ada, atau NULL. Protokol yang mengikat driver NIC apa pun yang mendukung indikasi penerimaan multipaket harus menyediakan fungsi ProtocolReceivePacket untuk meningkatkan performanya. Namun, protokol yang mengikat dirinya sendiri secara eksklusif ke miniport berorientasi koneksi juga dapat mengatur anggota ini ke NULL.
BindAdapterHandler
Menentukan titik masuk fungsi ProtocolBindAdapter penelepon. Pemanggil yang mengatur nilai di anggota MajorNdisVersion ke 0x05 atau 0x04 harus menyediakan fungsi ProtocolBindAdapter dan mendukung Plug and Play. Driver perantara NDIS juga harus menyediakan fungsi ProtocolBindAdapter , yang memungkinkan driver perantara tersebut memanggil NdisIMRegisterLayeredMiniport dan untuk menunda inisialisasi driver penuh sampai driver NIC yang mendasar telah diinisialisasi.
UnbindAdapterHandler
Menentukan titik masuk fungsi ProtocolUnbindAdapter penelepon. Driver NDIS yang menyediakan fungsi ProtocolBindAdapter juga harus menyediakan fungsi ProtocolUnbindAdapter .
PnPEventHandler
Menentukan titik masuk fungsi ProtocolPnPEvent pemanggil, jika ada.
UnloadHandler
Menentukan titik masuk fungsi ProtocolUnbind penelepon, jika ada, atau NULL.
CoSendCompleteHandler
Menentukan titik masuk fungsi ProtocolCoSendComplete penelepon, yang harus disuplai oleh klien berorientasi koneksi atau manajer panggilan. Klien berorientasi koneksi memasok fungsi ProtocolSendComplete jika juga mengikat dirinya ke miniport tanpa koneksi.
CoStatusHandlerCoStatusHandler
Menentukan titik masuk fungsi ProtocolCoStatus penelepon, yang harus disuplai oleh klien berorientasi koneksi atau manajer panggilan. Klien berorientasi koneksi memasok fungsi ProtocolStatus jika juga mengikat dirinya ke miniport tanpa koneksi.
CoReceivePacketHandler
Menentukan titik masuk fungsi ProtocolCoReceivePacket penelepon, yang harus disuplai oleh klien berorientasi koneksi atau manajer panggilan. Klien berorientasi koneksi menyediakan fungsi ProtocolReceivePacket dan/atau fungsi ProtocolReceive dan ProtocolTransferDataComplete jika juga mengikat dirinya sendiri ke miniport tanpa koneksi.
CoAfRegisterNotifyHandler
Menentukan titik masuk fungsi ProtocolAfRegisterNotify penelepon, yang harus disuplai klien berorientasi koneksi.

[in] CharacteristicsLength

Menentukan ukuran dalam byte struktur di ProtocolCharacteristics. Jika direktif build -DNDIS50=1 atau -DNDIS40=1 ditentukan dalam file sumber di depan #includeNdis.h , sizeof(NDIS_PROTOCOL_CHARACTERISTICS) secara otomatis diatur ke nilai yang sesuai. Jika tidak ada arahan yang ditentukan, NDIS mengasumsikan struktur karakteristik V3.0 sedang digunakan.

Nilai yang ditetapkan dalam anggota MajorNdisVersion dan MinorNdisVersion dari struktur karakteristik harus konsisten dengan arahan build, atau masing-masing harus 0x03 dan 0x00.

Mengembalikan nilai

Tidak ada

Keterangan

Driver protokol harus menentukan MajorNdisVersion 0x05 (versi saat ini) atau 0x04. NDIS tidak lagi mendukung protokol V.30 dan oleh karena itu tidak memuat protokol yang menentukan MajorNdisVersion 0x03.

Semua protokol harus berkemampuan Plug and Play (PnP). Oleh karena itu, protokol harus menentukan titik masuk untuk BindAdapterHandler dan UnbindAdapterHandler. NDIS tidak memuat protokol yang menentukan NULL untuk handler ini.

Untuk performa terbaik, protokol apa pun yang akan melapisi dirinya sendiri di atas driver NIC tanpa koneksi yang mendukung penerimaan multipaket harus menyediakan fungsi ProtocolReceivePacket . Driver protokol seperti itu juga harus menyediakan fungsi ProtocolReceive . Setiap driver NIC tanpa koneksi yang mendukung pengiriman multipaket juga cenderung menunjukkan penerimaan multipaket.

Semua protokol berorientasi koneksi, baik klien atau manajer panggilan, harus mendaftarkan fungsi ProtocolCoReceivePacket . Protokol klien yang juga mengikat diri mereka ke driver NIC tanpa koneksi juga menyediakan fungsi ProtocolReceivePacket dan ProtocolReceive . Protokol berorientasi koneksi harus mendaftarkan titik masuk berorientasi koneksi tambahan dengan NDIS dengan memanggil NdisClOpenAddressFamily untuk klien atau NdisCmRegisterAddressFamily untuk manajer panggilan dari fungsi ProtocolBindAdapter mereka.

Setelah panggilan berhasil ke NdisRegisterProtocol, driver tidak dapat mengubah kumpulan fungsi ProtocolXxx yang disediakannya.

Driver yang berhasil didaftarkan harus menyimpan handel yang dikembalikan di NdisProtocolHandle. Ini adalah parameter yang diperlukan untuk fungsi NdisXxx lain yang kemudian dipanggil driver.

Setelah panggilan berhasil ke NdisRegisterProtocol, fungsi DriverEntry dari protokol yang sadar PnP atau berorientasi koneksi mengembalikan kontrol karena fungsi ProtocolBindAdapter driver tersebut akan dipanggil kemudian satu atau beberapa kali untuk menyiapkan pengikatan ke NIC yang mendasar. Jika tidak, driver protokol dapat memanggil NdisOpenAdapter untuk menyiapkan pengikatan ke driver NIC yang mendasar atau untuk melapisi dirinya sendiri di atas driver NDIS apa pun yang mendaftarkan serangkaian fungsi NDIS MiniportXxx .

Platform target: Universal
Versi: Tidak didukung untuk driver NDIS 6.0 di Windows Vista. Gunakan NdisRegisterProtocolDriversebagai gantinya. Didukung untuk driver NDIS 5.1 di Windows Vista dan Windows XP.

Persyaratan

Persyaratan	Nilai
Header	ndis.h (termasuk Ndis.h)
Pustaka	Ndis.lib
IRQL	PASSIVE_LEVEL

Share via