struktur NDIS_OID_REQUEST (ndis/oidrequest.h)

Artikel
08/07/2023

Untuk mengkueri atau mengatur informasi OID, NDIS mengirimkan struktur NDIS_OID_REQUEST untuk memfilter driver dan driver miniport.

Sintaksis

typedef struct _NDIS_OID_REQUEST {
  NDIS_OBJECT_HEADER       Header;
  NDIS_REQUEST_TYPE        RequestType;
  NDIS_PORT_NUMBER         PortNumber;
  UINT                     Timeout;
  PVOID                    RequestId;
  NDIS_HANDLE              RequestHandle;
  union {
    NDIS_OID Oid;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesWritten;
      UINT     BytesNeeded;
    } QUERY_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } SET_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      ULONG    InputBufferLength;
      ULONG    OutputBufferLength;
      ULONG    MethodId;
      UINT     BytesWritten;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } METHOD_INFORMATION;
  } DATA;
  _REQUEST_DATA            _REQUEST_DATA;
  UCHAR                    *NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE  sizeof(PVOID)];
  UCHAR                    *MiniportReserved[2  sizeof(PVOID)];
  UCHAR                    *SourceReserved[2  sizeof(PVOID)];
  UCHAR                    SupportedRevision;
  UCHAR                    Reserved1;
  USHORT                   Reserved2;
  NDIS_NIC_SWITCH_ID       SwitchId;
  NDIS_NIC_SWITCH_VPORT_ID VPortId;
  ULONG                    Flags;
} NDIS_OID_REQUEST, *PNDIS_OID_REQUEST;

Anggota

Header

Struktur NDIS_OBJECT_HEADER untuk struktur NDIS_OID_REQUEST. Atur anggota Tipe ke NDIS_OBJECT_TYPE_OID_REQUEST. Untuk menunjukkan versi struktur NDIS_OID_REQUEST, atur anggota Revisi ke salah satu nilai berikut:

NDIS_OID_REQUEST_REVISION_2

MenambahkanSwitchId, VPortId, dan Anggota untuk NDIS 6.50.

Atur anggota UkuranHeader ke NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Versi asli untuk NDIS 6.0.

Atur anggota UkuranHeader ke NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

Jenis permintaan sebagai salah satu nilai enumerasi NDIS_REQUEST_TYPE.

PortNumber

Port tempat permintaan dikirim. Jika port tidak diketahui atau default, anggota ini adalah nol.

Timeout

Waktu habis, dalam detik, untuk permintaan. NDIS dapat mengatur ulang driver atau membatalkan permintaan jika waktu habis kedaluwarsa sebelum driver menyelesaikan permintaan.

RequestId

Pengidentifikasi untuk permintaan tersebut. Jika driver miniport harus segera menyelesaikan permintaan dan menyelesaikan permintaan dengan status NDIS_STATUS_INDICATION_REQUIRED, driver miniport menggunakan nilai RequestId ini untuk mengatur RequestId anggota struktur NDIS_STATUS_INDICATION terkait.

NDIS atau driver yang terlalu berlebihan juga dapat menggunakan RequestId untuk membatalkan permintaan. Ketika driver miniport menerima permintaan pembatalan, driver miniport membatalkan permintaan yang tertunda dengan RequestId yang cocok. Jika RequestId adalah nol, driver miniport dapat mengabaikan anggota ini. Untuk informasi selengkapnya tentang indikasi status, lihat bagian Keterangan berikut ini.

RequestHandle

Handel yang mengidentifikasi sumber yang mengeluarkan permintaan OID. Jika driver miniport harus segera menyelesaikan permintaan dan menyelesaikan permintaan dengan status NDIS_STATUS_INDICATION_REQUIRED, driver miniport menggunakan nilai requestHandle ini untuk mengatur DestinationHandle anggota struktur NDIS_STATUS_INDICATION terkait. Dalam hal ini, NDIS hanya akan mengirim indikasi status berikutnya ke sumber yang mengeluarkan permintaan OID.

Untuk informasi selengkapnya tentang indikasi status, lihat bagian Keterangan berikut ini.

DATA

Serikat yang menentukan data permintaan. Informasi dalam data bervariasi sesuai dengan jenis permintaan seperti yang ditentukan oleh RequestType anggota. Struktur anggota berikut ditentukan:

DATA.Oid

DATA.QUERY_INFORMATION

Struktur ini berisi parameter untuk NdisRequestQueryInformation atau NdisRequestQueryStatistics jenis permintaan. Struktur ini ditentukan sebagai berikut:


struct _QUERY
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesWritten;
    UINT        BytesNeeded;
  } QUERY_INFORMATION;

DATA.QUERY_INFORMATION.Oid

Pengidentifikasi objek dari operasi yang diminta. Nilainya adalah kode XXX OID_ .

DATA.QUERY_INFORMATION.InformationBuffer

Penunjuk ke buffer tempat driver atau NDIS yang mendasar mengembalikan informasi yang diminta untuk permintaan informasi kueri.

DATA.QUERY_INFORMATION.InformationBufferLength

