FilterSetModuleOptions routine

The FilterSetModuleOptions function changes the set of optional services that are associated with a specified filter module.

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

Syntax


FILTER_SET_FILTER_MODULE_OPTIONS FilterSetModuleOptions;

NDIS_STATUS FilterSetModuleOptions(
  _In_  NDIS_HANDLE FilterModuleContext
)
{ ... }

Parameters

FilterModuleContext [in]

A handle to the context area for the filter module that is the target of this request. The filter driver created and initialized this context area in the FilterAttach function.

Return value

FilterSetModuleOptions returns one of the following status values:

Return codeDescription
NDIS_STATUS_SUCCESS

FilterSetModuleOptions successfully registered the filter module's optional services and resources.

NDIS_STATUS_RESOURCES

FilterSetModuleOptions could not allocate the resources that the filter module 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

If FilterSetModuleOptions is defined, NDIS calls FilterSetModuleOptions before it calls the FilterRestart function to start the filter module.

A filter driver specifies the default values for the changeable filter module options in the NDIS_FILTER_DRIVER_CHARACTERISTICS structure that it passes to the NdisFRegisterFilterDriver function during driver initialization.

To change options for a specific filter module at run time, the filter driver must also specify an entry point for FilterSetModuleOptions in the NDIS_FILTER_DRIVER_CHARACTERISTICS structure.

To specify the options that should be changed, FilterSetModuleOptions defines a characteristics structure and calls the NdisSetOptionalHandlers function. Filter drivers must not call NdisSetOptionalHandlers from a different thread.

The possible characteristics structures that can be specified from FilterSetModuleOptions are:

NDIS_FILTER_PARTIAL_CHARACTERISTICS

NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS

NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

For information on the last four structures, see NDIS 6.0 TCP chimney offload documentation.

The options that are specified in each characteristics structure can be different for each filter module.

When NDIS calls the FilterDetach function, the filter driver should undo all the operations that were performed in FilterSetModuleOptions.

NDIS calls FilterSetModuleOptions at IRQL = PASSIVE_LEVEL.

Examples

To define a FilterSetModuleOptions 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 FilterSetModuleOptions function that is named "MySetModuleOptions", use the FILTER_SET_FILTER_MODULE_OPTIONS type as shown in this code example:


FILTER_SET_FILTER_MODULE_OPTIONS MySetModuleOptions;

Then, implement your function as follows:


_Use_decl_annotations_
NDIS_STATUS
 MySetModuleOptions(
    NDIS_HANDLE  FilterModuleContext
    )
  {...}

The FILTER_SET_FILTER_MODULE_OPTIONS 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_SET_FILTER_MODULE_OPTIONS 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

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

FilterRestart
NDIS_FILTER_DRIVER_CHARACTERISTICS
NDIS_FILTER_PARTIAL_CHARACTERISTICS
NdisFRegisterFilterDriver
NdisSetOptionalHandlers

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft