структура 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 .
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) |
См. также раздел
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по