NDIS_OID_REQUEST 結構 (ndis/oidrequest.h)

  • 發行項

若要查詢或設定 OID 資訊，NDIS 會提交NDIS_OID_REQUEST結構來篩選驅動程式和迷你埠驅動程式。

語法

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;

成員

Header

NDIS_OID_REQUEST 結構的NDIS_OBJECT_HEADER結構。 將 [類型 ] 成員設定為 [NDIS_OBJECT_TYPE_OID_REQUEST]。 若要指出NDIS_OID_REQUEST結構的版本，請將 Revision 成員設定為下列其中一個值：

NDIS_OID_REQUEST_REVISION_2

已新增 NDIS 6.50 的 SwitchId、 VPortId 和 Flags 成員。

將 標頭大小 成員設定為 NDIS_SIZEOF_OID_REQUEST_REVISION_2。

NDIS_OID_REQUEST_REVISION_1

NDIS 6.0 的原始版本。

將 標頭大小 成員設定為 NDIS_SIZEOF_OID_REQUEST_REVISION_1。

RequestType

要求類型做為其中一個 NDIS_REQUEST_TYPE 列舉值。

PortNumber

要求傳送至其中的埠。 如果埠未知或預設值，則此成員為零。

Timeout

要求的逾時，以秒為單位。 如果驅動程式完成要求之前逾時到期，NDIS 可以重設驅動程式或取消要求。

RequestId

要求的標識碼。 如果迷你埠驅動程序必須立即完成要求，並完成狀態為NDIS_STATUS_INDICATION_REQUIRED的要求，迷你埠驅動程式會使用此 RequestId 值來設定相關聯NDIS_STATUS_INDICATION結構的 RequestId 成員。

NDIS 或過度處理驅動程式也可以使用 RequestId 來取消要求。 當迷你埠驅動程式收到取消要求時，迷你埠驅動程式會取消具有相符 RequestId 的任何擱置要求。 如果 RequestId 為零，迷你埠驅動程式可以忽略這個成員。 如需狀態指示的詳細資訊，請參閱下列一節。

RequestHandle

識別發出 OID 要求之來源的句柄。 如果迷你埠驅動程序必須立即完成要求，並完成狀態為 NDIS_STATUS_INDICATION_REQUIRED 的要求，迷你埠驅動程式會使用此 RequestHandle 值來設定相關聯NDIS_STATUS_INDICATION結構的 DestinationHandle 成員。 在此情況下，NDIS 只會將後續狀態指示傳送給發出 OID 要求的來源。

如需狀態指示的詳細資訊，請參閱下列一節。

DATA

定義要求數據的等位。 數據中的資訊會根據 RequestType 成員所指定的要求類型而有所不同。 指定下列成員結構：

DATA.Oid

DATA.QUERY_INFORMATION

這個結構包含 NdisRequestQueryInformation 或 NdisRequestQueryStatistics 要求類型的參數。 此結構指定如下：


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

DATA.QUERY_INFORMATION.Oid

所要求作業的物件標識碼。 值為 OID_ XXX 程式代碼。

DATA.QUERY_INFORMATION.InformationBuffer

基礎驅動程式或 NDIS 傳回查詢資訊要求之要求資訊的緩衝區指標。

DATA.QUERY_INFORMATION.InformationBufferLength

資訊Buffer 緩衝區的大小，以位元組為單位。 Oid 上的值會決定適合這個成員的值。

DATA.QUERY_INFORMATION.BytesWritten

基礎驅動程式或 NDIS 在 InformationBuffer 進行查詢資訊要求的緩衝區中傳輸的位元組數目。 如果 NdisOidRequest 函式傳回NDIS_STATUS_INVALID_LENGTH，這個成員的值就沒有意義。

DATA.QUERY_INFORMATION.BytesNeeded

傳回指定OID_ XXX 程式代碼要求之查詢資訊所需的位元元組數目。

如果 NdisOidRequest 傳回NDIS_STATUS_SUCCESS，這個成員的值就沒有意義。 如果對查詢要求上的指定OID_ XXX 而言，InformationBufferLength 太小，則此成員會指出滿足要求所需的緩衝區大小。