Ukuran, dalam byte, buffer di InformationBuffer. Nilai di Oid menentukan nilai yang sesuai untuk anggota ini.

DATA.QUERY_INFORMATION.BytesWritten

Jumlah byte yang ditransfer driver atau NDIS yang mendasar ke buffer di InformationBuffer untuk permintaan informasi kueri. Jika fungsi NdisOidRequest mengembalikan NDIS_STATUS_INVALID_LENGTH, nilai anggota ini tidak ada artinya.

DATA.QUERY_INFORMATION.BytesNeeded

Jumlah byte yang diperlukan untuk mengembalikan informasi kueri yang diminta oleh kode OID_ XXX yang diberikan.

DATA.SET_INFORMATION

Struktur ini berisi parameter untuk jenis permintaan NdisRequestSetInformation. Struktur ini ditentukan sebagai berikut:


struct _SET
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesRead;
    UINT        BytesNeeded;
  } SET_INFORMATION;

DATA.SET_INFORMATION.Oid

Pengidentifikasi objek dari operasi yang diminta. Nilainya adalah kode XXX OID_ .

DATA.SET_INFORMATION.InformationBuffer

Pointer ke buffer tempat driver yang mendasar membaca informasi yang disediakan penelepon untuk permintaan set-information.

DATA.SET_INFORMATION.InformationBufferLength

Ukuran, dalam byte, buffer di InformationBuffer. Nilai di Oid menentukan nilai yang sesuai untuk anggota ini.

DATA.SET_INFORMATION.BytesRead

Jumlah byte yang dibaca driver yang mendasar dari buffer di InformationBuffer untuk permintaan set-information.

DATA.SET_INFORMATION.BytesNeeded

Jumlah byte yang diperlukan untuk melakukan operasi yang ditetapkan yang diminta oleh kode OID_ XXX yang diberikan.

Jika NdisOidRequest mengembalikan NDIS_STATUS_SUCCESS, nilai anggota ini tidak ada artinya. Jika buffer di InformationBuffer tidak berisi data yang memadai untuk OID_ XXX yang diberikan pada permintaan yang ditetapkan, anggota ini menunjukkan berapa banyak data yang diperlukan.

DATA.METHOD_INFORMATION

Struktur ini berisi parameter untuk jenis permintaan NdisRequestMethod. Struktur ini ditentukan sebagai berikut:


struct _METHOD
  {
    NDIS_OID            Oid;
    PVOID               InformationBuffer;
    ULONG               InputBufferLength;
    ULONG               OutputBufferLength;
    ULONG               MethodId;
    UINT                BytesWritten;
    UINT                BytesRead;
    UINT                BytesNeeded;
  } METHOD_INFORMATION;

DATA.METHOD_INFORMATION.Oid

Pengidentifikasi objek dari operasi yang diminta. Nilainya adalah kode XXX OID_ .

DATA.METHOD_INFORMATION.InformationBuffer

Penunjuk ke buffer tempat driver atau NDIS yang mendasar mengembalikan informasi yang diminta untuk operasi kueri atau dari mana driver yang mendasar membaca informasi yang disediakan pemanggil untuk operasi yang ditetapkan. Operasi ini khusus untuk jenis permintaan NdisRequestMethod yang sedang dibuat.

Catatan Buffer ini digunakan untuk permintaan set-information dan query-information. Akibatnya, data dalam buffer untuk permintaan set-information akan ditimpa oleh data yang dikembalikan untuk permintaan informasi kueri. Penggunaan yang tepat tergantung pada operasi yang diminta seperti yang ditentukan oleh anggota Oid.

DATA.METHOD_INFORMATION.InputBufferLength

Ukuran, dalam byte, dari data yang dapat dibaca di buffer di InformationBuffer. Nilai di Oid menentukan nilai yang sesuai untuk anggota ini.

DATA.METHOD_INFORMATION.OutputBufferLength

Jumlah byte dalam buffer di InformationBuffer yang dapat ditulis driver.

DATA.METHOD_INFORMATION.MethodId

Metode yang akan dijalankan untuk metode OID. Permintaan OID metode dapat mendukung beberapa operasi seperti yang didefinisikan oleh MethodId. Ini bisa menjadi nilai apa pun yang lebih besar atau sama dengan nol. Zero menunjukkan metode default. NDIS dapat menentukan OID metode publik dengan beberapa metode yang telah ditentukan sebelumnya. Driver miniport dapat menentukan OID metode kustom. Untuk informasi selengkapnya tentang OID kustom, lihat OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

Untuk OID metode, BytesWritten harus kurang dari atau sama dengan nilai dalam anggota OutputBufferLength .

DATA.METHOD_INFORMATION.BytesRead

Jumlah byte yang dibaca driver yang mendasar dari buffer di InformationBuffer untuk permintaan set-information.

Untuk OID metode, BytesRead harus kurang dari atau sama dengan nilai di anggota InputBufferLength .

DATA.METHOD_INFORMATION.BytesNeeded

Jumlah byte yang diperlukan untuk mengembalikan informasi kueri atau untuk melakukan operasi set yang diminta oleh kode OID_ XXX yang diberikan.

