NdisFRegisterFilterDriver function (ndis.h)

Article
04/18/2022

A filter driver calls the NdisFRegisterFilterDriver function to register its FilterXxx functions with NDIS.

Syntax

NDIS_STATUS NdisFRegisterFilterDriver(
  [in]  PDRIVER_OBJECT                      DriverObject,
  [in]  NDIS_HANDLE                         FilterDriverContext,
        PNDIS_FILTER_DRIVER_CHARACTERISTICS FilterDriverCharacteristics,
  [out] PNDIS_HANDLE                        NdisFilterDriverHandle
);

Parameters

[in] DriverObject

A pointer to an opaque driver object that the filter driver received in its DriverEntry routine at the Argument1 parameter. (For more information, see DriverEntry of NDIS Filter Drivers.)

[in] FilterDriverContext

A handle to a driver-allocated context area where the driver maintains state and configuration information.

FilterDriverCharacteristics

A pointer to an NDIS_FILTER_DRIVER_CHARACTERISTICS structure that the filter driver created and initialized with its FilterXxx function entry points.

[out] NdisFilterDriverHandle

A pointer to a handle variable. If the call to NdisFRegisterFilterDriver succeeds, NDIS fills this variable with a filter driver handle. The filter driver saves this handle and later passes this handle to NDIS functions, such as NdisFDeregisterFilterDriver, that require a filter driver handle as an input parameter.

Return value

NdisFRegisterFilterDriver returns one of the following status values:

Return code	Description
NDIS_STATUS_SUCCESS	NdisFRegisterFilterDriver returns NDIS_STATUS_SUCCESS if it registered the filter driver.
NDIS_STATUS_BAD_VERSION	The version that is specified in the MajorNdisVersion member of the structure at FilterCharacteristics is invalid.
NDIS_STATUS_BAD_CHARACTERISTICS	At least one of the members that are specified in NDIS_FILTER_DRIVER_CHARACTERISTICS is invalid.
NDIS_STATUS_INVALID_PARAMETER	At least one of the input parameters that the driver passed to NdisFRegisterFilterDriver is invalid.
NDIS_STATUS_RESOURCES	NdisFRegisterFilterDriver failed because of insufficient resources.
NDIS_STATUS_FAILURE	NdisFRegisterFilterDriver returns NDIS_STATUS_FAILURE if none of the preceding values applies.

Remarks

A filter driver calls the NdisFRegisterFilterDriver function from its DriverEntry routine. For more information about DriverEntry, see DriverEntry of NDIS Filter Drivers.

Drivers that call NdisFRegisterFilterDriver must be prepared for an immediate call to any of their FilterXxx functions. For more information see Initializing a Filter Driver.

Every filter driver exports a set of FilterXxx functions by setting up the NDIS_FILTER_DRIVER_CHARACTERISTICS structure and calling NdisFRegisterFilterDriver. NDIS copies this structure to the NDIS library's internal storage.

To allow filter drivers to register optional services, NDIS calls the FilterSetOptions function within the context of NdisFRegisterFilterDriver.

After it has registered, a filter driver can later call the NdisSetOptionalHandlers function to change the entry points for optional FilterXxx functions.

Filter drivers call the NdisFDeregisterFilterDriver function to release resources that were previously allocated with NdisFRegisterFilterDriver.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Desktop
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI compliance rules	Irql_Filter_Driver_Function(ndis), NdisFDeregisterFilterDriver(ndis)