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

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 вместе с параметрами, которые указывают причину сбоя.

Remarks

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 в 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

См. также раздел

FilterDetach

FilterSetOptions

NDIS_FILTER_ATTACH_PARAMETERS

NdisFRegisterFilterDriver

NdisFSetAttributes

NdisWriteEventLogEntry