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

Статья
08/07/2023

Функция FilterRestart инициирует операцию перезапуска для указанного модуля фильтра.

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

Синтаксис

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Параметры

[in] FilterModuleContext

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

[in] RestartParameters

Указатель на NDIS_FILTER_RESTART_PARAMETERS структуры, определяющей параметры перезапуска для модуля фильтра.

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

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

Код возврата	Описание
NDIS_STATUS_SUCCESS	FilterRestart успешно перезапустил указанный модуль фильтра.
NDIS_STATUS_PENDING	Драйвер фильтра выполнит запрос асинхронно с помощью вызова функции NdisFRestartComplete после завершения операции перезапуска.
NDIS_STATUS_RESOURCES	Сбой FilterRestart из-за нехватки ресурсов.
NDIS_STATUS_FAILURE	Ни одно из предыдущих значений состояния не применяется. Драйвер фильтра должен вызывать функцию NdisWriteEventLogEntry вместе с параметрами, указывающими причину сбоя.

FilterRestart — это обязательная функция для драйверов фильтров. NDIS может вызывать FilterRestart , если модуль фильтра находится в состоянии Приостановлено . Модуль фильтра переходит в состояние Перезапуск в начале выполнения FilterRestart.

Когда NDIS вызывает FilterRestart, драйвер фильтра:

Необходимо завершить операции, необходимые для перезапуска обычных операций отправки и получения.
При необходимости считывает или записывает параметры конфигурации.
При необходимости перераспределяет пулы буферов.
При необходимости изменяет атрибуты перезапуска, указанные в элементе RestartAttributes элемента структура NDIS_FILTER_RESTART_PARAMETERS . Если указатель в RestartAttributes имеет значение NULL, драйвер фильтра не должен изменять или добавлять в список атрибутов перезапуска. Если указатель в RestartAttributes не равен NULL, он указывает на первую структуру NDIS_RESTART_ATTRIBUTES в списке атрибутов перезапуска. Если драйвер фильтра не перезапускается, он не должен изменять атрибуты.
При необходимости использует запросы OID для запроса или задания сведений в базовых драйверах. Драйверы фильтров не должны выдавать запросы OID на получение сведений, которые уже указаны в списке атрибутов перезапуска.
Возвращает NDIS_STATUS_SUCCESS или состояние сбоя.

Если драйвер фильтра изменяет список атрибутов перезапуска, драйвер фильтра:

Не следует изменять атрибуты носителя, если он не распознает OID в элементе Oid структура NDIS_RESTART_ATTRIBUTES .
Может добавлять новые атрибуты носителя в список атрибутов перезапуска. В этом случае драйвер фильтра должен выделить новую структуру NDIS_RESTART_ATTRIBUTES, например с помощьюФункция NdisAllocateMemoryWithTagPriority — и предоставляет пространство памяти для новых атрибутов. После распространения атрибутов перезапуска на более чем ранее отстающие драйверы NDIS освобождает память атрибутов для драйверов фильтров.
Может изменять атрибуты носителя в списке атрибутов перезапуска. Если драйверу фильтра требуется больше места в памяти, он может освободить NDIS_RESTART_ATTRIBUTES структуру с помощью функции NdisFreeMemory и выделить новую структуру для хранения измененных сведений. После распространения атрибутов перезапуска на более чем ранее отстающие драйверы NDIS освобождает память атрибутов для драйверов фильтров.
Должно, если элемент Oid в структуре NDIS_RESTART_ATTRIBUTES имеет значение OID_GEN_MINIPORT_RESTART_ATTRIBUTES убедитесь, что NDIS_RESTART_GENERAL_ATTRIBUTES структура содержит сведения, необходимые драйверу фильтра. Чтобы убедиться, что структура NDIS_RESTART_GENERAL_ATTRIBUTES содержит необходимые сведения, необходимо проверка элемент Revision в структуре NDIS_OBJECT_HEADER, указанной в элементе Header структуры NDIS_RESTART_GENERAL_ATTRIBUTES.
Примечание Драйвер фильтра может изменять любой элемент в структуре NDIS_RESTART_GENERAL_ATTRIBUTES. Если некоторые атрибуты, которые должен изменить драйвер фильтра, не включены в редакцию структуры, предоставленной NDIS, драйвер фильтра должен полагаться на слишком много драйверов для выдачи запросов OID для отсутствующих атрибутов. Драйвер фильтра может изменять атрибуты по завершении запроса OID.
Если драйвер фильтра изменяет атрибуты перезапуска, необходимо предоставить функцию FilterOidRequest . Драйвер фильтра должен убедиться, что сведения, получаемые драйверами в атрибутах перезапуска, соответствуют сведениям, которые они получают в ответ на запросы OID.

После того как драйвер фильтра возвращает свое состояние или вызывает функцию NdisFRestartComplete , операция перезапуска завершена. Если операция выполнена успешно, модуль фильтра находится в состоянии Выполняется и возобновляется обычная обработка отправки и получения. Если операция перезапуска завершилась сбоем, модуль фильтра возвращается в состояние Приостановлено .

NDIS вызывает FilterRestart в IRQL = PASSIVE_LEVEL.

Примеры

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

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

FILTER_RESTART MyRestart;

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

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

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

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

Требования

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