MINIPORT_DEVICE_PNP_EVENT_NOTIFY callback function (ndis.h)

Article
10/21/2021

NDIS calls a miniport driver's MiniportDevicePnPEventNotify function to notify the driver of Plug and Play (PnP) events.

Note You must declare the function by using the MINIPORT_DEVICE_PNP_EVENT_NOTIFY type. For more information, see the following Examples section.

Syntax

MINIPORT_DEVICE_PNP_EVENT_NOTIFY MiniportDevicePnpEventNotify;

void MiniportDevicePnpEventNotify(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNET_DEVICE_PNP_EVENT NetDevicePnPEvent
)
{...}

Parameters

[in] MiniportAdapterContext

A handle to a context area that the miniport driver allocated in its MiniportInitializeEx function. The miniport driver uses this context area to maintain state information for a miniport adapter.

[in] NetDevicePnPEvent

A pointer to a NET_DEVICE_PNP_EVENT structure that describes a device Plug and Play event.

Return value

None

Remarks

A driver specifies the MiniportDevicePnPEventNotify entry point when it calls the NdisMRegisterMiniportDriver function.

NDIS calls the driver's MiniportDevicePnPEventNotify function with the DevicePnPEvent member of the NetDevicePnPEvent parameter set to NdisDevicePnPEventPowerProfileChanged after one of the following events:

Driver initialization is complete.
The driver received an OID_PNP_SET_POWER notification that specifies the powered-on state ( NdisDeviceStateD0).

In the second case, the value at InformationBuffer indicates whether the system is running on battery power (NdisPowerProfileBattery) or AC power (NdisPowerProfileAcOnline). A driver can use this information to adjust the power consumption of the specified miniport adapter. For example, the 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.

When a driver receives a surprise removal notification (the DevicePnPEvent member of the NetDevicePnPEvent parameter is NdisDevicePnPEventSurpriseRemoved), it should:

Note internally that the device has been removed.
Cancel any pending IRPs that it sent down to the underlying bus driver.

After NDIS calls the MiniportDevicePnPEventNotify function to indicate a surprise removal, NDIS calls the driver's MiniportHaltEx function. If the driver receives any send requests or OID requests before NDIS calls MiniportHaltEx, it should immediately complete such requests with a status value of NDIS_STATUS_NOT_ACCEPTED.

NDIS calls MiniportDevicePnPEventNotify at IRQL = PASSIVE_LEVEL.

Examples

To define a MiniportDevicePnPEventNotify function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a MiniportDevicePnPEventNotify function that is named "MyDevicePnPEventNotify", use the MINIPORT_DEVICE_PNP_EVENT_NOTIFY type as shown in this code example:

MINIPORT_DEVICE_PNP_EVENT_NOTIFY MyDevicePnPEventNotify;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyDevicePnPEventNotify(
    NDIS_HANDLE  MiniportAdapterContext,
    PNET_DEVICE_PNP_EVENT  NetDevicePnPEvent
    )
  {...}

The MINIPORT_DEVICE_PNP_EVENT_NOTIFY function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the MINIPORT_DEVICE_PNP_EVENT_NOTIFY function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL
DDI compliance rules	NdisOidComplete

Share via