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

NDIS_OID_REQUEST_REVISION_2

Добавлены элементы SwitchId, VPortId и Flags для NDIS 6.50.

Задайте для элемента Размер заголовка значение 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 или overlying также могут использовать RequestId для отмены запроса. Когда драйвер минипорта получает запрос на отмену, он отменяет все ожидающие запросы с соответствующим Значением RequestId. Если значение RequestId равно нулю, драйвер мини-порта может игнорировать этот элемент. Дополнительные сведения о признаках состояния см. в следующем разделе Примечания.

RequestHandle

Дескриптор, идентифицирующий источник, выдавающий запрос OID. Если драйвер мини-порта должен немедленно выполнить запрос и завершает запрос с состоянием NDIS_STATUS_INDICATION_REQUIRED, драйвер мини-порта использует это значение RequestHandle , чтобы задать член DestinationHandle связанной структуры NDIS_STATUS_INDICATION. В этом случае 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

Размер буфера в байтах в 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

Указатель на буфер, из которого базовый драйвер считывает предоставленные вызывающим объектом сведения для запросов set-information.

DATA.SET_INFORMATION.InformationBufferLength

Размер буфера в байтах в InformationBuffer. Значение в 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. В результате данные в буфере для запроса 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_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, значение этого элемента не имеет смысла. Если аргумент 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 (включая ndis.h)

См. также раздел

NDIS_OBJECT_HEADER

NDIS_REQUEST_TYPE

NDIS_STATUS_INDICATION

NdisOidRequest

OID_GEN_SUPPORTED_GUIDS