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

Статья
08/07/2023

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

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

Синтаксис

FILTER_OID_REQUEST FilterOidRequest;

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

Параметры

[in] FilterModuleContext

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

[in] OidRequest

Указатель на структуру NDIS_OID_REQUEST , указывающую запрошенную операцию, включая код OID_XXX . В структуре можно указать запрос запроса OID или запрос на набор OID. Дополнительные сведения о идентификаторах OID см. в разделе NDIS OIDs.

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

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

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

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

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

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

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

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

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

Как и драйверы минипорта, драйверы фильтров могут получать только один запрос за раз. NDIS сериализует запросы, отправляемые драйверу фильтра. NDIS не может вызвать FilterOidRequest до того, как драйвер фильтра завершит текущий запрос.

NDIS вызывает FilterOidRequest в IRQL <= DISPATCH_LEVEL.

Примеры

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

Например, чтобы определить функцию FilterOidRequest с именем MyOidRequest, используйте тип FILTER_OID_REQUEST , как показано в этом примере кода:

FILTER_OID_REQUEST MyOidRequest;

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

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

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

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

Требования

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