Hardware Dev Center

FilterSetOptions routine

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

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

Syntax


FILTER_SET_OPTIONS FilterSetOptions;

NDIS_STATUS FilterSetOptions(
  _In_ NDIS_HANDLE NdisDriverHandle,
  _In_ NDIS_HANDLE DriverContext
)
{ ... }

Parameters

NdisDriverHandle [in]

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

DriverContext [in]

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

Return value

FilterSetOptions returns one of the following status values:

Return codeDescription
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.

There are no optional filter driver services in the current Windows version.

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.

Examples

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


FILTER_SET_OPTIONS MySetOptions;

Then, implement your function as follows:


_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

The FILTER_SET_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_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

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

FilterDriverUnload
NDIS_FILTER_DRIVER_CHARACTERISTICS
NdisFRegisterFilterDriver
NdisSetOptionalHandlers

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft