Поделиться через

структура 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_OBJECT_HEADER для структуры NDIS_OID_REQUEST. Задайте для элемента типа значение NDIS_OBJECT_TYPE_OID_REQUEST. Чтобы указать версию структуры NDIS_OID_REQUEST, задайте элемент редакции одним из следующих значений:

NDIS_OID_REQUEST_REVISION_2

Добавлены SwitchId, VPortIdи флаги для NDIS 6.50.

Задайте для элемента NDIS_SIZEOF_OID_REQUEST_REVISION_2 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, чтобы задать requestId член связанной структуры NDIS_STATUS_INDICATION.

Драйверы NDIS или более поздней версии также могут использовать RequestId для отмены запроса. Когда драйвер минипорта получает запрос на отмену, драйвер минипорта отменяет все ожидающие запросы с соответствующим RequestId. Если RequestId равно нулю, драйвер минипорта может игнорировать этот элемент. Дополнительные сведения о признаках состояния см. в следующем разделе "Примечания".

RequestHandle

Дескриптор, определяющий источник, выдаваемый запросом OID. Если мини-драйвер должен немедленно завершить запрос и завершить запрос с состоянием NDIS_STATUS_INDICATION_REQUIRED, драйвер минипорта использует это значение RequestHandle, чтобы задать DestinationHandle член связанной структуры NDIS_STATUS_INDICATION. В этом случае NDIS отправляет только последующее указание состояния источнику, который выдал запрос OID.

Дополнительные сведения о признаках состояния см. в следующем разделе "Примечания".

DATA

Объединение, определяющее данные запроса. Сведения в данных зависят от типа запроса, указанного членом RequestType. Указаны следующие структуры-члены:

DATA.Oid

DATA.QUERY_INFORMATION

Эта структура содержит параметры для NdisRequestQueryInformation или типа запроса NdisRequestQueryStatistic s. Эта структура указана следующим образом:


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

Размер буфера в InformationBufferв байтах. Значение по Oid определяет значение, соответствующее этому элементу.

DATA.QUERY_INFORMATION.BytesWritten

Количество байтов, которые базовый драйвер или NDIS передают в буфер в InformationBuffer для запросов информации. Если функция NdisOidRequest возвращает NDIS_STATUS_INVALID_LENGTH, значение этого элемента является бессмысленным.

DATA.QUERY_INFORMATION.BytesNeeded

Количество байтов, необходимых для возврата сведений о запросах, запрошенных указанным OID_ кодом XXX.

Если NdisOidRequest возвращает NDIS_STATUS_SUCCESS, значение этого элемента является бессмысленным. Если InformationBufferLength слишком мал для заданного OID_ XXX в запросе, этот элемент указывает, насколько большой буфер необходим для удовлетворения запроса.

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

Размер буфера в InformationBufferв байтах. Значение по Oid определяет значение, соответствующее этому элементу.

DATA.SET_INFORMATION.BytesRead

Количество байтов, считываемых базовым драйвером из буфера в InformationBuffer для запросов набора сведений.

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, так и запросов. В результате данные в буфере для запроса set-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 для запросов набора сведений.

Для OID методов BytesRead должно быть меньше или равно значению в элементе InputBufferLength.

DATA.METHOD_INFORMATION.BytesNeeded

Количество байтов, необходимых для возврата сведений запроса или выполнения операции набора, запрошенной указанным OID_ XXX кодом.

Если NdisOidRequest возвращает NDIS_STATUS_SUCCESS, значение этого элемента является бессмысленным. Если InformationBufferLength слишком мал для заданного OID_ XXX в запросе, этот элемент указывает, насколько большой буфер необходим для удовлетворения запроса. Если буфер в 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, поддерживаемой драйвером NDIS 6.0 или более поздней версии при обработке запроса OID. Измененная структура — это любая структура NDIS 6.0, которая имеет NDIS_OBJECT_HEADER структуру внутри нее. После успешного задания OID драйвер должен задать SupportedRevision номер редакции поддерживаемой структуры. Дополнительные сведения о версии NDIS см. в разделе Указание сведений о версии NDIS.

Reserved1

Зарезервировано для дальнейшего использования.

Reserved2

Зарезервировано для дальнейшего использования.

SwitchId

Значение NDIS_NIC_SWITCH_ID, определяющее переключатель, на котором выполняется целевой VPort, указанный VPortId.

Заметка

Это поле поддерживается в NDIS 6.50 и более поздних версиях.

VPortId

Значение NDIS_NIC_SWITCH_VPORT_ID, определяющее VPort, на который предназначен этот запрос OID. Это поле считается допустимым, только если установлен флаг NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID.

Заметка

Это поле поддерживается в NDIS 6.50 и более поздних версиях.

Flags

Значение ULONG, содержащее побитовое ЗНАЧЕНИЕ ИЛИ флагов для этого запроса OID. В настоящее время поддерживаются следующие флаги:

Флаг Ценность Описание
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 0x0001 Если этот флаг задан, элемент VportId считается допустимым и определяет VPort, к которому предназначен OID. Если этот флаг не задан, OID предназначен для самого мини-адаптера.

Заметка

Это поле поддерживается в NDIS 6.50 и более поздних версиях.

Замечания

Драйвер протокола или драйвер фильтра должен выделить неупакованную память для буфера в InformationBuffer и для структуры NDIS_OID_REQUEST. Использование данных, выделенных из страницной памяти, может привести к сбою страниц, так как базовые драйверы выполняются в IRQL = DISPATCH_LEVEL для выполнения запрошенной операции.

NDIS_OID_REQUEST содержит подструктуру DATA для каждого типа операции, которую драйвер протокола может запрашивать базовый драйвер. Перед вызовом NdisOidRequestдрайвер протокола заполняет соответствующие члены подструктуры, представляющей запрос или операцию задания, указанную в элементе Oid. NDIS или базовый драйвер заполняет остальные элементы перед возвратом элемента управления вызывающему объекту.

Некоторые запросы OID позволяют мини-драйверу предоставить состояние завершения OID с указанием состояния. В этом случае драйвер минипорта возвращает NDIS_STATUS_INDICATION_REQUIRED для состояния завершения запроса OID. Минипорт-драйвер не может вернуть это состояние, если он не разрешает определенный OID. Чтобы определить, разрешено ли это состояние, см. страницу справочника по OID.

Если указание состояния связано с запросом OID, в котором драйвер минипорта вернулся NDIS_STATUS_INDICATION_REQUIRED, драйвер, указывающий состояние, должен задать DestinationHandle и RequestId членов в структуре NDIS_STATUS_INDICATION.

В этом случае драйвер задает DestinationHandle и элементы RequestId значениями из RequestHandle и элементов RequestId в структуре NDIS_OID_REQUEST соответственно.

Например, в беспроводной сети обработка запроса 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