OID_PM_ADD_WOL_PATTERN
As a set, NDIS protocol drivers use the OID_PM_ADD_WOL_PATTERN OID to add a power management wake-on-LAN pattern to a network adapter. The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_PM_WOL_PATTERN structure.
Remarks
NDIS 6.20 and later protocol drivers use OID_PM_ADD_WOL_PATTERN to add a Wake on LAN (WOL) pattern to a network adapter. The OID request contains criterion that the network adapter must compare to incoming packets when it is in a low power state. The network adapter must generate a wake up event when it receives a packet that matches the pattern criteria.
A protocol driver can add WOL patterns after it successfully binds to an underlying network adapter and as soon as it has the necessary data (such as the IP address of the interface) to set up the WOL pattern. The protocol driver can also add a WOL pattern in response to some other power management event notifications such as the rejection of a previously added WOL pattern or an offloaded protocol.
To avoid race conditions in NDIS and other protocol drivers that are bound to the same miniport adapter, after NDIS starts to set a network adapter to a low power state, it will fail any attempt to add a new wake up pattern to that network adapter. For example, if an NDIS protocol driver tries to add a new WOL pattern in the context of processing a NetEventSetPower event notification for that network adapter, NDIS will fail the request.
Before NDIS sends this OID request down to the underlying NDIS drivers or completes the request to the overlying driver, it sets the ULONG PatternId member of the NDIS_PM_WOL_PATTERN structure to a unique value. Protocol drivers and NDIS use this pattern identifier with the OID_PM_REMOVE_WOL_PATTERN OID request to remove the WOL pattern from the underlying network adapter.
Note 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 miniport adapters.
If NDIS or an underlying network adapter removes a WOL pattern, it generates an NDIS_STATUS_PM_WOL_PATTERN_REJECTED status indication. The StatusBuffer member of the NDIS_STATUS_INDICATION structure contains the ULONG WOL pattern identifier of the rejected WOL pattern.
The miniport driver returns one of the following status codes for the request:
NDIS_STATUS_SUCCESS
The requested pattern was added successfully. The PatternId member of the NDIS_PM_WOL_PATTERN structure contains a pattern identifier.
NDIS_STATUS_PENDING
The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete.
NDIS_STATUS_PM_WOL_PATTERN_LIST_FULL
The request failed because the pattern list is full and the network adapter cannot add another pattern.
NDIS_STATUS_RESOURCES
NDIS or underlying network adapter could not add the new pattern due to lack of resources.
NDIS_STATUS_INVALID_PARAMETER
One or more parameters in the NDIS_PM_WOL_PATTERN structure were invalid.
NDIS_STATUS_BUFFER_TOO_SHORT
The information buffer was too short. NDIS set the DATA.SET_INFORMATION.BytesNeeded member in the NDIS_OID_REQUEST structure to the minimum buffer size that is required.
NDIS_STATUS_NOT_SUPPORTED
The network adapter does not support the requested WOL pattern.
NDIS_STATUS_FAILURE
The request failed for reasons other than the preceding reasons.
Requirements
Version |
Supported in NDIS 6.20 and later. Mandatory for miniport drivers. |
Header |
Ntddndis.h (include Ndis.h) |