Fungsi NdisCoOidRequest (ndis.h)

Artikel
03/08/2023

Fungsi NdisCoOidRequest meneruskan permintaan ke driver CoNDIS yang ditargetkan untuk mengkueri atau mengatur informasi driver target yang ditentukan OID.

Sintaks

NDIS_STATUS NdisCoOidRequest(
  [in]           NDIS_HANDLE       NdisBindingHandle,
  [in, optional] NDIS_HANDLE       NdisAfHandle,
  [in, optional] NDIS_HANDLE       NdisVcHandle,
  [in, optional] NDIS_HANDLE       NdisPartyHandle,
  [in, out]      PNDIS_OID_REQUEST OidRequest
);

Parameter

[in] NdisBindingHandle

Handel yang dikembalikan fungsi NdisOpenAdapterEx yang mengidentifikasi adaptor target untuk pengikatan.

[in, optional] NdisAfHandle

Handel yang mengidentifikasi keluarga alamat (AF) yang dibagikan di antara klien, manajer panggilan, dan NDIS. Handel ini diperoleh sebagai berikut:

Jika pemanggil adalah klien yang membuat permintaan ke manajer panggilan, klien awalnya mendapatkan handel ini dari panggilan yang berhasil ke Fungsi NdisClOpenAddressFamilyEx .
Jika pemanggil adalah manajer panggilan mandiri atau manajer panggilan miniport (MCM) yang membuat permintaan ke klien, manajer panggilan atau MCM awalnya mendapatkan handel ini sebagai parameter input untuk fungsi ProtocolCmOpenAf-nya .

Untuk membuat permintaan dari klien atau manajer panggilan mandiri ke driver miniport yang mendasar, parameter ini harus NULL.

[in, optional] NdisVcHandle

Handel yang mengidentifikasi koneksi virtual (VC) pemanggil meminta atau mengatur informasi, jika permintaannya khusus untuk VC. Jika tidak, jika parameter ini NULL, permintaannya tidak spesifik untuk VC. Untuk permintaan khusus VC apa pun, pemanggil awalnya mendapatkan handel ini baik ketika membuat VC dengan fungsi NdisCoCreateVc , atau sebagai parameter input untuk fungsi ProtocolCoCreateVc-nya . Untuk permintaan khusus VC yang diarahkan ke driver miniport yang mendasar, handel ini mengidentifikasi VC, sementara NdisAfHandle dan NdisPartyHandle adalah NULL.

[in, optional] NdisPartyHandle

Handel yang mengidentifikasi pihak pada VC multipoint yang diminta atau diatur informasinya, jika permintaannya khusus pihak. Jika tidak, jika parameter ini NULL, permintaannya tidak spesifik untuk pihak tertentu. Untuk permintaan khusus pihak mana pun, klien awalnya mendapatkan handel ini dari panggilan yang berhasil ke fungsi NdisClAddParty atau fungsi NdisClMakeCall atau manajer panggilan memperoleh handel ini sebagai parameter input ke fungsi ProtocolCmAddParty-nya . Jika NdisAfHandleADALAH NULL, NdisPartyHandle juga NULL.

[in, out] OidRequest

Penunjuk ke struktur NDIS_OID_REQUEST yang menentukan operasi yang diminta dengan kode OID_XXX yang diberikan untuk mengkueri atau mengatur informasi.

Nilai kembali

Driver target menentukan kode NDIS_STATUS_XXX mana yang dikembalikan NdisCoOidRequest , biasanya salah satu nilai berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	Operasi permintaan berhasil diselesaikan.
NDIS_STATUS_PENDING	Permintaan sedang ditangani secara asinkron, dan NDIS akan memanggil pemanggil Fungsi ProtocolCoOidRequestComplete saat permintaan selesai.
NDIS_STATUS_INVALID_OID	Kode OID_XXX yang ditentukan dalam anggota Oid dari struktur NDIS_OID_REQUEST di parameter OidRequest tidak valid atau tidak didukung oleh driver yang mendasar.
NDIS_STATUS_INVALID_LENGTH atau NDIS_STATUS_BUFFER_TOO_SHORT	Nilai yang ditentukan dalam anggota InformationBufferLength dari buffer terstruktur NDIS_OID_REQUEST di OidRequest tidak cocok dengan persyaratan untuk kode OID_XXX yang diberikan. Jika buffer informasi terlalu kecil, anggota BytesNeeded dari NDIS_OID_REQUEST berisi nilai yang benar untuk InformationBufferLength, saat NdisCoOidRequest kembali.
NDIS_STATUS_INVALID_DATA	Data yang disediakan di InformationBuffer dalam struktur NDIS_OID_REQUEST yang diberikan tidak valid untuk kode OID_XXX yang diberikan.
NDIS_STATUS_NOT_SUPPORTED atau NDIS_STATUS_NOT_RECOGNIZED	Driver yang mendasar tidak mendukung operasi yang diminta.
NDIS_STATUS_RESOURCES	Permintaan tidak dapat dipenuhi karena kekurangan sumber daya. Biasanya, nilai pengembalian ini menunjukkan bahwa upaya untuk mengalokasikan memori tidak berhasil, tetapi tidak selalu menunjukkan bahwa permintaan yang sama, jika dikirimkan nanti, akan gagal karena alasan yang sama.
NDIS_STATUS_NOT_ACCEPTED	Driver yang mendasar mencoba operasi yang diminta, biasanya permintaan yang ditetapkan, tetapi operasi gagal. Misalnya, upaya untuk mengatur terlalu banyak alamat multicast dapat menyebabkan NdisCoOidRequest mengembalikan nilai ini.
NDIS_STATUS_CLOSING atau NDIS_STATUS_CLOSING_INDICATING	Driver yang mendasar gagal dalam operasi yang diminta karena operasi penutupan sedang berlangsung.
NDIS_STATUS_RESET_IN_PROGRESS	Driver miniport yang mendasar tidak dapat memenuhi permintaan saat ini karena saat ini sedang mengatur ulang NIC yang terpengaruh. Fungsi ProtocolStatusEx penelepon adalah atau akan dipanggil dengan NDIS_STATUS_RESET_START untuk menunjukkan bahwa reset sedang berlangsung. Nilai pengembalian ini tidak selalu menunjukkan bahwa permintaan yang sama, jika dikirimkan nanti, akan gagal karena alasan yang sama.
NDIS_STATUS_FAILURE	Nilai ini biasanya adalah nilai default nonspesfik yang dikembalikan ketika tidak ada NDIS_STATUS_XXX yang lebih spesifik yang menyebabkan driver yang mendasar gagal dalam permintaan.
NDIS_STATUS_REQUEST_ABORTED	Driver miniport berhenti memproses permintaan. Misalnya, NDIS disebut MiniportResetEx driver miniport yang mendasar atau Fungsi MiniportCancelOidRequest .

