W_PNP_EVENT_NOTIFY_HANDLER callback function

Article
06/19/2017

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 MiniportPnPEventNotify function handles the notification of Plug and Play (PnP) events.

Syntax

W_PNP_EVENT_NOTIFY_HANDLER MiniportPnPEventNotify;

VOID MiniportPnPEventNotify(
  _In_ NDIS_HANDLE           MiniportAdapterContext,
  _In_ NDIS_DEVICE_PNP_EVENT PnPEvent,
  _In_ PVOID                 InformationBuffer,
  _In_ ULONG                 InformationBufferLength
)
{ ... }

Parameters

MiniportAdapterContext [in]
Specifies the handle to a miniport-allocated context area in which the miniport driver maintains per-NIC state, set up by MiniportInitialize.
PnPEvent [in]
An event code that describes the Plug and Play event as one of the following:
- NdisDevicePnPEventSurpriseRemoved
  Indicates that the specified adapter has been unexpectedly removed from the system.
- NdisDevicePnPEventPowerProfileChanged
  Indicates that the power profile of the host system has changed.
InformationBuffer [in]
When PnPEvent is set to NdisDevicePnPEventPowerProfileChanged, InformationBuffer points to a ULONG variable that is set to either of the following values:
- NdisPowerProfileBattery
  Specifies that the host system is running on battery power.
- NdisPowerProfileAcOnline
  Specifies that the host system is running on AC power.
When PnPEvent is set to NdisDevicePnPEventSurpriseRemoved, InformationBuffer is NULL.
InformationBufferLength [in]
Size, in bytes, of the buffer at InformationBuffer.

Return value

None

Remarks

All NDIS 5.1 miniport drivers must export a MiniportPnPEventNotify function. Miniport drivers that have a WDM lower edge should export a MiniportPnPEventNotify function.

After initializing a miniport driver or after a miniport driver receives an OID_PNP_SET_POWER notification that specifies a device power state of NdisDeviceStateD0 (the powered-on state), NDIS calls the miniport's MiniportPnPEventNotify function with PnPEvent set to NdisDevicePnPEventPowerProfileChanged. InformationBuffer, in this case, points to a ULONG variable, the value of which indicates whether the system is running on battery power ( NdisPowerProfileBattery) or AC power ( NdisPowerProfileAcOnline). A miniport driver can use this information to adjust the power consumption of its NIC. For example, the miniport driver for a wireless LAN device could reduce power consumption if the system is running on battery power or increase power consumption if the system is running on AC power.

An NDIS miniport driver with a WDM lower edge should export a MiniportPnPEventNotify function so that it can be notified when its NIC is removed without prior notification through the user interface. If such a miniport driver does not export a MiniportPnPEventNotify function, any pending IRPs that the miniport driver sent to the underlying bus driver cannot be completed after the surprise removal of the device.

When a miniport driver receives notification of a surprise removal, it should note internally that the device has been removed and cancel any pending IRPs that it sent down to the underlying bus driver. After calling the MiniportPnPEventNotify function to indicate the surprise removal, NDIS calls the miniport's MiniportHalt function. If the miniport driver receives any requests to send packets or query or set OIDs before its MiniportHalt function is called, it should immediately complete such requests with a status value of NDIS_STATUS_NOT_ACCEPTED.

System support for MiniportPnPEventNotify is available in Windows XP and later operating systems.

MiniportPnPEventNotify runs synchronously at IRQL = PASSIVE_LEVEL and in the context of a system thread.

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportDevicePnPEventNotify instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP.
Header	Ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL (see Comment section)

Share via