DATA.SET_INFORMATION

這個結構包含 NdisRequestSetInformation 要求類型的參數。 此結構指定如下：


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

DATA.SET_INFORMATION.Oid

所要求作業的物件標識碼。 值為 OID_ XXX 程式代碼。

DATA.SET_INFORMATION.InformationBuffer

基礎驅動程式從中讀取呼叫端提供之資訊的緩衝區指標，用於設定資訊要求。

DATA.SET_INFORMATION.InformationBufferLength

資訊Buffer 緩衝區的大小，以位元組為單位。 Oid 上的值會決定適合這個成員的值。

DATA.SET_INFORMATION.BytesRead

基礎驅動程式從緩衝區讀取的位元元組數目，位於 InformationBuffer 以取得 set-information 要求。

DATA.SET_INFORMATION.BytesNeeded

執行指定OID_ XXX 程式代碼所要求的設定作業所需的位元元組數目。

如果 NdisOidRequest 傳回NDIS_STATUS_SUCCESS，這個成員的值就沒有意義。 如果 InformationBuffer 上的緩衝區在設定要求上未包含指定OID_ XXX 的足夠數據，則此成員會指出需要多少數據。

DATA.METHOD_INFORMATION

這個結構包含 NdisRequestMethod 要求類型的參數。 此結構指定如下：


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

所要求作業的物件標識碼。 值為 OID_ XXX 程式代碼。

DATA.METHOD_INFORMATION.InformationBuffer

基礎驅動程式或 NDIS 傳回查詢作業的要求資訊，或基礎驅動程式從中讀取集合作業之呼叫端提供的資訊之緩衝區的指標。 這些作業專屬於所要進行的 NdisRequestMethod 要求類型。

注意 這個緩衝區用於 set-information 和 query-information 要求。 如此一來，設定資訊要求的緩衝區中的數據會由針對查詢資訊要求傳回的數據覆寫。 確切的使用方式取決於 Oid 成員所指定的要求作業。
 

DATA.METHOD_INFORMATION.InputBufferLength

在 InformationBuffer 緩衝區中可讀取數據的大小，以位元組為單位。 Oid 上的值會決定適合這個成員的值。

DATA.METHOD_INFORMATION.OutputBufferLength

緩衝區中驅動程式可以寫入 的 InformationBuffer 位元節數目。

DATA.METHOD_INFORMATION.MethodId

要針對 OID 方法執行的方法。 方法 OID 要求可以支援 由 MethodId 所定義的多個作業。 它可以是大於或等於零的任何值。 零表示預設方法。 NDIS 可以使用一些預先定義的方法定義公用方法 OID。 迷你埠驅動程式可以定義自定義方法 OID。 如需自定義 OID 的詳細資訊，請參閱 OID_GEN_SUPPORTED_GUIDS。

DATA.METHOD_INFORMATION.BytesWritten

基礎驅動程式或 NDIS 在 InformationBuffer 進行查詢資訊要求的緩衝區中傳輸的位元組數目。 如果 NdisOidRequest 函式傳回NDIS_STATUS_INVALID_LENGTH，這個成員的值就沒有意義。

對於方法 OID，BytesWritten 應該小於或等於 OutputBufferLength 成員中的值。

DATA.METHOD_INFORMATION.BytesRead

基礎驅動程式從緩衝區讀取的位元元組數目，位於 InformationBuffer 以取得 set-information 要求。

如果是方法 OID，BytesRead 應該小於或等於 InputBufferLength 成員中的值。

DATA.METHOD_INFORMATION.BytesNeeded

傳回查詢資訊或執行指定OID_ XXX 程式代碼所要求的設定作業所需的位元組數目。

如果 NdisOidRequest 傳回NDIS_STATUS_SUCCESS，這個成員的值就沒有意義。 如果查詢上指定OID_ XXX 的 InformationBufferLength 太小，則此成員會指出滿足要求所需的緩衝區大小。 如果 InformationBuffer 上的緩衝區未包含集合上指定OID_ XXX 的足夠數據，則此成員會指出需要多少數據。

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

保留給 NDIS 的區域。

MiniportReserved[2 * sizeof(PVOID)]

