FILTER_ATTACH callback function (ndis.h)

Article
10/21/2021

NDIS calls a filter driver's FilterAttach function to allocate and initialize a filter module's data structures.

Note You must declare the function by using the FILTER_ATTACH type. For more information, see the following Examples section.

Syntax

FILTER_ATTACH FilterAttach;

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

Parameters

[in] NdisFilterHandle

An NDIS handle that identifies a filter module. The filter driver must save this handle. The handle is required in subsequent calls to NdisFXxx functions.

[in] FilterDriverContext

The handle that the driver passed to the NdisFRegisterFilterDriver function that identifies the driver context area.

[in] AttachParameters

A pointer to an NDIS_FILTER_ATTACH_PARAMETERS structure that defines the initialization parameters for the filter module.

Return value

FilterAttach returns one of the following status values:

Return code	Description
NDIS_STATUS_SUCCESS	FilterAttach successfully allocated and initialized data structures for this filter module.
NDIS_STATUS_RESOURCES	FilterAttach failed because of insufficient resources.
NDIS_STATUS_FAILURE	FilterAttach returns NDIS_STATUS_FAILURE if none of the preceding values applies. The filter driver should call the NdisWriteEventLogEntry function together with parameters that specify the reason for the failure.

Remarks

FilterAttach is a required function. NDIS calls a filter driver's FilterAttach function when the specified filter module is in the Detached state. NDIS can call FilterAttach at any time after the call to the FilterSetOptions function returns.

At the start of execution in FilterAttach, the filter module enters the Attaching state.

Filter drivers should avoid issuing unnecessary OID queries. Instead, use the information in NDIS_FILTER_ATTACH_PARAMETERS, when available, to obtain information about underlying drivers.

A filter driver performs the following operations when NDIS calls FilterAttach.

Creates a context area for the filter module and allocates buffer pools and any other resources.
Calls the NdisFSetAttributes function together with the NdisFilterHandle that NDIS passed to FilterAttach. The FilterModuleContext parameter of NdisFSetAttributes specifies the filter driver's context area for this filter module. NDIS passes this context area to the filter driver's FilterXxx functions.
Optionally reads configuration parameters from the registry.
If the preceding operations completed successfully, the filter module enters the Paused state.
If the preceding operations failed, the filter driver must release any resources that it allocated in the FilterAttach function and return the filter module to the Detached state.
Returns NDIS_STATUS_SUCCESS or an appropriate failure code.

A filter driver should not make send requests, indicate received data, make OID requests, or make status indications from the Attaching state.

NDIS calls a filter driver's FilterDetach function to release all the resources that are associated with a filter module and return the filter module to the Detached state.

NDIS calls FilterAttach at IRQL = PASSIVE_LEVEL.

Examples

To define a FilterAttach function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a FilterAttach function that is named "MyAttach", use the FILTER_ATTACH type as shown in this code example:

FILTER_ATTACH MyAttach;

Then, implement your function as follows:

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

The FILTER_ATTACH function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the FILTER_ATTACH function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL