SET_OPTIONS callback function (ndis.h)

Artikel
10/21/2021

NDIS calls a driver's XxxSetOptions function to allow the driver to register optional services. This function is defined as MiniportSetOptions for miniport drivers, ProtocolSetOptions for protocol drivers, or FilterSetOptions for filter drivers.

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

Syntax

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

Parameters

[in] NdisDriverHandle

A handle that identifies a driver. NDIS returns this handle to the driver when it returns from the driver registration function ( NdisMRegisterMiniportDriver for miniport drivers, NdisRegisterProtocolDriver for protocol drivers, and NdisFRegisterFilterDriver for filter drivers).

[in] DriverContext

The handle that the driver passed to NdisRegisterXxxDriver that identifies the driver context area, where Xxx is the type of driver (Miniport, Protocol, or Filter).

Return value

XxxSetOptions returns one of the following status values:

Return code	Description
NDIS_STATUS_SUCCESS	XxxSetOptions successfully registered the driver's optional services and resources.
NDIS_STATUS_RESOURCES	XxxSetOptions could not allocate the resources that the driver requires.
NDIS_STATUS_XXX or NTSTATUS_XXX	The 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

XxxSetOptions is an optional function. NDIS calls XxxSetOptions within the context of the driver's call to the NdisRegisterXxxDriver function, where Xxx is the type of driver (Miniport, Protocol, or Filter).

XxxSetOptions registers optional services and can allocate other driver resources. To register optional MiniportXxx, ProtocolXxx, or FilterXxx functions, the driver calls the NdisSetOptionalHandlers function. The driver passes the handle from the NdisDriverHandle parameter at the NdisHandle parameter of NdisSetOptionalHandlers and passes a characteristics structure at the OptionalHandlers parameter.

Miniport drivers can apply to the optional services defined in the following characteristics structures:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(see NDIS 6.0 TCP chimney offload documentation)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(see NDIS 6.0 TCP chimney offload documentation)

Protocol drivers can apply to the optional services defined in the following characteristics structures:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

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

NDIS can call the driver's other MiniportXxx, ProtocolXxx, or FilterXxx functions at any time after XxxSetOptions returns. The driver should be prepared to be called back at its initialization function:(MiniportInitializeEx for miniport drivers, ProtocolBindAdapterEx for protocol drivers, and FilterAttach for filter drivers).

For miniport drivers, the miniport adapters are in the Halted state before the NDIS calls MiniportInitializeEx. For protocol drivers, the protocol bindings are in the Unbound state before the NDIS calls ProtocolBindAdapterEx. For filter drivers, the filter modules are in the Detached state before the NDIS calls FilterAttach.

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

Miniport and filter drivers' XxxDriverUnload should undo all the operations that were performed in XxxSetOptions

NDIS calls XxxSetOptions at IRQL = PASSIVE_LEVEL.

Examples

To define a XxxSetOptions 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.

In the Ndis.h header file, the SET_OPTIONS callback function is further defined as follows:

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

This enables all NDIS drivers to implement their XxxSetOptions callback functions with the same syntax. Miniport drivers use the MINIPORT_SET_OPTIONS type, protocol drivers use the PROTOCOL_SET_OPTIONS type, and filter drivers use the FILTER_SET_OPTIONS type.

For example, to define a MiniportSetOptions function that is named "MySetOptions", use the MINIPORT_SET_OPTIONS type as shown in this code example:

MINIPORT_SET_OPTIONS MySetOptions;

Then, implement your function as follows:

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

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

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL

Delen via