Handling PnP Events and PM Events in a Protocol Driver (NDIS 5.1)
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.
When the operating system issues a Plug and Play IRP or a Power Management IRP to a target device object that represents a NIC, NDIS intercepts the IRP. NDIS indicates the event to each bound protocol and each bound intermediate driver by calling the driver's ProtocolPnPEventfunction. In the call to ProtocolPnPEvent, NDIS passes a pointer to a NET_PNP_EVENT structure that describes the Plug and Play event or Power Management event being indicated. For more information about the NET_PNP_EVENT structure, see NET_PNP_EVENT for Protocol Drivers.
The following list contains Plug and Play and Power Management events, as indicated by the NetEventcode in the NET_PNP_EVENT structure:
NetEventSetPower
Indicates a Set Power request, which specifies that the NIC transition to a particular power state. A Power-Management-aware protocol driver should always succeed this event by returning NDIS_STATUS_SUCCESS. A legacy protocol driver can return NDIS_STATUS_NOT_SUPPORTED to indicate that NDIS should unbind it from the NIC.
NetEventQueryPower
Indicates a Query Power request, which queries whether the NIC can make a transition to a particular power state. A protocol driver should always succeed a NetEventQueryPower. After establishing an active connection, a protocol driver can call PoRegisterSystemState to register a continuous 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 driver cancels the state registration by calling PoUnregisterSystemState. A protocol driver 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 that sets the device's current power state in effect cancels the NetEventQueryPower.
NetEventQueryRemoveDevice
Indicates a Query Remove Device request, which queries whether the NIC can be removed without disrupting operations. If a protocol driver cannot release a device (for example, because the device is in use) it must fail a NetEventQueryRemoveDevice by returning NDIS_STATUS_FAILURE.
NetEventCancelRemoveDevice
Indicates a Cancel Remove Device request, which cancels the removal of an underlying NIC. The protocol driver should always succeed this event by returning NDIS_STATUS_SUCCESS.
NetEventReconfigure
Indicates that the configuration has changed for a network component. For example, if a user changes the IP address for TCP/IP, NDIS indicates this event to the TCP/IP protocol with the NetEventReconfigure code. The protocol driver can, in rare circumstances, return a failure code if it is not able to apply the indicated configuration changes and there are no available default values. A failed attempt to allocate memory is an example of a case in which the protocol returns a failure code. Returning an error code can result in prompting the user to reboot the system.
A protocol should validate NetEventReconfigure-related data passed to its ProtocolPnPEvent function. For more information about such data, see NET_PNP_EVENT for Protocol Drivers.
NetEventBindList
Indicates to a protocol driver that its bind list processing order has been reconfigured. This list indicates a relative order to be applied to the protocol's bindings when processing, for example, a user request that might be routed to one of several bindings. The buffer passed with this event contains a list of device names formatted as NULL-terminated Unicode strings. The format of each device name is identical to the DeviceName parameter passed to a call to ProtocolBindAdapter.
A protocol should validate NetEventBindList -related data passed to its ProtocolPnPEvent function. For more information about such data, see NET_PNP_EVENT for Protocol Drivers.
A protocol should validate NetEventBindList-related data passed to its ProtocolPnPEvent function. For more information about such data, see NET_PNP_EVENT for Protocol Drivers.
NetEventBindsComplete
Indicates that a protocol driver has bound to all the NICs to which it can bind. NDIS will not indicate any more bindings to the protocol driver unless, for example, a Plug and Play NIC is plugged into the system.
NetEventPnPCapabilities
Indicates whether the wake-up capabilities of the NIC on the specified binding have changed. (The ProtocolBindingContext parameter that NDIS passes to ProtocolPnPEvent specifies the binding )
The Buffermember of the NET_PNP_EVENT structure points to a buffer that contains information specific to the event being indicated.
A protocol driver can complete the call to ProtocolPnPEventasynchronously with NdisCompletePnPEvent.