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 函数与指定失败原因的参数一起调用。

言论

FilterAttach 是必需函数。当指定的筛选器模块处于分离状态时，NDIS 调用筛选器驱动程序的 FilterAttach 函数。在 FilterSetOptions 函数返回后，NDIS 可以随时调用 filterAttach。

在 FilterAttach执行开始时，筛选器模块将进入附加状态。

筛选器驱动程序应避免发出不必要的 OID 查询。请改用中的信息 NDIS_FILTER_ATTACH_PARAMETERS（如果可用）获取有关基础驱动程序的信息。

当 NDIS FilterAttach调用时，筛选器驱动程序将执行以下作。

为筛选器模块创建上下文区域，并分配缓冲池和其他任何资源。
将 NdisFSetAttributes 函数与传递给 FilterAttach的 NdisFilterHandle 一起调用。 NdisFSetAttributes FilterModuleContext 参数指定此筛选器模块的筛选器驱动程序的上下文区域。 NDIS 将此上下文区域传递给筛选器驱动程序的 FilterXxx 函数。
（可选）从注册表读取配置参数。
如果上述作成功完成，筛选器模块将进入暂停状态。
如果上述作失败，筛选器驱动程序必须释放在 FilterAttach 函数中分配的任何资源，并将筛选器模块返回到已分离状态。
返回NDIS_STATUS_SUCCESS或适当的故障代码。

筛选器驱动程序不应发出发送请求、指示收到的数据、发出 OID 请求或从附加状态发出状态指示。

NDIS 调用筛选器驱动程序的 FilterDetach 函数以释放与筛选器模块关联的所有资源，并将筛选器模块返回到已分离状态。

NDIS 在 IRQL = PASSIVE_LEVEL FilterAttach 调用。

示例

若要定义 FilterAttach 函数，必须首先提供一个函数声明，用于标识要定义的函数的类型。 Windows 为驱动程序提供了一组函数类型。使用函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序（SDV）和其他验证工具查找错误，这是为 Windows作系统编写驱动程序的要求。

例如，若要定义名为“MyAttach”的 FilterAttach 函数，请使用 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的信息，请参阅批注函数行为。