EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN callback function

Warning

Some information in this topic relates to prereleased product, which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

NetAdapterCx is preview only in Windows 10, version 1903.

Implement this optional callback to reject wake patterns that are not compatible with your hardware.

Syntax

EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN EvtNetAdapterPreviewWakePattern;

NTSTATUS EvtNetAdapterPreviewWakePattern(
  NETADAPTER Adapter,
  NETPOWERSETTINGS ExistingPowerSettings,
  NDIS_PM_WOL_PACKET WakePatternType,
  PNDIS_PM_WOL_PATTERN PatternToBeAdded
)
{...}

Parameters

Adapter

The network adapter object that the client created in a prior call to NetAdapterCreate.

ExistingPowerSettings

A handle to the net power settings object.

WakePatternType

An NDIS_PM_WOL_PACKET enumeration value that specifies the type of the WOL packet.

PatternToBeAdded

A pointer to an NDIS_PM_WOL_PATTERN structure that specifies the wake-on-LAN (WOL) pattern to accept or reject. The client driver can use this pointer to examine the NDIS_PM_WOL_PATTERN structure but should not retain it. NetAdapterCx will destroy the wake pattern structure once the driver's EvtNetAdapterPreviewWakePattern returns.

Return Value

To accept the pattern, the callback function must return STATUS_SUCCESS.

To reject the pattern, return STATUS_NDIS_PM_WOL_PATTERN_LIST_FULL.

Remarks

Drivers are not required to implement EvtNetAdapterPreviewWakePattern, as NetAdapter already blocks wake patterns that are not compatible with the driver's NET_ADAPTER_POWER_CAPABILITIES. However, if your hardware has additional limitations that cannot be expressed in the NET_ADAPTER_POWER_CAPABILITIES structure, you can provide EvtNetAdapterPreviewWakePattern to enforce those additional limitations.

Register your implementation of this callback function by setting the appropriate member of NET_ADAPTER_POWER_CAPABILITIES and then calling NetAdapterSetPowerCapabilities during EVT_NET_ADAPTER_SET_CAPABILITIES.

The client driver can use the pointer to examine the NDIS_PM_WOL_PATTERN structure but should not retain it. NetAdapterCx will destroy the wake pattern structure once the driver's EvtNetAdapterPreviewWakePattern returns.

In this callback, the driver typically uses the NETPOWERSETTINGS handle it receives in the ExistingPowerSettings parameter to iterate through the enabled wake patterns to determine whether to accept or reject PatternToBeAdded. For an example, see Configuring Power Management.

In its EvtDeviceArmWakeFromS0 and EvtDeviceArmWakeFromSx callback functions, the driver can iterate through the enabled wake patterns and protocol offloads to program them into the hardware.

Requirements

   
Target Platform Universal
Minimum KMDF version 1.21
Header netadapter.h

See Also

EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD

NetAdapterSetPowerCapabilities