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