функция обратного вызова FILTER_DIRECT_OID_REQUEST (ndis.h)

Статья
08/07/2023

NDIS вызывает функцию FilterDirectOidRequest драйвера фильтра для обработки прямого запроса OID, связанного с указанным модулем фильтра.

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

Синтаксис

FILTER_DIRECT_OID_REQUEST FilterDirectOidRequest;

NDIS_STATUS FilterDirectOidRequest(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

Параметры

[in] FilterModuleContext

Дескриптор области контекста для модуля фильтра, который является целевым объектом этого запроса. Драйвер фильтра создал и инициализировал эту область контекста в функции FilterAttach .

[in] OidRequest

Указатель на структуру NDIS_OID_REQUEST , указывающую запрошенную операцию, включая код OID_ Xx . В структуре можно указать запрос запроса или запрос набора.

Возвращаемое значение

FilterDirectOidRequest возвращает одно из следующих значений состояния:

Код возврата	Описание
NDIS_STATUS_SUCCESS	FilterDirectOidRequest успешно завершил запрос или операцию установки драйвера фильтра для этого модуля фильтра.
NDIS_STATUS_PENDING	Драйвер фильтра выполнит запрос асинхронно. После выполнения запроса драйвер должен вызватьФункция NdisFDirectOidRequestComplete, информирующая NDIS о завершении запроса.
NDIS_STATUS_INVALID_OID	Запрос, указанный OidRequest , является недопустимым или не распознаваемым.
NDIS_STATUS_NOT_SUPPORTED	FilterDirectOidRequest не поддерживает OID; OID является необязательным.
NDIS_STATUS_BUFFER_TOO_SHORT	Буфер, предоставленный OidRequest , был слишком мал для хранения запрошенных данных.
NDIS_STATUS_INVALID_LENGTH	Для операции запроса элемент InformationBufferLength структуры NDIS_OID_REQUEST не соответствует длине, необходимой заданному идентификатору OID. FilterDirectOidRequest вернул необходимый размер буфера в байтах в элементе BytesNeeded структуры NDIS_OID_REQUEST.
NDIS_STATUS_INVALID_DATA	Для операции набора данные, предоставленные в элементе InformationBuffer структуры NDIS_OID_REQUEST, были недопустимыми для заданного идентификатора OID.
NDIS_STATUS_NOT_ACCEPTED	FilterDirectOidRequest попыталась собрать запрошенные сведения, но не удалась.
NDIS_STATUS_RESOURCES	Сбой FilterDirectOidRequest из-за нехватки ресурсов.
NDIS_STATUS_FAILURE	Применяется N одно из предыдущих возвращаемых значений. Драйвер фильтра должен вызывать функцию NdisWriteErrorLogEntry с параметрами, указывающими причину сбоя.

FilterDirectOidRequest является необязательной функцией. Если драйвер фильтра не использует прямые запросы OID, он может задать точку входа для этой функции значение NULL при вызове функции NdisFRegisterFilterDriver . Если драйвер фильтра определяет Функция FilterDirectOidRequestComplete должна предоставлять функцию FilterDirectOidRequest .

NDIS вызывает функцию FilterDirectOidRequest драйвера фильтра для обработки прямых запросов OID, которые создаются из-за превышения драйверов. Драйверы фильтров могут пересылать такие запросы базовым драйверам, вызывая функцию NdisFDirectOidRequest . Кроме того, драйвер фильтра может выполнять запрос немедленно, не пересылая запрос.

Прежде чем драйвер вызовет NdisFDirectOidRequest, драйвер должен выделить NDIS_OID_REQUEST структуру и передать сведения о запросе в новую структуру, вызвавФункция NdisAllocateCloneOidRequest.

Чтобы выполнить запрос синхронно, драйвер фильтра возвращает NDIS_STATUS_SUCCESS или состояние сбоя. Если драйвер возвращает NDIS_STATUS_PENDING, он должен вызватьФункция NdisFDirectOidRequestComplete, информирующая NDIS о завершении запроса.

Для операции запроса FilterDirectOidRequest возвращает запрошенные сведения в элементе InformationBuffer и задает переменную в элементе BytesWritten структуры NDIS_OID_REQUEST объем возвращаемых сведений. Базовые драйверы делают это, если драйвер фильтра передал запрос с помощью NdisFDirectOidRequest.

Для операции задания FilterDirectOidRequest может использовать данные в элементе InformationBuffer структуры NDIS_OID_REQUEST для задания сведений, необходимых данному OID. В этом случае FilterDirectOidRequest задает для переменной BytesRead объем предоставленных данных, которые она использовала. Базовые драйверы задают BytesRead таким образом, если драйвер фильтра передал запрос с помощью NdisFDirectOidRequest.

NDIS не сериализует запросы, отправляемые в FilterDirectOidRequest , с другими запросами OID. Драйвер фильтра должен иметь возможность обрабатывать несколько вызовов FilterDirectOidRequest , если другие запросы, отправляемые в FilterOidRequest или FilterDirectOidRequest , не выполняются.

NDIS вызывает FilterDirectOidRequest по адресу IRQL <= DISPATCH_LEVEL.

Примеры

Чтобы определить функцию FilterDirectOidRequest , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию FilterDirectOidRequest с именем MyDirectOidRequest, используйте тип FILTER_DIRECT_OID_REQUEST , как показано в следующем примере кода:

FILTER_DIRECT_OID_REQUEST MyDirectOidRequest;

Затем реализуйте функцию следующим образом:

_Use_decl_annotations_
NDIS_STATUS
 MyDirectOidRequest(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Тип функции FILTER_DIRECT_OID_REQUEST определен в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции FILTER_DIRECT_OID_REQUEST в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов NDIS.

Сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.1 и более поздних версиях.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	<= DISPATCH_LEVEL