ProtocolPnPEvent (Compact 2013)
3/26/2014
ProtocolPnPEvent is a required function in any protocol driver 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
NDIS_STATUS ProtocolPnPEvent(
NDIS_HANDLE ProtocolBindingContext,
PNET_PNP_EVENT NetPnPEvent
);
Parameters
- ProtocolBindingContext
[in] Specifies the handle to a protocol-allocated context area in which this driver maintains per-binding runtime state. The protocol supplied this handle when it called NdisOpenAdapter. A NetEventXxx indicated on a NULL ProtocolBindingContext pertains to all network bindings. NetEventBindsComplete is always indicated on a NULL ProtocolBindingContext. NetEventReconfigurecan be indicated on a particular ProtocolBindingContextor a NULL ProtocolBindingContext.
- NetPnPEvent
[in] Points 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
The following table shows the NDIS status events that ProtocolPnPEvent can return.
Status event |
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. The following list shows Status Code meanings for NDIS_STATUS_SUCCESS.
|
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 the 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. The following list shows Status Code meanings for NDIS_STATUS_FAILURE.
|
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 following list shows guidelines for protocol use:
- 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. As long as the state registration is in effect, the Power Manager does not attempt to put the system to sleep. Note that a NetEventSetPower always follows a NetEventQueryPower. A NetEventSetPower to the device's current power state in effect cancels the NetEventQueryPower.
- A protocol should always succeed a NetEventReconfigure or a NetEventBindsComplete 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.
- A protocol can return NDIS_STATUS_RESOURCES for any Plug and Play or Power Management event.
Requirements
Header |
ndis.h |
Library |
Ndislib.lib |