Keterangan

Klien CoNDIS dan manajer panggilan mandiri dapat memanggil fungsi NdisCoOidRequest untuk mengirim permintaan OID untuk mengkueri atau mengatur informasi yang ditentukan OID dalam driver target. Driver target dapat menjadi driver protokol CoNDIS lain atau driver yang mendasar.

Pemanggil NdisCoOidRequest harus mengalokasikan memori yang cukup untuk menahan buffer informasi yang terkait dengan OID yang ditentukan. Pemanggil juga harus mengalokasikan dan menyiapkan buffer di OidRequest sebelum memanggil NdisCoOidRequest. Kedua buffer harus dialokasikan dari kumpulan yang tidak disebarkan karena driver target dapat berjalan pada IRQL yang dinaikkan saat memproses permintaan.

Beberapa kesalahan yang dikembalikan NdisCoOidRequest dapat dipulihkan, termasuk yang berikut ini:

NDIS_STATUS_INVALID_OID
NDIS_STATUS_INVALID_LENGTH
NDIS_STATUS_BUFFER_TOO_SHORT
NDIS_STATUS_INVALID_DATA
NDIS_STATUS_RESOURCES
NDIS_STATUS_RESET_IN_PROGRESS

Artinya, driver dapat memodifikasi paket di OidRequest dengan tepat untuk memperbaiki kode OID_XXX atau ukuran atau konten buffer di InformationBuffer dan mengirim ulang paket permintaan ke NdisCoOidRequest. Paket yang sama mungkin terpenuhi ketika driver mengirimkannya kembali ke NdisCoOidRequest jika panggilan asli menunjukkan pengaturan ulang sedang berlangsung atau bahwa kekurangan sumber daya, yang mungkin bersifat sementara, mencegah permintaan tersebut dilakukan.

Bergantung pada nilai parameter NdisAfHandle , klien, dan manajer panggilan mandiri memanggil NdisCoOidRequest untuk berkomunikasi satu sama lain atau dengan driver miniport berorientasi koneksi yang mendasar.

Jika driver melewati NULL untuk NdisVcHandle, permintaan bersifat global, apakah permintaan diarahkan ke klien, manajer panggilan, atau driver miniport. Misalnya, jika pemanggil memasok nilai non-NULL untuk NdisVcHandle, permintaan OID OID_GEN_CO_RCV_CRC_ERROR ke driver miniport berorientasi koneksi yang mendasar mengembalikan jumlah kesalahan pemeriksaan redundansi siklik (CRC) yang ditemui untuk VC tertentu. Untuk permintaan yang sama dengan NULL untuk NdisVcHandle, driver miniport yang mendasar mengembalikan jumlah total kesalahan CRC yang ditemui untuk semua VC.

Klien dan manajer panggilan mandiri harus memanggil fungsi NdisOidRequest untuk semua OID yang tidak berorientasi koneksi, seperti yang dikembalikan dalam kueri OID_GEN_SUPPORTED_LIST , yang biasanya dikeluarkan selama inisialisasi setelah driver protokol terikat dengan driver NIC yang mendasar.

Jika NdisCoOidRequest mengembalikan NDIS_STATUS_PENDING, permintaan sedang ditangani secara asinkron dan NDIS akan memanggil driver Fungsi ProtocolCoOidRequestComplete saat permintaan selesai. Jika NdisCoOidRequest mengembalikan status lain, permintaan selesai saat NdisCoOidRequest kembali, dan NDIS tidak memanggil ProtocolCoOidRequestComplete.

Untuk informasi selengkapnya tentang kumpulan OID yang ditentukan untuk digunakan dengan NdisCoOidRequest dan NdisOidRequest, lihat OID NDIS.

Hanya klien dan manajer panggilan mandiri, yang merupakan driver protokol, yang dapat memanggil NdisCoOidRequest. MCM memanggil fungsi NdisMCmOidRequest untuk berkomunikasi dengan klien mereka.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung di NDIS 6.0 dan yang lebih baru.
Target Platform	Desktop
Header	ndis.h (termasuk Ndis.h)
Pustaka	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Aturan kepatuhan DDI	Irql_Connection_Function(ndis)