функция FILTER_SYNCHRONOUS_OID_REQUEST (ndis.h)
NDIS вызывает функцию FilterSynchronousOidRequest драйвера фильтра для предварительного просмотра синхронного запроса OID перед отправкой запроса базовому драйверу мини-порта.
Эта функция поддерживается в NDIS 6.81 и более поздних версиях.
Синтаксис
NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
NDIS_HANDLE FilterModuleContext,
[in, out] NDIS_OID_REQUEST *OidRequest,
[out] PVOID *CallContext
);
Параметры
FilterModuleContext
Дескриптор области контекста для модуля фильтра, который является целевым объектом этого запроса. Драйвер фильтра создал и инициализировал эту область контекста в функции FilterAttach .
[in, out] OidRequest
Указатель на структуру NDIS_OID_REQUEST , указывающую запрошенную операцию.
[out] CallContext
Слот хранения размера PVOID для драйвера фильтра для совместного использования состояния между обработчиками FilterSynchronousOidRequest и FilterSynchronousOidRequestComplete . NDIS гарантирует, что изначально это указывает на нулевое значение. Дополнительные сведения см. в разделе "Примечания".
Возвращаемое значение
Эта функция возвращает один из следующих соответствующих кодов NDIS_STATUS:
| Код возврата | Описание |
|---|---|
| NDIS_STATUS_SUCCESS | Разрешите OID-запросу продолжить распространение вплоть до драйвера мини-порта. Драйверы фильтров должны возвращать этот код состояния для любого нераспознанного типа OID. |
| NDIS_STATUS_ALREADY_COMPLETE | Прекратите распространение запроса OID и верните его вызывающему объекту с состоянием NDIS_STATUS_SUCCESS. |
|
То же, что и FilterDirectOidRequest. |
| NDIS_STATUS_RESOURCES | То же самое, что и FilterDirectOidRequest, но с осторожностью, что синхронные запросы OID должны выполняться быстро, поэтому драйверы фильтров обычно не должны выделять ресурсы. |
| NDIS_STATUS_NOT_SUPPORTED | Драйверы фильтров не должны возвращать этот код только потому, что идентификатор OID неизраспознан. Драйверы фильтров могут возвращать это значение, только если фильтр распознает операцию, но не может выполнить ее по какой-либо причине. |
Комментарии
FilterSynchronousOidRequest является необязательной функцией. Если драйверу фильтра не нужно отслеживать или изменять синхронные запросы OID, отправленные драйверу мини-порта, драйвер фильтра должен задать точку входа для этой функции значение NULL при вызове NdisFRegisterFilterDriver.
NDIS вызывает функцию FilterSynchronousOidRequest драйвера фильтра для обработки синхронных запросов OID, которые порождены избыточными драйверами. Драйверы фильтров могут считывать или изменять некоторые поля в структуре NDIS_OID_REQUEST следующим образом:
| Поле | Фильтрация доступа |
|---|---|
| Заголовок | Только для чтения |
| RequestType | Чтение/запись |
| PortNumber | Чтение/запись |
| Время ожидания | Не получать доступ |
| RequestId | Не получать доступ |
| RequestHandle | Чтение/запись |
| DATA | Чтение/запись |
| NdisReserved | Не получать доступ |
| MiniportReserved | Не получать доступ |
| SourceReserved | Не получать доступ |
| SupportedRevision | Чтение/запись |
| Reserved1, Reserved2 | Не получать доступ |
| SwitchId | Чтение/запись |
| VPortId | Чтение/запись |
| Флаги | Чтение/запись |
Помимо изменения структуры NDIS_OID_REQUEST , драйверы фильтров могут управлять запросом с помощью кода возврата из FilterSynchronousOidRequest:
- NDIS_STATUS_SUCCESS: OID продолжает распространяться на драйвер мини-порта.
- NDIS_STATUS_ALREADY_COMPLETE: OID немедленно возвращается обратно к драйверам, расположенным выше, без предварительного распространения на драйвер мини-порта. Запрос OID завершается для вышестающего драйвера с NDIS_STATUS_SUCCESS.
- Любой другой код состояния: OID сразу же возвращается к вышеопределяющим драйверам без предварительного распространения на драйвер мини-порта. Запрос OID завершается в драйвере, который находится выше, с кодом состояния, возвращенным драйвером фильтра.
Если драйвер фильтра также регистрирует обработчик FilterSynchronousOidRequestComplete , NDIS гарантирует, что обработчик FilterSynchronousOidRequestComplete будет вызываться только в том случае, если обработчик FilterSynchronousOidRequest возвращает NDIS_STATUS_SUCCESS.
Обработчик FilterSynchronousOidRequest может записывать любое значение размера PVOID в *CallContext, и то же значение будет возвращено обработчику FilterSynchronousOidRequestComplete драйвера фильтра после завершения запроса OID. Драйвер фильтра может использовать его для переноса состояния между двумя обработчиками. Так как обработчик FilterSynchronousOidRequestComplete вызывается только в том случае, если обработчик FilterSynchronousOidRequest возвращает NDIS_STATUS_SUCCESS, нет смысла записывать значение в *CallContext при возврате любого другого кода. Аналогичным образом, нет смысла записывать значение в *CallContext , если драйвер фильтра не предоставляет обработчик FilterSynchronousOidRequestComplete .
Драйверы фильтров не должны возвращать NDIS_STATUS_PENDING из обработчика FilterSynchronousOidRequest . Синхронные запросы OID нельзя выполнять или отменять.
Ожидается, что драйверы фильтров будут быстро возвращать данные из обработчика FilterSynchronousOidRequest , не блокируя, не ожидая или не в спящем режиме. Синхронные запросы OID используются только для операций с низкой задержкой, и драйверы фильтров должны стремиться продолжить или завершить их в течение нескольких миллисекунд. NDIS не сериализует синхронные запросы OID друг к другу, к другим запросам OID или FilterPause. За реализацию любой необходимой синхронизации отвечает драйвер фильтра.
NDIS сериализует синхронные запросы OID к FilterDetach. NDIS гарантирует, что синхронные запросы OID не будут активны после вызова FilterDetach .
Драйверы фильтров не должны вызывать NdisAllocateCloneOidRequest или NdisCancelOidRequest в синхронном запросе OID. Драйверы фильтров не должны вызывать NdisFSynchronousOidRequest в запросе OID, полученном через обработчик FilterSynchronousOidRequest .
Если драйвер фильтра вызывает IRQL в обработчике FilterSynchronousOidRequest , он должен восстановить IRQL до начального уровня, прежде чем возвращать его из обработчика FilterSynchronousOidRequest .
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 10 версии 1709 |
| Целевая платформа | Windows |
| Header | ndis.h (включая Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по