PROTOCOL_NET_PNP_EVENT fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

NDIS memanggil fungsi ProtocolNetPnPEvent untuk menunjukkan peristiwa Plug and Play jaringan, peristiwa PnP NDIS, atau peristiwa manajemen daya ke driver protokol.

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

Sintaks

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

Parameter

[in] ProtocolBindingContext

Handel ke area konteks yang dialokasikan oleh driver protokol tempat driver ini mempertahankan informasi status run-time per pengikatan. Driver protokol menyediakan handel ini ketika disebut fungsi NdisOpenAdapterEx . Peristiwa NetEventXxx yang ditunjukkan dengan PROTOKOL NULLBindingContext berlaku untuk semua pengikatan. NetEventBindList dan NetEventBindsComplete selalu ditunjukkan dengan PROTOKOL NULLBindingContext. NetEventReconfigure dapat ditunjukkan dengan ProtocolBindingContext tertentu atau dengan PROTOKOL NULLBindingContext.

[in] NetPnPEventNotification

Penunjuk ke NET_PNP_EVENT_NOTIFICATION struktur yang menjelaskan peristiwa Plug and Play atau peristiwa Power Management yang diindikasikan NDIS ke driver protokol.

Nilai kembali

ProtocolNetPnPEvent dapat mengembalikan salah satu hal berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	Driver protokol berhasil menangani peristiwa Plug and Play jaringan yang ditunjukkan, peristiwa PnP NDIS, atau peristiwa manajemen daya. Arti dari kode status ini tergantung pada kode NetEvent dalam buffered NET_PNP_EVENT_NOTIFICATION struktur di NetPnPEvent: NetEventSetPower Driver protokol telah melakukan tindakan khusus driver yang diperlukan untuk mempersiapkan transisi perangkat ke status daya perangkat yang diminta. NetEventQueryPower Adaptor yang mendasar dapat beralih ke status daya perangkat yang diminta. NetEventQueryRemoveDevice Adaptor yang mendasar dapat dihapus. NetEventCancelRemoveDevice Driver protokol telah melakukan tindakan khusus driver yang diperlukan untuk mempersiapkan penghapusan adaptor yang mendasar yang dibatalkan. NetEventReconfigure Driver protokol telah menerima konfigurasi yang diubah. NetEventBindList Driver protokol memiliki daftar ikatan baru dan telah melakukan pemrosesan terkait. NetEventBindsComplete Driver protokol telah mengakui indikasi dari NDIS bahwa driver protokol terikat ke semua adaptor yang mendasar yang tersedia. NetEventPnPCapabilities Driver protokol telah mengakui bahwa ia telah menerima kemampuan bangun saat ini dari adaptor yang mendasar yang terkait dengan pengikatan yang ditentukan. NetEventPause Pengikatan protokol yang ditentukan telah memasuki status Jeda . Pengikatan akan memasuki status Dijeda setelah NDIS menyelesaikan semua permintaan pengiriman yang beredar untuk pengikatan. Untuk informasi selengkapnya tentang operasi jeda, lihat Menjeda Pengikatan. NetEventRestart Pengikatan protokol yang ditentukan telah memasuki status Memulai Ulang . Setelah driver protokol siap untuk melanjutkan operasi kirim dan terima untuk pengikatan, pengikatan memasuki status Berjalan . NetEventPortActivation Driver protokol telah mengakui aktivasi port yang terkait dengan pengikatan yang ditentukan. Untuk informasi selengkapnya tentang aktivasi port, lihat Mengaktifkan Port NDIS. NetEventPortDeactivation Driver protokol telah mengakui aktivasi port yang terkait dengan pengikatan yang ditentukan.
NDIS_STATUS_PENDING	Driver protokol akan mengembalikan responsnya ke peristiwa yang ditunjukkan secara asinkron dengan panggilan ke Fungsi NdisCompleteNetPnPEvent .
NDIS_STATUS_RESOURCES	Driver protokol tidak dapat memperoleh sumber daya sistem yang diperlukan untuk memenuhi peristiwa Plug and Play atau Power Management yang ditunjukkan.
NDIS_STATUS_NOT_SUPPORTED	Driver protokol NDIS 6.0 dan yang lebih baru tidak boleh mengembalikan status ini. Sebuah NDIS 5. driver protokol x yang tidak mendukung Plug and Play dapat mengembalikan status ini sebagai respons terhadap NetEventSetPower untuk menunjukkan bahwa NDIS harus membatalkan ikatannya dari adaptor yang mendasar.
NDIS_STATUS_FAILURE	Driver protokol gagal pada peristiwa yang ditunjukkan karena alasan selain yang dinyatakan dalam daftar sebelumnya.