保留給迷你埠驅動程序的區域。

SourceReserved[2 * sizeof(PVOID)]

保留給原始驅動程序的區域。 保留給NDIS_OID_REQUEST結構的配置器。 這通常是 NDIS 通訊協定驅動程式或 NDIS 篩選驅動程式。

SupportedRevision

NDIS 6.0 或更新版本驅動程序處理 OID 要求時所支援的 NDIS 結構修訂。 已修訂的結構是內有 NDIS_OBJECT_HEADER 結構的任何 NDIS 6.0 結構。 當驅動程式成功設定 OID 時，必須將 SupportedRevision 設定為它所支援結構的修訂編號。 如需 NDIS 版本資訊的詳細資訊，請參閱 指定 NDIS 版本資訊。

Reserved1

保留供未來使用。

Reserved2

保留供未來使用。

SwitchId

NDIS_NIC_SWITCH_ID值，識別 VPortId 所指定目標 VPort 執行所在的參數。

注意

NDIS 6.50 和更新版本支援此欄位。

VPortId

NDIS_NIC_SWITCH_VPORT_ID值，識別此 OID 要求的目標 VPort。 只有在設定 NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 旗標時，才會將此欄位視為有效。

注意

NDIS 6.50 和更新版本支援此欄位。

Flags

ULONG 值，包含這個 OID 要求的位 OR 旗標。 目前支持這些旗標：

旗標 值 Description
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 0x0001 設定此旗標時， VportId 成員會被視為有效，並識別 OID 的目標 VPort。 如果未設定此旗標，則 OID 適用於迷你埠配接器本身。

注意

NDIS 6.50 和更新版本支援此欄位。

備註

通訊協定驅動程式或篩選驅動程序應該在 InformationBuffer 和 NDIS_OID_REQUEST 結構上為緩衝區配置非分頁記憶體。 使用從分頁記憶體配置的數據可能會導致嚴重分頁錯誤，因為基礎驅動程式會在 IRQL = DISPATCH_LEVEL執行要求的作業。

NDIS_OID_REQUEST包含通訊協定驅動程式可以要求基礎驅動程式之每種作業類型的 DATA 子結構。 呼叫 NdisOidRequest 之前，通訊協定驅動程式會填入子結構的相關成員，該成員代表 Oid 成員中指定的查詢或設定作業。 NDIS 或基礎驅動程式會在將控制權傳回給呼叫端之前，先填入其餘成員。

某些 OID 要求允許迷你埠驅動程式提供狀態指示的 OID 完成狀態。 在此情況下，迷你埠驅動程式會針對 OID 要求的完成狀態傳回NDIS_STATUS_INDICATION_REQUIRED。 除非特定 OID 允許此狀態，否則迷你埠驅動程式無法傳回此狀態。 若要判斷是否允許此狀態，請參閱 OID 參考頁面。

如果狀態指示與迷你埠驅動程式傳回NDIS_STATUS_INDICATION_REQUIRED的 OID 要求相關聯，則發出狀態指示的驅動程式必須在 NDIS_STATUS_INDICATION 結構中設定 DestinationHandle 和 RequestId 成員。

在此情況下，驅動程式會將 DestinationHandle 和 RequestId 成員分別設定為 NDIS_OID_REQUEST 結構中 RequestHandle 和 RequestId 成員的值。

例如，在無線網路中，OID 要求的處理可能需要很長的時間才能完成。 在此情況下，迷你埠驅動程式可以立即完成 OID 要求，並在稍後提供狀態指示，以提供 OID 要求的最終結果。

NdisRequestGenericn (1-4) 類型適用於建立自己的內部要求的迷你埠驅動程式。 若要實作這類要求，迷你埠驅動程式會將內部變數指派給下列其中一個泛型類型。

規格需求

需求 值
最低支援的用戶端 NDIS 6.0 和更新版本支援。
標頭 ndis/oidrequest.h (include ndis.h)

另請參閱

NDIS_OBJECT_HEADER

NDIS_REQUEST_TYPE

NDIS_STATUS_INDICATION

NdisOidRequest

OID_GEN_SUPPORTED_GUIDS