Jika NdisOidRequest mengembalikan NDIS_STATUS_SUCCESS, nilai anggota ini tidak ada artinya. Jika InformationBufferLength terlalu kecil untuk XXX OID_ yang diberikan pada kueri, anggota ini menunjukkan seberapa besar buffer yang diperlukan untuk memenuhi permintaan. Jika buffer di InformationBuffer tidak berisi data yang memadai untuk OID_ XXX yang diberikan pada satu set, anggota ini menunjukkan berapa banyak data yang diperlukan.

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

Area yang dicadangkan untuk NDIS.

MiniportReserved[2 * sizeof(PVOID)]

Area yang dicadangkan untuk pengemudi miniport.

SourceReserved[2 * sizeof(PVOID)]

Area yang dicadangkan untuk driver asal. Dicadangkan untuk alokator struktur NDIS_OID_REQUEST. Ini biasanya driver protokol NDIS atau driver filter NDIS.

SupportedRevision

Revisi struktur NDIS yang didukung oleh driver NDIS 6.0 atau yang lebih baru saat menangani permintaan OID. Struktur yang direvisi adalah struktur NDIS 6.0 apa pun yang memiliki struktur NDIS_OBJECT_HEADER di dalamnya. Ketika driver berhasil mengatur OID, driver harus mengatur SupportedRevision ke nomor revisi struktur yang didukungnya. Untuk informasi selengkapnya tentang informasi versi NDIS, lihat Menentukan Informasi Versi NDIS.

Reserved1

Dicadangkan untuk digunakan di masa mendatang.

Reserved2

Dicadangkan untuk digunakan di masa mendatang.

SwitchId

Nilai NDIS_NIC_SWITCH_ID yang mengidentifikasi sakelar tempat VPort target, yang ditentukan oleh VPortId, sedang berjalan.

Nota

Bidang ini didukung di NDIS 6.50 dan yang lebih baru.

VPortId

Nilai NDIS_NIC_SWITCH_VPORT_ID yang mengidentifikasi VPort yang ditargetkan permintaan OID ini. Bidang ini dianggap valid hanya jika bendera NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID diatur.

Nota

Bidang ini didukung di NDIS 6.50 dan yang lebih baru.

Flags

Nilai ULONG yang berisi bitwise ATAU bendera untuk permintaan OID ini. Saat ini, bendera ini didukung:

Bendera	Nilai	Deskripsi
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID	0x0001	Ketika bendera ini diatur, anggota VportId dianggap valid dan mengidentifikasi VPort tempat OID ditargetkan. Jika bendera ini tidak diatur, maka OID adalah untuk adaptor miniport itu sendiri.

Nota

Bidang ini didukung di NDIS 6.50 dan yang lebih baru.

Komentar

Driver protokol atau driver filter harus mengalokasikan memori yang tidak di-patok untuk buffer pada InformationBuffer dan untuk struktur NDIS_OID_REQUEST. Menggunakan data yang dialokasikan dari memori halaman dapat menyebabkan kesalahan halaman fatal karena driver yang mendasarinya berjalan di IRQL = DISPATCH_LEVEL untuk melakukan operasi yang diminta.

NDIS_OID_REQUEST berisi substruktur DATA untuk setiap jenis operasi yang dapat diminta driver protokol dari driver yang mendasar. Sebelum memanggil NdisOidRequest, driver protokol mengisi anggota substruktur yang relevan yang mewakili kueri atau mengatur operasi yang ditentukan dalam anggota Oid. NDIS atau driver yang mendasar mengisi anggota yang tersisa sebelum mengembalikan kontrol ke pemanggil.

Beberapa permintaan OID memungkinkan driver miniport untuk memberikan status penyelesaian OID dengan indikasi status. Dalam hal ini, driver miniport mengembalikan NDIS_STATUS_INDICATION_REQUIRED untuk status penyelesaian permintaan OID. Driver miniport tidak dapat mengembalikan status ini kecuali OID tertentu mengizinkannya. Untuk menentukan apakah status ini diizinkan, lihat halaman referensi OID.

Jika indikasi status dikaitkan dengan permintaan OID tempat driver miniport mengembalikan NDIS_STATUS_INDICATION_REQUIRED, driver yang membuat indikasi status harus mengatur DestinationHandle dan anggota RequestId dalam struktur NDIS_STATUS_INDICATION.

Dalam hal ini, driver mengatur DestinationHandle dan anggota RequestId ke nilai dari RequestHandle dan anggota RequestId dalam struktur NDIS_OID_REQUEST.

Misalnya, dalam jaringan nirkabel, pemrosesan permintaan OID dapat memakan waktu yang sangat lama untuk diselesaikan. Dalam hal ini, driver miniport dapat segera menyelesaikan permintaan OID dan memberikan indikasi status nanti untuk memberikan hasil akhir untuk permintaan OID.

Jenis NdisRequestGenericn(1-4) tersedia untuk driver miniport yang membuat permintaan internal mereka sendiri. Untuk menerapkan permintaan seperti itu, driver miniport menetapkan variabel internal ke salah satu jenis generik ini.