Edit

Share via

Adding and Deleting Wake on LAN Patterns

  • Article

To add a wake-on-LAN (WOL) pattern, NDIS protocol drivers issue an OID set request of OID_PM_ADD_WOL_PATTERN. The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_PM_WOL_PATTERN structure. Protocol drivers should specify a WOL packet if that WOL packet is supported by a network adapter. When the network adapter does not support the WOL packet, the protocol driver should use the WOL bitmap wake method.

NDIS_PM_WOL_PATTERN includes the following information:

Priority
Contains the priority of the WOL pattern. If an overlying driver adds a higher priority WOL pattern when there are no resources available for more WOL patterns, NDIS might remove a lower priority WOL pattern to free resources. Miniport drivers should ignore this member. A protocol driver can specify any priority that is within the pre-defined range from NDIS_PM_WOL_PRIORITY_LOWEST to NDIS_PM_WOL_PRIORITY_HIGHEST.

WoLPacketType
Contains an NDIS_PM_WOL_PACKET enumeration value that specifies the type of the WOL packet.

FriendlyName
Contains an NDIS_PM_COUNTED_STRING structure that contains the user-readable description of the WOL packet.

PatternId
Contains an NDIS-provided value that identifies the WOL pattern. Before NDIS sends the OID_PM_ADD_WOL_PATTERN OID request down to the underlying NDIS drivers or completes the request to the overlying driver, NDIS sets PatternId to a value that is unique among the WOL patterns on a network adapter.

NextWoLPatternOffset
Contains the offset (from the beginning of the OID request InformationBuffer) of one NDIS_PM_WOL_PATTERN structure to the next NDIS_PM_WOL_PATTERN structure in a list for the OID_PM_WOL_PATTERN_LIST OID. For more information about OID_PM_WOL_PATTERN_LIST, see Obtaining the Current Settings of WOL Patterns.

WoLPattern
Contains one of the IPv4TcpSynParameters, IPv6TcpSynParameters, EapolRequestIdMessageParameters, or WoLBitMapPattern structures in a union.

IPv4TcpSynParameters
Contains IPv4 TCP synchronize (SYN) information.

IPv6TcpSynParameters
Contains IPv6 TCP SYN information.

EapolRequestIdMessageParameters
Contains 802.1X EAP over LAN (EAPOL) request identity message parameters.

WoLBitMapPattern
Contains a WOL bitmap pattern specification.

NDIS assigns an identifier that is unique for network adapter to every WOL pattern. The pattern identifier is a unique value for each of the patterns that are set on a network adapter. However, the pattern identifier is not globally unique across all network adapters. NDIS passes the identifier to the underlying network adapter when NDIS sends the OID_PM_ADD_WOL_PATTERN OID request to the miniport driver. If adding the WOL pattern is successful, NDIS returns the identifier to the overlying driver that added the WOL pattern. The overlying driver uses the identifier to remove a previously added WOL pattern. The pattern identifier is also used in status indications to the overlying drivers when a WOL pattern is removed from a network adapter.

Protocol drivers must issue the OID set request of OID_PM_REMOVE_WOL_PATTERN to remove all of the patterns that they added to a network adapter before they close a binding to that network adapter. The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to a pattern identifier.

User-mode applications use the GUID_PM_REMOVE_WOL_PATTERN WMI GUID to remove a previously added WOL pattern from a network adapter. NDIS translates this WMI request to the OID set request of OID_PM_REMOVE_WOL_PATTERN for the network adapter. NDIS deletes all of the WOL patterns that an application added from the network adapter before it halts the network adapter.

NDIS allows multiple NDIS protocol drivers to add WOL patterns to the same network adapter. To ensure that the right set of WOL patterns have been set when the number of requested WOL patterns is higher than what a network adapter can support, protocol drivers assign a priority to each requested WOL pattern in the Priority member of the NDIS_PM_WOL_PATTERN structure. When NDIS cannot add a new high priority WOL pattern because the network adapter is out of resources, NDIS deletes one of the lower priority patterns (if any) and attempts to add the high priority pattern again.

Note  A miniport driver should fail a pattern add request and return the STATUS_NDIS_PM_WOL_PATTERN_LIST_FULL status code to allow NDIS to re-prioritize the patterns.

If NDIS deletes one of the lower priority patterns, it notifies the overlying driver that set the deleted pattern with an NDIS_STATUS_PM_WOL_PATTERN_REJECTED status indication. The StatusBuffer member of the NDIS_STATUS_INDICATION structure contains a ULONG for the WOL pattern identifier of the rejected WOL pattern. NDIS provided the WOL pattern identifier in the PatternId member of the NDIS_PM_WOL_PATTERN structure.

For wireless network adapter's that might use an infrastructure element to offload the patterns as it roams across the infrastructure, a new infrastructure element might not support the same capabilities and the miniport driver can send an NDIS_STATUS_PM_WOL_PATTERN_REJECTED status indication with an appropriate status code.