PNP_EVENT_HANDLER callback function

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

The ProtocolPnPEvent function is required in protocol drivers 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.

Syntax

PNP_EVENT_HANDLER ProtocolPnPEvent;

NDIS_STATUS ProtocolPnPEvent(
  _In_ NDIS_HANDLE    ProtocolBindingContext,
  _In_ PNET_PNP_EVENT NetPnPEvent
)
{ ... }

Parameters

  • ProtocolBindingContext [in]
    Specifies the handle to a protocol-allocated context area in which this driver maintains per-binding run-time state. The protocol supplied this handle when it called NdisOpenAdapter. A NetEventXxx indicated on a NULLProtocolBindingContext pertains to all network bindings. NetEventBindList and NetEventBindsComplete are always indicated on a NULLProtocolBindingContext. NetEventReconfigure can be indicated on a particular ProtocolBindingContext or a NULLProtocolBindingContext.

  • NetPnPEvent [in]
    Pointer to a NET_PNP_EVENT structure, which describes the Plug and Play event or Power Management event being indicated to the protocol driver.

Return value

ProtocolPnPEvent can return any of the following:

Return code 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:

NetEventSetPower

The device has transitioned to the requested power device power state.

NetEventQueryPower

The device can transition to the requested device power state.

NetEventQueryRemoveDevice

The device can be removed.

NetEventCancelRemoveDevice

The removal of the device has been canceled.

NetEventReconfigure

The protocol has accepted the changed configuration parameter(s).

NetEventBindList

The protocol has the new bind list and has performed related processing. For example, it has conveyed the new binding list to all bound TDI clients that have registered a ClientBinding handler with the protocol.

NetEventBindsComplete

The protocol has acknowledged the indication from NDIS that the protocol has bound to all available NICs.

NetEventPnPCapabilities

The protocol has acknowledged that the wake-up capabilities of the NIC on the specified binding have changed.

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 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:

NetEventSetPower

The device has transitioned to the requested power device power state.

NetEventQueryPower

The device can transition to the requested device power state.

NetEventQueryRemoveDevice

The device can be removed.

NetEventCancelRemoveDevice

The removal of the device has been canceled.

NetEventReconfigure

The protocol has accepted the changed configuration parameter(s).

NetEventBindList

The protocol has the new bind list and has performed related processing. For example, it has conveyed the new binding list to all bound TDI clients that have registered a ClientBinding handler with the protocol.

NetEventBindsComplete

The protocol has acknowledged the indication from NDIS that the protocol has bound to all available NICs.

NetEventPnPCapabilities

The protocol has acknowledged that the wake-up capabilities of the NIC on the specified binding have changed.

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 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. After establishing an active connection, a protocol can call PoRegisterSystemState to register a continuously busy state. As long as the state registration is in effect, the power manager does not attempt to put the system to sleep. After the connection becomes inactive, the protocol cancels the state registration by calling PoUnregisterSystemState. A protocol should never try to prevent the system from transitioning to the sleeping state by failing a NetEventQueryRemoveDevice. Note that a NetEventQueryPower is always followed by a NetEventSetPower. A NetEventSetPower to the device's current power state in effect cancels the NetEventQueryPower.

If a protocol cannot release a device (for example, because the device is in use) it must fail a NetEventQueryRemoveDevice by returning NDIS_STATUS_FAILURE.

A protocol should always succeed a NetEventCancelRemoveDevice, a NetEventReconfigure, NetEventBindsComplete, or NetEventPnPCapabilities 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.

When handling a NetEventReconfigure or a NetEventBindList, a protocol should validate the data associated with the event. For more information about such data, see NET_PNP_EVENT for Protocol Drivers.

A protocol can return NDIS_STATUS_RESOURCES for any Plug and Play or Power Management event.

Requirements

Target platform

Desktop

Version

Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolNetPnPEventinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

NET_PNP_EVENT for Protocol Drivers

NdisCompletePnPEvent

Send comments about this topic to Microsoft