PROTOCOL_CO_OID_REQUEST fungsi panggilan balik (ndis.h)

Artikel
03/08/2023

Fungsi ProtocolCoOidRequest menangani permintaan OID yang dimulai klien CoNDIS atau manajer panggilan mandiri dengan panggilan ke fungsi NdisCoOidRequest atau driver manajer panggilan miniport (MCM) dimulai dengan panggilan ke fungsi NdisMCmOidRequest .

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

Sintaks

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

NDIS_STATUS ProtocolCoOidRequest(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest
)
{...}

Parameter

[in] ProtocolAfContext

Handel yang mengidentifikasi area konteks keluarga alamat (AF). Jika driver adalah klien, driver menyediakan handel ini ketika memanggil NdisClOpenAddressFamilyEx berfungsi untuk menyambungkan dirinya ke manajer panggilan. Jika driver adalah manajer panggilan, ia menyediakan handel ini dari fungsi ProtocolCmOpenAf - nya.

[in] ProtocolVcContext

Handel yang mengidentifikasi koneksi virtual (VC) untuk mengkueri atau mengatur informasi, jika permintaannya khusus untuk VC. Jika tidak, parameter ini adalah NULL.

[in] ProtocolPartyContext

Handel yang mengidentifikasi pihak pada VC multipoint untuk mengkueri atau mengatur informasi, jika permintaan tersebut khusus untuk pihak. Jika tidak, parameter ini adalah NULL.

[in, out] OidRequest

Penunjuk ke struktur NDIS_OID_REQUEST yang berisi buffer dan paket permintaan untuk ditangani oleh driver target. Bergantung pada permintaan, driver mengembalikan informasi yang diminta dalam struktur yang dituju OidRequest .

Nilai kembali

ProtocolCoOidRequest dapat mengembalikan salah satu hal berikut ini:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	Klien atau manajer panggilan melakukan operasi yang diminta.
NDIS_STATUS_PENDING	Klien, atau manajer panggilan menangani permintaan ini secara asinkron, dan akan memanggil Fungsi NdisCoOidRequestComplete atau Fungsi NdisMCmOidRequestComplete saat operasi yang diminta selesai.
NDIS_STATUS_INVALID_LENGTH atau NDIS_STATUS_BUFFER_TOO_SHORT	Driver gagal dalam permintaan karena pemanggil fungsi NdisCoOidRequest atau NdisMCmOidRequest tidak menyediakan nilai yang memadai untuk anggota InformationBuffer dari struktur NDIS_OID_REQUEST untuk permintaan yang diberikan. Driver mengatur anggota BytesNeeded dari NDIS_OID_REQUEST di buffer pada parameter OidRequest ke nilai khusus OID dari anggota InformationBufferLength yang diperlukan untuk melakukan operasi yang diminta.
NDIS_STATUS_XXX	Klien atau manajer panggilan gagal dalam permintaan untuk beberapa alasan yang ditentukan driver, seperti data input yang tidak valid yang ditentukan untuk satu set.
NDIS_STATUS_NOT_SUPPORTED	Klien atau manajer panggilan gagal dalam permintaan ini karena tidak mengenali kode OID_GEN_CO_XXX di anggota Oid dalam buffer di NdisRequest.

Keterangan

Fungsi ProtocolCoOidRequest diperlukan untuk klien CoNDIS, manajer panggilan, dan MCM. ProtocolCoOidRequest mirip dengan fungsi MiniportCoOidRequest driver miniport.

Klien CoNDIS dan manajer panggilan mengirim informasi satu sama lain dengan menentukan nilai non-NULL dalam parameter NdisAfHandle saat mereka memanggil fungsi NdisCoOidRequest . Demikian pula, MCM memanggil NdisMCmOidRequest dengan nilai eksplisit bagi NdisAfHandle untuk mengomunikasikan informasi kepada klien. Panggilan tersebut ke NdisCoOidRequest atau NdisMCmOidRequest menyebabkan NDIS memanggil fungsi ProtocolCoOidRequest dari klien yang ditargetkan, manajer panggilan, atau MCM yang terkait dengan handel AF yang ditentukan.

Untuk mendaftarkan ProtocolCoOidRequest sebagai klien, driver menginisialisasi NDIS_CO_CLIENT_OPTIONAL_HANDLERS struktur dan meneruskannya di parameter OptionalHandlers dari fungsi NdisSetOptionalHandlers . Untuk mendaftarkan ProtocolCoOidRequest sebagai manajer panggilan, driver menginisialisasi NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS struktur dan meneruskannya di parameter OptionalHandlers .

Jika parameter NdisVcHandle dan NdisPartyHandle dari NdisCoOidRequest atau NdisMCmOidRequestadalah NULL, permintaan bersifat global. Artinya, nilai eksplisit untuk NdisVcHandle atau NdisPartyHandle menunjukkan bahwa ProtocolCoOidRequest harus memenuhi permintaan yang diberikan masing-masing berdasarkan per VC atau per pihak.

Buffer pada parameter OidRequest dialokasikan dari kumpulan yang tidak bertumpuk dan, oleh karena itu, dapat diakses pada IRQL yang dinaikkan. Pemanggil NdisCoOidRequest(atau NdisMCmOidRequest) harus merilis buffer ini dan buffer internal pada anggota InformationBuffer dari struktur NDIS_OID_REQUEST yang ditunjuk OidRequest .

Jika ProtocolCoOidRequest mengembalikan NDIS_STATUS_PENDING, driver kemudian harus memanggil Fungsi NdisCoOidRequestComplete , atau Fungsi NdisMCmOidRequestComplete untuk driver MCM, ketika driver menyelesaikan permintaan.

Contoh

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

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Jenis fungsi PROTOCOL_CO_OID_REQUEST 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_CO_OID_REQUEST 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	<= DISPATCH_LEVEL