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 可以在对 FilterSetOptions 函数的调用返回后随时调用 FilterAttach。

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

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

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

为筛选器模块创建上下文区域，并分配缓冲池和任何其他资源。
将 NdisFSetAttributes 函数与 NDIS 传递给 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的信息，请参阅批注函数行为。