ProtocolPnPEvent

  • Article

ProtocolPnPEvent is a required function in any protocol driver to support Plug and Play and/or Power Management. NDIS calls ProtocolPnPEvent to indicate a Plug and Play event or a Power Management event to a protocol bound to a NIC.

NDIS_STATUS ProtocolPnPEvent(
  NDIS_HANDLE ProtocolBindingContext,
  PNET_PNP_EVENT NetPnPEvent
);

Parameters

  • ProtocolBindingContext
    [in] Specifies the handle to a protocol-allocated context area in which this driver maintains per-binding runtime state. The protocol supplied this handle when it called NdisOpenAdapter. A NetEventXxx indicated on a NULL ProtocolBindingContext pertains to all network bindings. NetEventBindsComplete is always indicated on a NULL ProtocolBindingContext. NetEventReconfigure can be indicated on a particular ProtocolBindingContext or a NULL ProtocolBindingContext.
  • NetPnPEvent
    [in] Points to a NET_PNP_EVENT structure, which describes the Plug and Play event or Power Management event being indicated to the protocol driver.

Return Values

The following table shows the NDIS status events that ProtocolPnPEvent can return.

Status event Description
NDIS_STATUS_SUCCESS The protocol successfully handled the indicated Plug and Play or Power Management event. The meaning of this status code depends on the NetEvent code in the buffered NET_PNP_EVENT structure at NetPnPEvent. The following list shows Status Code meanings for NDIS_STATUS_SUCCESS.
  • NetEventSetPower: The device has transitioned to the requested power device power state.
  • NetEventQueryPower: The device can transition to the requested device power state.
  • NetEventReconfigure: The protocol has accepted the changed configuration parameter(s).
  • NetEventBindsComplete: The protocol has acknowledged the indication from NDIS that the protocol has bound to all available NICs.
NDIS_STATUS_PENDING The protocol will return its response to the indicated event asynchronously with a call to NdisCompletePnPEvent.
NDIS_STATUS_RESOURCES The protocol could not obtain the necessary system resources to satisfy the indicated Plug and Play or Power Management event.
NDIS_STATUS_NOT_SUPPORTED A legacy (non-PnP-aware) protocol can return this status in response to a NetEventSetPower to indicate that NDIS should unbind the it from the NIC.
NDIS_STATUS_FAILURE The protocol failed the indicated Plug and Play or Power Management event. The meaning of this status code depends on the NetEvent code in the buffered NET_PNP_EVENT structure at NetPnPEvent.
The following list shows Status Code meanings for NDIS_STATUS_FAILURE.
  • NetEventSetPower: The protocol should not fail this event.
  • NetEventQueryPower: The protocol should not fail this event.
  • NetEventReconfigure: The protocol should not fail this event.
  • NetEventBindsComplete: The protocol should not fail this event

Remarks

NDIS calls ProtocolPnPEvent to notify a protocol bound to a network NIC that the operating system has issued a Plug and Play or Power Management event to the device object representing the NIC. NDIS calls the ProtocolPnPEvent function of each protocol bound to the NIC.

The NET_PNP_EVENT structure passed to ProtocolPnPEvent describes the Plug and Play or Power Management event. ProtocolPnPEvent interprets two basic pieces of information in the NET_PNP_EVENT structure:

  • A NetEvent code that describes the Plug and Play or Power Management event.
  • Event-specific information (for example, for a NetEventSetPower, the device power state to which the device is transitioning).

The following list shows guidelines for protocol use:

  • The protocol should save the NetPnPEvent pointer. This pointer is a required input parameter to NdisCompletePnPEvent, which the protocol must subsequently call if ProtocolPnPEvent returns NDIS_STATUS_PENDING.
  • A protocol should always succeed a NetEventQueryPower. As long as the state registration is in effect, the Power Manager does not attempt to put the system to sleep. Note that a NetEventSetPower always follows a NetEventQueryPower. A NetEventSetPower to the device's current power state in effect cancels the NetEventQueryPower.
  • A protocol should always succeed a NetEventReconfigure or a NetEventBindsComplete by returning NDIS_STATUS_SUCCESS.
  • A PnP-aware protocol must always succeed a NetEventSetPower. A legacy protocol that does not support power management returns NDIS_STATUS_NOT_SUPPORTED in response to a NetEventSetPower to indicate that NDIS should unbind the protocol from the NIC.
  • A protocol can return NDIS_STATUS_RESOURCES for any Plug and Play or Power Management event.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.
Link Library: Ndislib.lib.

See Also

NdisOpenAdapter

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.