NdisSetOptionalHandlers function (ndis.h)
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_CHARACTERISTICSNDIS_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_CHARACTERISTICSReturn value
NdisSetOptionalHandlers returns one of the following status values:
| Return code | Description |
|---|---|
|
NdisSetOptionalHandlers returns NDIS_STATUS_SUCCESS if it set the driver entry points. |
|
NdisSetOptionalHandlers failed due to insufficient resources. |
|
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. |
|
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_CHARACTERISTICSFor 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_CHARACTERISTICSNDIS_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_CHARACTERISTICSFor 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_CHARACTERISTICSNDIS_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) |