OID_PM_ADD_PROTOCOL_OFFLOAD

As a set, NDIS protocol drivers use the OID_PM_ADD_PROTOCOL_OFFLOAD OID to add a protocol offload for power management to a network adapter. The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_PM_PROTOCOL_OFFLOAD structure.

Remarks

NDIS 6.20 and later protocol drivers use OID_PM_ADD_PROTOCOL_OFFLOAD OID to add a protocol offload for power management to a network adapter. If the request is successful, the network adapter must generate and transmit the necessary response packets for the offloaded protocol when the network adapter is in a low power state.

A protocol driver can offload a protocol 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 offload the protocol. The protocol driver can also offload a protocol 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 offload another protocol to that network adapter. For example, if an NDIS protocol driver tries to offload a protocol 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 ProtocolOffloadId member of the NDIS_PM_PROTOCOL_OFFLOAD structure to a unique value. Protocol drivers and NDIS use this protocol offload identifier with the OID_PM_REMOVE_PROTOCOL_OFFLOAD OID request to remove the protocol offload from the underlying network adapter.

Note  The protocol offload identifier is a unique value for each of the protocol offloads that are set on a network adapter. However, the protocol offload identifier is not globally unique across all network adapters.

If NDIS or an underlying network adapter rejects an offload, it generates an NDIS_STATUS_PM_OFFLOAD_REJECTED status indication. This can occur after returning NDIS_STATUS_SUCCESS for the OID. The StatusBuffer member of the NDIS_STATUS_INDICATION structure contains the ULONG protocol offload identifier of the rejected protocol offload.

For information on how a Native 802.11 Wireless LAN miniport driver uses this OID, see Adding and Deleting Low Power Protocol Offloads.

The miniport driver returns one of the following status codes for the request:

NDIS_STATUS_SUCCESS
The requested protocol offload was added successfully. The ProtocolOffloadId member of the NDIS_PM_PROTOCOL_OFFLOAD structure contains a protocol offload 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_PROTOCOL_OFFLOAD_LIST_FULL
The request failed because the protocol offload list is full and the network adapter cannot add another protocol offload.

NDIS_STATUS_RESOURCES
NDIS or an underlying network adapter could not add the new protocol offload due to lack of resources.

NDIS_STATUS_INVALID_PARAMETER
One or more parameters in the NDIS_PM_PROTOCOL_OFFLOAD 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 protocol offload.

NDIS_STATUS_FAILURE
The request failed for reasons other than the preceding reasons.

Requirements

See also

NDIS_OID_REQUEST

NDIS_PM_PROTOCOL_OFFLOAD

NDIS_STATUS_INDICATION

NDIS_STATUS_PM_OFFLOAD_REJECTED

OID_PM_REMOVE_PROTOCOL_OFFLOAD

Adding and Deleting Low Power Protocol Offloads