PROTOCOL_NET_PNP_EVENT callback function (ndis.h)
NDIS calls the ProtocolNetPnPEvent function to indicate a network Plug and Play event, an NDIS PnP event, or a power management event to a protocol driver.
Syntax
PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;
NDIS_STATUS ProtocolNetPnpEvent(
[in] NDIS_HANDLE ProtocolBindingContext,
[in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}
Parameters
[in] ProtocolBindingContext
The handle to a protocol-driver-allocated context area in which this driver maintains per-binding run-time state information. The protocol driver supplied this handle when it called the NdisOpenAdapterEx function. A NetEventXxx event that is indicated with a NULLProtocolBindingContext applies to all bindings. NetEventBindList and NetEventBindsComplete are always indicated with a NULLProtocolBindingContext. NetEventReconfigure can be indicated with a specified ProtocolBindingContext or with a NULLProtocolBindingContext.
[in] NetPnPEventNotification
A pointer to a NET_PNP_EVENT_NOTIFICATION structure which describes the Plug and Play event or Power Management event that NDIS is indicating to the protocol driver.
Return value
ProtocolNetPnPEvent can return any of the following:
| Return code | Description |
|---|---|
|
The protocol driver successfully handled the indicated network Plug and Play event, NDIS PnP
event, or power management event. The meaning of this status code depends on the
NetEvent code in the buffered
NET_PNP_EVENT_NOTIFICATION structure at
NetPnPEvent:
|
|
The protocol driver will return its response to the indicated event asynchronously with a call to the NdisCompleteNetPnPEvent function. |
|
The protocol driver could not obtain the necessary system resources to satisfy the indicated Plug and Play or Power Management event. |
|
NDIS 6.0 and later protocol drivers must not return this status. An NDIS 5.x protocol driver that does not support Plug and Play can return this status in response to a NetEventSetPower to indicate that NDIS should unbind it from the underlying adapter. |
|
The protocol driver failed the indicated event for reasons other than those stated in the preceding list. |
A protocol driver can fail the NetEventQueryRemoveDevice and NetEventPortActivation events.
If a protocol driver fails the NetEventPortActivation event, it should not use any associated ports in subsequent operations.
A protocol driver should always succeed the NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation, and NetEventPnPCapabilities events by returning NDIS_STATUS_SUCCESS.
Remarks
The ProtocolNetPnPEvent function is required in protocol drivers to support Plug and Play and Power Management. NDIS calls ProtocolNetPnPEvent to notify a protocol driver that a network Plug and Play event, an NDIS PnP event, or Power Management event has occurred.
The NET_PNP_EVENT_NOTIFICATION structure that is passed to ProtocolNetPnPEvent describes the event. ProtocolNetPnPEvent interprets two basic pieces of information in the NET_PNP_EVENT_NOTIFICATION structure:
- A code in the NetEvent member that identifies the type of Plug and Play or Power Management event.
- Event-specific information. For example, with a NetEventSetPower event the Buffer member contains the device power state to which the device is transitioning.
A protocol driver should always succeed a NetEventQueryPower event. After establishing an active connection, a protocol driver can call the PoRegisterSystemState function 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 driver cancels the state registration by calling the PoUnregisterSystemState function. A protocol driver should never try to prevent the system from transitioning to the sleeping state by failing a NetEventQueryPower event. Note that a NetEventQueryPower event is always followed by a NetEventSetPower event. A NetEventSetPower event that specifies the underlying device's current power state in effect cancels the NetEventQueryPower event.
If a protocol driver cannot release a device (for example, because the device is in use) it must fail a NetEventQueryRemoveDevice event by returning NDIS_STATUS_FAILURE.
A protocol driver should always succeed a NetEventCancelRemoveDevice, a NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause, or NetEventPortDeactivation by returning NDIS_STATUS_SUCCESS.
When handling a NetEventReconfigure or a NetEventBindList, a protocol driver should validate the data associated with the event. For more information about such data, see NET_PNP_EVENT_NOTIFICATION.
NDIS calls ProtocolNetPnPEvent at IRQL = PASSIVE_LEVEL.
Examples
To define a ProtocolNetPnPEvent 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 ProtocolNetPnPEvent function that is named "MyNetPnPEvent", use the PROTOCOL_NET_PNP_EVENT type as shown in this code example:
PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;
Then, implement your function as follows:
_Use_decl_annotations_
NDIS_STATUS
MyNetPnPEvent(
NDIS_HANDLE ProtocolBindingContext,
PNET_PNP_EVENT_NOTIFICATION NetPnPEvent
)
{...}
The PROTOCOL_NET_PNP_EVENT 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 PROTOCOL_NET_PNP_EVENT 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 |