NET_PNP_EVENT structure (netpnp.h)
The NET_PNP_EVENT structure describes a network Plug and Play (PnP) event, an NDIS PnP event, or a power management event.
Syntax
typedef struct _NET_PNP_EVENT {
NET_PNP_EVENT_CODE NetEvent;
PVOID Buffer;
ULONG BufferLength;
ULONG_PTR NdisReserved[4];
ULONG_PTR TransportReserved[4];
ULONG_PTR TdiReserved[4];
ULONG_PTR TdiClientReserved[4];
} NET_PNP_EVENT, *PNET_PNP_EVENT;
Members
NetEvent
An event code that describes the event as one of the following:
NetEventSetPower
Indicates that the power manager has sent a Set Power request, which specifies a transition to a system power state. NDIS translates this state to an appropriate device power state for the device.
For more information, see the Remarks section.
NetEventQueryPower
Indicates that the power manager has sent a Query Power request, which requests a transition to a system power state. NDIS translates this state to an appropriate device power state for the device.
For more information, see the Remarks section.
NetEventQueryRemoveDevice
Indicates that the PnP Manager has sent a Query Remove Device request. The PnP Manager sends this request to query whether a device can be removed without disrupting operations.
NetEventCancelRemoveDevice
Indicates that the PnP Manager has sent a Cancel Remove Device request. The PnP Manager sends this request to cancel the removal of a device after the PnP Manager sends a Query Remove Device request.
NetEventReconfigure
Indicates that the configuration has changed for a network component. For example, if a user, through the Network and Dial-up Connections folder, changes the IP address for TCP/IP, NDIS indicates the NetEventReconfigure event to the TCP/IP protocol. Also, an intermediate driver typically uses this event as a trigger to call the NdisIMInitializeDeviceInstanceEx function and start its virtual miniports. For more information about NetEventReconfigure, see NetEventIMReEnableDevice.
NetEventBindList
Indicates to a protocol driver that its bind list processing order has been reconfigured. This list indicates a relative order that applies to bindings when processing, for example, a user request that might be routed to one of several bindings. The buffer that is passed with this event contains a list of device names that are formatted as null-terminated Unicode strings. The format of each device name is identical to the AdapterName member that is passed to a call to the ProtocolBindAdapterEx function.
NetEventBindsComplete
Indicates that a protocol driver has bound to all the NICs that it can bind to. NDIS will not indicate any more NICs to the protocol unless a PnP NIC is plugged into the system.
NetEventPnPCapabilities
Indicates that the user enabled or disabled the wake-up capabilities of the underlying adapter. (The binding is specified by the ProtocolBindingContext parameter that is passed to the ProtocolNetPnPEvent function.)
NetEventPause
Indicates that the specified protocol binding should enter the Pausing state. The binding will enter the Paused state after NDIS has completed all the outstanding send requests for the binding.
NetEventRestart
Indicates that the specified protocol binding has entered the Restarting state. After the protocol driver is ready to resume send and receive operations for the binding, the binding enters the Running state.
NetEventPortActivation
Indicates the activation of a list of ports that are associated with the specified binding.
NetEventPortDeactivation
Indicates the deactivation of a list of ports that are associated with the specified binding.
NetEventIMReEnableDevice
Indicates that the configuration has changed for a virtual miniport of an NDIS 6.0 or later intermediate driver. NetEventIMReEnableDevice is similar to the NetEventReconfigure event except that the intermediate driver receives this event for a single virtual miniport and the NetEventReconfigure event applies to all the intermediate driver's virtual miniports. For example, an intermediate driver receives the NetEventIMReEnableDevice event when a user disables and then enables a single virtual miniport from the Device Manager or another source. For examples of intermediate driver power management, see the NDIS MUX Intermediate Driver and Notify Object driver sample available in the Windows driver samples repository on GitHub.
NetEventNDKEnable
Indicates that Network Direct Kernel (NDK) is currently enabled.
NetEventNDKDisable
Indicates that NDK is currently disabled.
NetEventFilterPreDetach
Indicates that a filter is about to be detached, so that the filter can perform any necessary cleanup that isn't possible in the FilterDetach handler (because the OID and indication paths are closed at that time).
NetEventBindFailed
Indicates that a binding event failure has occurred.
NetEventSwitchActivate
Indicates that the Hyper-V Extensible Switch has completed activation, and switch extensions can now safely query for further switch configuration. The indication is only used in the Hyper-V Extensible Switch stack, issued by the extension miniport. See Querying the Hyper-V Extensible Switch Configuration and NDIS_SWITCH_PARAMETERS for more details.
NetEventInhibitBindsAbove
A synchronous event that prevents other filters and protocols from binding to the miniport adapter. Any filters or protocols that were previously bound will be unbound before the event completes. The usage rules are below.
- Avoid leaving the miniport adapter in the inhibit state, for longer than 1000 milliseconds.
- This event can only be issued after MiniportInitializeEx begins and must not be issued after MiniportHaltEx returns.
- This event can only be issued when the miniport adapter is in a D0 state.
- Because this event is blocking, it should not be issued by any context that would cause a deadlock.
- Locks must not be held while issuing this event.
- This event must be issued at PASSIVE_LEVEL.
NetEventAllowBindsAbove
An asynchronous event that reverses the effects of NetEventInhibitBindsAbove. The usage rules are below.
- This event can only be issued after MiniportInitializeEx begins and must not be issued after MiniportHaltEx returns.
- This event can only be issued when the miniport adapter is in a D0 state.
- Locks must not be held while issuing this event.
- This event must be issued at PASSIVE_LEVEL.
NetEventRequirePause
A synchronous event that indicates the protocols and filters including the miniport adapter must be paused. The protocols and filters and the miniport adapter are guaranteed to be paused when the NdisMNetPnPEvent routine returns. The usage rules are below.
- Avoid delaying between NetEventAllowStart and NetEventRequirePause events for longer than 1000 milliseconds to prevent delay in user applications.
- This event can only be issued after MiniportInitializeEx begins and must not be issued after MiniportHaltEx returns.
- There is no guarantee that NDIS will call MiniportPause after this event is issued. In particular, if your miniport adapter is already paused, NDIS won't introduce an extra start-pause loop. This means that the amount of times MiniportPause called is not greater than, less than, or equal to the amount this event is issued.
- Because this event is blocking, it should not be issued by any context that would cause a deadlock.
- Locks must not be held while issuing this event.
NetEventAllowStart
An asynchronous event that indicates the protocols and filters including the miniport adapter does not need to be paused. The usage rules are below. There is no guaranteed pause state for any driver in the protocols and filters after the NdisMNetPnPEvent routine returns.
- This event can only be issued after MiniportInitializeEx begins and must not be issued after MiniportHaltEx returns.
- Because this event is blocking, it should not be issued by any context that would cause a deadlock.
- Locks must not be held while issuing this event.
Buffer
The address of a buffer that contains information that is specific to the event indicated in the NetEvent member. For each type of event, the buffer contains the following information:
NetEventSetPower
The buffer contains the device power state to which the device is transitioning.
When NDIS calls a protocol driver's ProtocolNetPnPEvent function, the device state is NDIS_DEVICE_POWER_STATE, which can be one of the following values:
NdisDeviceStateUnspecified
The network device does not support power management.
NdisDeviceStateD0
The fully powered state, in which the device delivers full functionality and performance.
NdisDeviceStateD1
A low-power state, in which transmit requests from the host are not honored by the device, data received by the device is not transferred to host memory, and no interrupts can occur. Some device context may be lost. Depending on the capabilities of the NIC and its miniport driver, the device might be able to generate a wake-up signal.
NdisDeviceStateD2
A low-power state that is similar to NdisDeviceStateD1, except that more power and less context are typically saved and more time is required to transition to the fully powered state.
NdisDeviceStateD3
The off state, in which power has been fully removed from the device.
For protocol drivers, NdisDeviceStateD0 means that the NIC is fully powered and is available for normal operations. Any other device state means that the device is not fully powered and is not available for sending and receiving network data.
NetEventQueryPower
The buffer contains the device power state that is requested for the device. The device state is NDIS_DEVICE_POWER_STATE (which is described in the NetEventSetPower value description).
NetEventQueryRemoveDevice
The buffer contents are NULL.
NetEventCancelRemoveDevice
The buffer contents are NULL.
NetEventReconfigure
The buffer can contain protocol-specific data. The protocol driver is responsible for validating this data.
NetEventBindList
The buffer contains a revised binding list for the network component that the NET_PNP_EVENT_NOTIFICATION structure is being passed to. The bind list, which is a series of null-terminated Unicode strings, has a REG_MULTI_SZ format. Each of the strings is an adapter name. TDI clients that are bound to a protocol use this bind list to reorder their bindings. The protocol driver is responsible for validating this list.
NetEventBindsComplete
The buffer contents are NULL.
NetEventPnPCapabilities
The buffer is a ULONG that contains a bitmask. When the NDIS_DEVICE_WAKE_UP_ENABLE flag is set in the bitmask, the wake-up capabilities of the NIC are enabled. Otherwise, the NIC's wake-up capabilities are disabled. (The binding is specified by the ProtocolBindingContext parameter that is passed to ProtocolNetPnPEvent.) When set to zero, this flag indicates that the NIC's wake-up capabilities are disabled.
NetEventPause
The buffer contains an NDIS_PROTOCOL_PAUSE_PARAMETERS structure.
NetEventRestart
The buffer might contain NULL or an NDIS_PROTOCOL_RESTART_PARAMETERS structure. NDIS provides a pointer to an NDIS_RESTART_ATTRIBUTES structure in the RestartAttributes member of the NDIS_PROTOCOL_RESTART_PARAMETERS structure.
NetEventPortActivation
The buffer contains the first entry in a list of NDIS_PORT structures that identify the ports that NDIS will activate. You can use the Next member of the NDIS_PORT structure to get the next structure in the list.
NetEventPortDeactivation
The buffer contains an array of port numbers, of type NDIS_PORT_NUMBER (defined as ULONG), that identify the NDIS ports that NDIS will deactivate. To calculate the number of elements in the array, divide the value of the BufferLength member, which is in the NET_PNP_EVENT structure that is specified in the NetPnPEvent member of NET_PNP_EVENT_NOTIFICATION, by sizeof(NDIS_PORT_NUMBER).
NetEventIMReEnableDevice
The buffer contains a pointer to a variable of type NDIS_STRING that contains a null-terminated Unicode string that names the device object of a virtual miniport for the device that is being enabled. The string is a full path name—for example, \Device\DeviceName.
NetEventNDKEnable
The Buffer member is NULL.
NetEventNDKDisable
The Buffer member is NULL.
NetEventFilterPreDetach
The Buffer member is NULL.
NetEventBindFailed
The buffer contains an NDIS_BIND_FAILED_NOTIFICATION structure.
NetEventSwitchActivate
The buffer contents are NULL.
NetEventAllowBindsAbove
The buffer contents are NULL.
NetEventInhibitBindsAbove
The buffer contents are NULL.
NetEventAllowStart
The buffer contents are NULL.
NetEventRequirePause
The buffer contents are NULL.
BufferLength
The number of bytes of event-specific information at Buffer.
NdisReserved[4]
An area reserved for used by NDIS.
TransportReserved[4]
An area reserved for used by the transport driver.
TdiReserved[4]
An area reserved for used by TDI.
TdiClientReserved[4]
An area reserved for used by a TDI client.
Remarks
In NDIS 6.0 and later versions, when the operating system issues a system PnP event or a power management event to a target device object that represents a miniport adapter, NDIS translates the event into a NET_PNP_EVENT_NOTIFICATION structure. The NetPnPEvent member of the NET_PNP_EVENT_NOTIFICATION structure is a NET_PNP_EVENT structure.
NDIS passes a pointer to the NET_PNP_EVENT structure to each protocol driver that is bound to the miniport adapter by calling the protocol driver's ProtocolNetPnPEvent function. The protocol driver should save this pointer, because the pointer is an input parameter to the NdisCompleteNetPnPEvent function, which the driver calls to complete the call to ProtocolNetPnPEvent asynchronously.
NDIS passes a pointer to the NET_PNP_EVENT structure to each filter driver that is bound to the miniport adapter by calling the filter driver's FilterNetPnPEvent function. The filter driver does not have to save this pointer because the driver must complete the call to FilterNetPnPEvent synchronously.
Starting with NDIS 6.30, the protocol or filter driver must follow these guidelines when NDIS calls the ProtocolNetPnPEvent or FilterNetPnPEvent functions:
-
If the NetEvent member of the NET_PNP_EVENT structure is set to NetEventSetPower, the driver must stop generating new I/O requests. Also, the driver must not wait for the completion of any pending I/O requests.
After the protocol or filter driver returns from ProtocolNetPnPEvent or FilterNetPnPEvent, NDIS will not pause and restart these drivers during power-state transitions if the following conditions are true:
- The underlying miniport driver sets the NDIS_MINIPORT_ATTRIBUTES_NO_PAUSE_ON_SUSPEND flag in the NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure. The driver passes a pointer to this structure in its call to the NdisMSetMiniportAttributes function.
- All filter drivers that are attached to the miniport driver support NDIS 6.30 or later versions of NDIS.
- All protocol drivers that are bound to the miniport driver support NDIS 6.30 or later versions of NDIS.
- If the NetEvent member of the NET_PNP_EVENT structure is set to NetEventSetPower or NetEventQueryPower, the driver must not wait for the completion of any pending I/O requests.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Supported in NDIS 5.1, and NDIS 6.0 and later. For more information about the NDIS 5.1 version of this structure, see NET_PNP_EVENT (NDIS 5.1). |
| Header | netpnp.h (include Ndis.h, Netpnp.h) |