NDIS_SWITCH_REFERENCE_SWITCH_NIC callback function (ndis.h)

The ReferenceSwitchNic function increments the Hyper-V extensible switch reference counter for a network adapter that is connected to an extensible switch port.

Syntax

NDIS_SWITCH_REFERENCE_SWITCH_NIC NdisSwitchReferenceSwitchNic;

NDIS_STATUS NdisSwitchReferenceSwitchNic(
  [in] NDIS_SWITCH_CONTEXT NdisSwitchContext,
  [in] NDIS_SWITCH_PORT_ID SwitchPortId,
  [in] NDIS_SWITCH_NIC_INDEX SwitchNicIndex
)
{...}

Parameters

[in] NdisSwitchContext

An NDIS_SWITCH_CONTEXT value that contains the handle of the extensible switch module to which the Hyper-V extensible switch extension is attached. When the extension calls NdisFGetOptionalSwitchHandlers, this handle is returned through the NdisSwitchContext parameter.

[in] SwitchPortId

An NDIS_SWITCH_PORT_ID value that contains the unique identifier of the extensible switch port to which the virtual network adapter is connected.

[in] SwitchNicIndex

An NDIS_SWITCH_NIC_INDEX value that specifies the index of the virtual network adapter for which the extensible switch reference counter is to be incremented.

For more information on NDIS_SWITCH_NIC_INDEX values, see Network Adapter Index Values.

Note  This parameter must specify the index value of a network adapter that is in a connected state. Index values for network adapters that are in a created or disconnected state cannot be specified. For more information about network connection states, see Hyper-V Extensible Switch Port and Network Adapter States.

 

Return value

If the call succeeds, the function returns NDIS_STATUS_SUCCESS. Otherwise, it returns an NDIS_STATUS_Xxx error code that is defined in Ndis.h.

Remarks

The extensible switch extension calls ReferenceSwitchNic to increment a reference counter for a network adapter that is connected to an extensible switch port. While the reference counter has a nonzero value, the protocol edge of the extensible switch will not issue an object identifier (OID) set request of OID_SWITCH_NIC_DELETE to delete the connection to the adapter.

After the extension calls ReferenceSwitchNic, it must call DereferenceSwitchNic to decrement the extensible switch reference counter.

The extension should call ReferenceSwitchNic before it performs the following operations:

• Forwards an OID_SWITCH_NIC_REQUEST OID request over the extensible switch control path to an underlying physical network adapter.

  For more information, see Managing OID Requests to Physical Network Adapters.

• Forwards an NDIS_STATUS_SWITCH_NIC_STATUS status indication over the extensible switch control path from an underlying external adapter.

  For more information, see Managing NDIS Status Indications from Physical Network Adapters.

Note  The extension must not call ReferenceSwitchNic when forwarding packets over the extensible switch data path. The extensible switch interface manages its own reference counters for packets that are forwarded to ports and network adapter connections over the data path.

 

The extension calls ReferenceSwitchNic after the network adapter connection has reached the Network adapter connection created state. The extension must not call ReferenceSwitchNic after the connection has reached the Network adapter disconnected or Network adapter deleted states. For more information about these states, see Hyper-V Extensible Switch Port and Network Adapter States.

Note  When the extension calls ReferenceSwitchNic, it does not have to synchronize the call with its code that handles OID requests. As a result, it is possible for the extension to call ReferenceSwitchNic while the protocol edge of the extensible switch issues an OID request of OID_SWITCH_NIC_DISCONNECT. However, if the call to ReferenceSwitchNic completes with NDIS_STATUS_SUCCESS, the extension can still forward OID_SWITCH_NIC_REQUEST OID request or NDIS_STATUS_SWITCH_NIC_STATUS status indications after it handles the OID_SWITCH_NIC_DISCONNECT OID request.

 

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.30 and later.
Target Platform	Desktop
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL

See also

DereferenceSwitchNic

NDIS_STATUS_SWITCH_NIC_STATUS

NdisFGetOptionalSwitchHandlers

OID_SWITCH_NIC_DELETE

OID_SWITCH_NIC_DISCONNECT

OID_SWITCH_NIC_REQUEST