Driver protokol dapat menggagalkan peristiwa NetEventQueryRemoveDevice dan NetEventPortActivation .

Jika driver protokol gagal dalam peristiwa NetEventPortActivation , driver tersebut tidak boleh menggunakan port terkait dalam operasi berikutnya.

Driver protokol harus selalu berhasil peristiwa NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation, dan NetEventPnPCapabilities dengan mengembalikan NDIS_STATUS_SUCCESS.

Keterangan

Fungsi ProtocolNetPnPEvent diperlukan dalam driver protokol untuk mendukung Plug and Play dan Power Management. NDIS memanggil ProtocolNetPnPEvent untuk memberi tahu driver protokol bahwa peristiwa Plug and Play jaringan, peristiwa PnP NDIS, atau peristiwa Power Management telah terjadi.

The NET_PNP_EVENT_NOTIFICATION struktur yang diteruskan ke ProtocolNetPnPEvent menjelaskan peristiwa tersebut. ProtocolNetPnPEvent menginterpretasikan dua bagian dasar informasi dalam struktur NET_PNP_EVENT_NOTIFICATION:

Kode di anggota NetEvent yang mengidentifikasi jenis peristiwa Plug and Play atau Power Management.
Informasi khusus peristiwa. Misalnya, dengan peristiwa NetEventSetPower , anggota Buffer berisi status daya perangkat tempat perangkat bertransisi.

Driver protokol harus menyimpan penunjuk NetPnPEvent . Pointer ini adalah parameter input yang diperlukan untuk fungsi NdisCompleteNetPnPEvent , yang kemudian harus dipanggil driver protokol jika ProtocolNetPnPEvent mengembalikan NDIS_STATUS_PENDING.

Driver protokol harus selalu berhasil dalam peristiwa NetEventQueryPower . Setelah membuat koneksi aktif, driver protokol dapat memanggil fungsi PoRegisterSystemState untuk mendaftarkan status yang terus sibuk. Selama pendaftaran status berlaku, manajer daya tidak mencoba untuk membuat sistem tidur. Setelah koneksi menjadi tidak aktif, driver protokol membatalkan pendaftaran status dengan memanggil fungsi PoUnregisterSystemState . Driver protokol tidak boleh mencoba mencegah sistem beralih ke status tidur dengan gagal dalam peristiwa NetEventQueryPower . Perhatikan bahwa peristiwa NetEventQueryPower selalu diikuti oleh peristiwa NetEventSetPower . Peristiwa NetEventSetPower yang menentukan status daya perangkat saat ini yang mendasar yang berlaku membatalkan peristiwa NetEventQueryPower .

Jika driver protokol tidak dapat merilis perangkat (misalnya, karena perangkat sedang digunakan) itu harus gagal peristiwa NetEventQueryRemoveDevice dengan mengembalikan NDIS_STATUS_FAILURE.

Driver protokol harus selalu berhasil NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause, atau NetEventPortDeactivation dengan mengembalikan NDIS_STATUS_SUCCESS.

Saat menangani NetEventReconfigure atau NetEventBindList, driver protokol harus memvalidasi data yang terkait dengan peristiwa tersebut. Untuk informasi selengkapnya tentang data tersebut, lihat NET_PNP_EVENT_NOTIFICATION.

NDIS memanggil ProtocolNetPnPEvent di IRQL = PASSIVE_LEVEL.

Contoh

Untuk menentukan fungsi ProtocolNetPnPEvent , 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 ProtocolNetPnPEvent yang diberi nama "MyNetPnPEvent", gunakan jenis PROTOCOL_NET_PNP_EVENT seperti yang ditunjukkan dalam contoh kode ini:

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

Jenis fungsi PROTOCOL_NET_PNP_EVENT 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 PROTOCOL_NET_PNP_EVENT 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