Edit

NdisSetOptionalHandlers function (ndis.h)

  • Article

NDIS drivers can call the NdisSetOptionalHandlers function to set or change the entry points of driver functions.

Syntax

NDIS_STATUS NdisSetOptionalHandlers(
  NDIS_HANDLE                    NdisHandle,
  PNDIS_DRIVER_OPTIONAL_HANDLERS OptionalHandlers
);

Parameters

NdisHandle

An NDIS handle that identifies a driver or driver instance.

For a protocol driver, this is the NdisDriverHandle value passed to the ProtocolSetOptions function or the NdisBindingHandle value obtained by calling the NdisOpenAdapterEx function.

For a miniport driver, this is the NdisDriverHandle value passed to the MiniportSetOptions function

For a filter driver, this is the NdisDriverHandle value passed to the FilterSetOptions function or the NdisFilterHandle value passed to the FilterAttach function.

OptionalHandlers

A pointer to one of the following NDIS structures:

NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_CO_CLIENT_OPTIONAL_HANDLERS NDIS_FILTER_PARTIAL_CHARACTERISTICS NDIS_MINIPORT_CO_CHARACTERISTICS NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_MINIPORT_SS_CHARACTERISTICS

NDIS_NDK_PROVIDER_CHARACTERISTICS

NDIS_PROTOCOL_CO_CHARACTERISTICS NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS NDIS_SHARED_MEMORY_PROVIDER_CHARACTERISTICS

Return value

NdisSetOptionalHandlers returns one of the following status values:

Return code Description
NDIS_STATUS_SUCCESS

NdisSetOptionalHandlers returns NDIS_STATUS_SUCCESS if it set the driver entry points.
NDIS_STATUS_RESOURCES

NdisSetOptionalHandlers failed due to insufficient resources.
NDIS_STATUS_NOT_SUPPORTED

NdisSetOptionalHandlers failed because the miniport driver did not specify that it supports NDIS 6.0 or later. A miniport driver specifies its NDIS version when it calls the NdisMRegisterMiniportDriver function.
NDIS_STATUS_FAILURE

NdisSetOptionalHandlers returns NDIS_STATUS_FAILURE if none of the preceding values applies.

Remarks

An NDIS driver can call NdisSetOptionalHandlers to overwrite its default entry points. The structure types passed at OptionalHandlers vary according to the type of driver.

Protocol drivers can call NdisSetOptionalHandlers in the context of the ProtocolSetOptions function. As an option, protocol drivers can call NdisSetOptionalHandlers from the ProtocolBindAdapterEx function or the ProtocolOpenAdapterCompleteEx function after the protocol driver has a valid handle from the NdisOpenAdapterEx function.

In this case, the valid structures are:

NDIS_PROTOCOL_CO_CHARACTERISTICS NDIS_CO_CLIENT_OPTIONAL_HANDLERS NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_SHARED_MEMORY_PROVIDER_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

For more information on the 2 chimney offload structures, see NDIS 6.0 TCP chimney offload documentation.

Miniport drivers call NdisSetOptionalHandlers in the context of the MiniportSetOptions function.

In this case, the valid structures are:

NDIS_MINIPORT_CO_CHARACTERISTICS NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_MINIPORT_SS_CHARACTERISTICS

NDIS_NDK_PROVIDER_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_SHARED_MEMORY_PROVIDER_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

For more information on the 2 chimney offload structures, see NDIS 6.0 TCP chimney offload documentation.

Filter drivers call NdisSetOptionalHandlers in the context of the FilterSetOptions function.

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

Filter drivers can call NdisSetOptionalHandlers for a filter module. Filter drivers call NdisSetOptionalHandlers in the context of the FilterSetModuleOptions function.

In this case, the valid structures 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 more information on the 4 chimney offload structures, see NDIS 6.0 TCP chimney offload documentation.

Requirements

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

See also

FilterAttach

FilterRestart

FilterSetOptions

MiniportSetOptions

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_CO_CLIENT_OPTIONAL_HANDLERS NDIS_FILTER_PARTIAL_CHARACTERISTICS NDIS_MINIPORT_CO_CHARACTERISTICS NDIS_MINIPORT_PNP_CHARACTERISTICS NDIS_PROTOCOL_CO_CHARACTERISTICS NDIS_SHARED_MEMORY_PROVIDER_CHARACTERISTICS

NdisMRegisterMiniportDriver

NdisOpenAdapterEx

ProtocolBindAdapterEx

ProtocolOpenAdapterCompleteEx

ProtocolSetOptions