SET_OPTIONS fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

NDIS memanggil fungsi XxxSetOptions driver untuk memungkinkan driver mendaftarkan layanan opsional. Fungsi ini didefinisikan sebagai MiniportSetOptions untuk driver miniport, ProtocolSetOptions untuk driver protokol, atau FilterSetOptions untuk driver filter.

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

Sintaks

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

Parameter

[in] NdisDriverHandle

Handel yang mengidentifikasi driver. NDIS mengembalikan handel ini ke driver saat kembali dari fungsi pendaftaran driver ( NdisMRegisterMiniportDriver untuk driver miniport, NdisRegisterProtocolDriver untuk driver protokol, dan NdisFRegisterFilterDriver untuk driver filter).

[in] DriverContext

Handel yang diteruskan driver ke NdisRegisterXxxDriver yang mengidentifikasi area konteks driver, di mana Xxx adalah jenis driver (Miniport, Protocol, atau Filter).

Nilai kembali

XxxSetOptions mengembalikan salah satu nilai status berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	XxxSetOptions berhasil mendaftarkan layanan dan sumber daya opsional driver.
NDIS_STATUS_RESOURCES	XxxSetOptions tidak dapat mengalokasikan sumber daya yang diperlukan driver.
NDIS_STATUS_XXX atau NTSTATUS_XXX	Upaya pengandar untuk mendaftarkan opsi gagal. Biasanya, status kesalahan seperti itu disebarluaskan dari fungsi NdisXxx atau rutinitas dukungan mode kernel.

Keterangan

XxxSetOptions adalah fungsi opsional. NDIS memanggil XxxSetOptions dalam konteks panggilan driver ke Fungsi NdisRegisterXxxDriver , di mana Xxx adalah jenis driver (Miniport, Protocol, atau Filter).

XxxSetOptions mendaftarkan layanan opsional dan dapat mengalokasikan sumber daya driver lainnya. Untuk mendaftarkan fungsi MiniportXxx, ProtocolXxx, atau FilterXxx opsional, driver memanggil fungsi NdisSetOptionalHandlers . Driver melewati handel dari parameter NdisDriverHandle pada parameter NdisHandle dari NdisSetOptionalHandlers dan meneruskan struktur karakteristik pada parameter OptionalHandlers .

Driver Miniport dapat berlaku untuk layanan opsional yang ditentukan dalam struktur karakteristik berikut:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(lihat dokumentasi offload cerobong asap NDIS 6.0 TCP)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(lihat dokumentasi offload cerobong asap TCP NDIS 6.0)

Driver protokol dapat berlaku untuk layanan opsional yang ditentukan dalam struktur karakteristik berikut:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

Tidak ada layanan pengandar filter opsional dalam versi Windows saat ini.

NDIS dapat memanggil fungsi MiniportXxx, ProtocolXxx, atau FilterXxx lainnya dari driver kapan saja setelah XxxSetOptions kembali. Driver harus siap untuk dipanggil kembali pada fungsi inisialisasinya:(MiniportInitializeEx untuk driver miniport, ProtocolBindAdapterEx untuk driver protokol, dan FilterAttach untuk driver filter).

Untuk driver miniport, adaptor miniport berada dalam status Dihentikan sebelum NDIS memanggil MiniportInitializeEx. Untuk driver protokol, pengikatan protokol berada dalam status Tidak Terikat sebelum NDIS memanggil ProtocolBindAdapterEx. Untuk driver filter, modul filter berada dalam status Terlepas sebelum NDIS memanggil FilterAttach.

Jika upaya untuk mengalokasikan sumber daya atau layanan gagal, XxxSetOptions harus membatalkan semua alokasi yang berhasil sebelum mengembalikan kontrol dengan status selain NDIS_STATUS_SUCCESS.

XxxDriverUnload miniport dan driver filter harus membatalkan semua operasi yang dilakukan di XxxSetOptions

NDIS memanggil XxxSetOptions di IRQL = PASSIVE_LEVEL.

Contoh

Untuk menentukan fungsi XxxSetOptions , 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.

Dalam file header Ndis.h, fungsi panggilan balik SET_OPTIONS didefinisikan lebih lanjut sebagai berikut:

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

Ini memungkinkan semua driver NDIS untuk mengimplementasikan fungsi panggilan balik XxxSetOptions mereka dengan sintaks yang sama. Driver Miniport menggunakan jenis MINIPORT_SET_OPTIONS , driver protokol menggunakan jenis PROTOCOL_SET_OPTIONS , dan driver filter menggunakan jenis FILTER_SET_OPTIONS .

Misalnya, untuk menentukan fungsi MiniportSetOptions yang diberi nama "MySetOptions", gunakan jenis MINIPORT_SET_OPTIONS seperti yang ditunjukkan dalam contoh kode ini:

MINIPORT_SET_OPTIONS MySetOptions;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

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