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

Статья
08/07/2023

NDIS вызывает функцию FilterAttach драйвера фильтра для выделения и инициализации структур данных модуля фильтра.

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

Синтаксис

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Параметры

[in] NdisFilterHandle

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

[in] FilterDriverContext

Дескриптор, переданный драйвером Функция NdisFRegisterFilterDriver , идентифицирующая область контекста драйвера.

[in] AttachParameters

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

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

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

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

FilterAttach — это обязательная функция. NDIS вызывает функцию FilterAttach драйвера фильтра, если указанный модуль фильтра находится в состоянии "Отсоединенный ". NDIS может вызвать FilterAttach в любое время после возврата вызова функции FilterSetOptions .

В начале выполнения в FilterAttach модуль фильтра переходит в состояние Присоединение .

Драйверы фильтров должны избегать выдачи ненужных запросов OID. Вместо этого используйте сведения в NDIS_FILTER_ATTACH_PARAMETERS, если они доступны, для получения сведений о базовых драйверах.

Драйвер фильтра выполняет следующие операции, когда NDIS вызывает FilterAttach.

Создает область контекста для модуля фильтра и выделяет буферные пулы и любые другие ресурсы.
Вызывает функцию NdisFSetAttributes вместе с NdisFilterHandle , переданной NDIS в FilterAttach. Параметр FilterModuleContextобъекта NdisFSetAttributes указывает область контекста драйвера фильтра для этого модуля фильтра. NDIS передает эту область контекста в функции FilterXxx драйвера фильтра.
При необходимости считывает параметры конфигурации из реестра.
Если предыдущие операции успешно завершены, модуль фильтра переходит в состояние Приостановлено .
Если предыдущие операции завершилися сбоем, драйвер фильтра должен освободить все ресурсы, выделенные в функции FilterAttach , и вернуть модуль фильтра в состояние Отсоединенный .
Возвращает NDIS_STATUS_SUCCESS или соответствующий код сбоя.

Драйвер фильтра не должен отправлять запросы, указывать полученные данные, выполнять запросы OID или указывать состояние из состояния Присоединение .

NDIS вызывает функцию FilterDetach драйвера фильтра, чтобы освободить все ресурсы, связанные с модулем фильтра, и вернуть модуль фильтра в состояние Отсоединенный .

NDIS вызывает FilterAttach at IRQL = PASSIVE_LEVEL.

Примеры

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

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

FILTER_ATTACH MyAttach;

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

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

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

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

Требования

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