FilterSetOptions (Compact 2013)

3/26/2014

NDIS calls a filter driver's FilterSetOptions function to allow the filter driver to register optional services.

Syntax

NDIS_STATUS
  FilterSetOptions(
    IN NDIS_HANDLE  NdisDriverHandle,
    IN NDIS_HANDLE  DriverContext
    );

Parameters

• NdisDriverHandle
  A handle that identifies this filter driver. NDIS returns this handle to the filter driver when it returns from the NdisFRegisterFilterDriver function.

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

Return Value

Value	Meaning
NDIS_STATUS_SUCCESS	FilterSetOptions successfully registered the driver's optional services and resources.
NDIS_STATUS_RESOURCES	FilterSetOptions could not allocate the resources that the driver requires.
NDIS_STATUS_XXX or NTSTATUS_XXX	The filter driver's attempt to register options failed. Usually, such an error status is propagated from an NdisXxx function or a kernel-mode support routine.

Remarks

FilterSetOptions is an optional function. If the entry point for FilterSetOptions is not NULL in the NDIS_FILTER_DRIVER_CHARACTERISTICS structure, NDIS calls FilterSetOptions within the context of the filter driver's call to the NdisFRegisterFilterDriver function.

FilterSetOptions registers optional services and can allocate other driver resources. To register optional FilterXxx functions, the filter driver must call the NdisSetOptionalHandlers function from FilterSetOptions. The driver passes the handle from the NdisDriverHandle parameter of FilterSetOptions to the NdisHandle parameter of NdisSetOptionalHandlers. The driver passes a characteristics structure at the OptionalHandlers parameter.

If an attempt to allocate resources or services fails, FilterSetOptions should undo all the allocations that succeeded before it returns control with a status other than NDIS_STATUS_SUCCESS.

NDIS can call the filter driver's other FilterXxx functions at any time after FilterSetOptions returns. The driver should be prepared to be called back at the FilterAttach function. The filter modules are in the Detached state before the NDIS calls FilterAttach. The FilterDriverUnload function should undo all the operations that were performed in FilterSetOptions.

NDIS calls FilterSetOptions at IRQL = PASSIVE_LEVEL.

Requirements

Header

filter.h

See Also

Reference

NDIS Filter Driver Functions
NDIS_FILTER_DRIVER_CHARACTERISTICS
NdisFRegisterFilterDriver
NdisSetOptionalHandlers