FWPS_VSWITCH_LIFETIME_EVENT_CALLBACK0 callback function (fwpsk.h)

Article
02/22/2024

The filter engine calls the vSwitchLifetimeNotifyFn (FWPS_VSWITCH_LIFETIME_EVENT_CALLBACK0) callout function to notify the callout driver about create and delete events for a virtual switch.

Note FWPS_VSWITCH_LIFETIME_EVENT_CALLBACK0 is a specific version of FWPS_VSWITCH_LIFETIME_EVENT_CALLBACK. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

Syntax

FWPS_VSWITCH_LIFETIME_EVENT_CALLBACK0 FwpsVswitchLifetimeEventCallback0;

NTSTATUS FwpsVswitchLifetimeEventCallback0(
  [in, optional] void *notifyContext,
  [in]           FWPS_VSWITCH_EVENT_TYPE eventType,
  [in]           const NDIS_SWITCH_PARAMETERS *vSwitch,
  [in, optional] const NDIS_SWITCH_PORT_ARRAY *vSwitchPorts,
  [in, optional] const NDIS_SWITCH_NIC_ARRAY *vSwitchInterfaces
)
{...}

Parameters

[in, optional] notifyContext

A pointer to a context supplied by the callout driver. The driver passed this pointer to the notifyContext parameter of the FwpsvSwitchEventsSubscribe0 function. This parameter is optional and can be NULL.

[in] eventType

The type of virtual switch event specified as one of the FWPS_VSWITCH_EVENT_TYPE enumeration values. For more information, see Remarks.

[in] vSwitch

A pointer to an NDIS_SWITCH_PARAMETERS structure that contains information about a virtual switch.

Note The information in the NDIS_SWITCH_PARAMETERS structure reflects the initial state of the virtual switch, not necessarily its current state. In particular, the NumSwitchPorts and IsActive members might still have their initial value of zero, unless a virtual switch PnP event has been triggered. Current state information can be found in the other parameters to this callback function.

[in, optional] vSwitchPorts

A pointer to an NDIS_SWITCH_PORT_ARRAY structure that specifies an array of port configuration parameters. Each element in the array specifies the parameters for a port on a virtual switch.

[in, optional] vSwitchInterfaces

A pointer to an NDIS_SWITCH_NIC_ARRAY structure that specifies an array of miniport adapter configuration parameters. Each element in the array specifies the parameters for a virtual or physical miniport adapter that is attached to a port on a virtual switch.

Return value

A callout's

FWPS_VSWITCH_LIFETIME_EVENT_CALLBACK0 function returns one of the following NTSTATUS codes.

Return code	Description
STATUS_SUCCESS	The callout driver accepts the notification from the filter engine.
Other status codes	An error occurred.

Remarks

A callout driver registers a vSwitchLifetimeNotifyFn callback function by calling
the FwpsvSwitchEventsSubscribe0 function.

If the vSwitchLifetimeNotifyFn callback is registered, the WFP filter driver notifies the callout driver when a virtual switch instance is created. Multiple instances of a virtual switch can be present in a Hyper-V host at the same time.

The WFP filter driver queries the OID_SWITCH_PARAMETERS OID in the FilterRestart function to obtain the virtual switch identifier that is associated with the current instance of the virtual switch. The WFP filter driver also queries the OID_SWITCH_NIC_ARRAY and OID_SWITCH_PORT_ARRAY OIDs to obtain the initial set of configured virtual NICs and virtual ports. The WFP filter driver passes the NDIS_SWITCH_PORT_ARRAY and NDIS_SWITCH_NIC_ARRAY structure information from the OIDs to vSwitchLifetimeNotifyFn with FWPS_VSWITCH_EVENT_VSWITCH_CREATE set in the eventType parameter.

In the WFP filter driver's FilterDetach, the filter calls with FWPS_VSWITCH_EVENT_VSWITCH_DELETE set in the eventTypevSwitchLifetimeNotifyFn parameter.

A callout driver cannot return STATUS_PENDING from vSwitchLifetimeNotifyFn.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Windows
Header	fwpsk.h (include Fwpsk.h)
IRQL	<= DISPATCH_LEVEL