ProtocolSetOptions (Compact 2013)

  • Статья

3/26/2014

NDIS calls a protocol driver's ProtocolSetOptions function to allow the protocol driver to register optional services.

Syntax

NDIS_STATUS
  ProtocolSetOptions(
    IN NDIS_HANDLE  NdisDriverHandle,
    IN NDIS_HANDLE  DriverContext
    );

Parameters

  • NdisDriverHandle
    A handle that identifies a protocol driver. NDIS returns this handle to the protocol driver when it returns from the NdisRegisterProtocolDriver function.
  • DriverContext
    The handle that the driver passed to NdisRegisterProtocolDriver that identifies the driver context area.

Return Value

ProtocolSetOptions returns one of the following status values:

Value

Meaning

NDIS_STATUS_SUCCESS

ProtocolSetOptions successfully registered the protocol driver's optional services and resources.

NDIS_STATUS_RESOURCES

ProtocolSetOptions could not allocate the resources that the protocol driver requires.

NDIS_STATUS_XXX or NTSTATUS_XXX

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

ProtocolSetOptions is an optional function. NDIS calls ProtocolSetOptions within the context of the protocol driver's call to the NdisRegisterProtocolDriver function.

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

The optional services are defined in the following structures:

  • NDIS_PROTOCOL_CO_CHARACTERISTICS
  • NDIS_CO_CLIENT_OPTIONAL_HANDLERS
  • NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS
  • NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS
  • NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

NDIS can call the protocol driver's other ProtocolXxx functions at any time after ProtocolSetOptions returns. The driver should be prepared to be called back at the ProtocolBindAdapterEx function. The protocol bindings are in the Unbound state before the NDIS calls ProtocolBindAdapterEx.

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

NDIS calls ProtocolSetOptions at IRQL = PASSIVE_LEVEL.

See Also

Reference

NDIS Protocol Driver Functions
ProtocolBindAdapterEx
NdisOpenAdapterEx
NdisRegisterProtocolDriver
NdisSetOptionalHandlers