FilterAttach (Compact 2013)

3/26/2014

This function allocates and initializes a filter module's data structures.

Syntax

NDIS_STATUS
  FilterAttach(
    IN NDIS_HANDLE  NdisFilterHandle,
    IN NDIS_HANDLE  FilterDriverContext,
    IN PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    );

Parameters

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

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

• 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:

Value	Meaning
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 previous 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 it is 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 previous operations completed successfully, the filter module enters the Paused state.
• If the previous 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.

Requirements

Header

filter.h

See Also

Reference

NDIS Filter Driver Functions
FilterDetach
FilterSetOptions
NDIS_FILTER_ATTACH_PARAMETERS
NdisFRegisterFilterDriver
NdisFSetAttributes