NET_PNP_EVENT - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// netpnp.h
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;
View the official Windows Driver Kit DDI referenceNo description available.
The NET_PNP_EVENT structure describes a network Plug and Play (PnP) event, an NDIS PnP event, or a power management event.
NetEventAn event code that describes the event as one of the following:
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.
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.
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.
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.
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.
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.
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.
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.)
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.
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.
Indicates the activation of a list of ports that are associated with the specified binding.
Indicates the deactivation of a list of ports that are associated with the specified binding.
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.
Indicates that Network Direct Kernel (NDK) is currently enabled.
Indicates that NDK is currently disabled.
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).
Indicates that a binding event failure has occurred.
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.
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.
This event is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
An asynchronous event that reverses the effects of NetEventInhibitBindsAbove. The usage rules are below.
This event is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
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.
This event is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
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 is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
BufferThe 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:
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:
The network device does not support power management.
The fully powered state, in which the device delivers full functionality and performance.
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.
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.
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.
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).
The buffer contents are NULL.
The buffer contents are NULL.
The buffer can contain protocol-specific data. The protocol driver is responsible for validating this data.
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.
The buffer contents are NULL.
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.
The buffer contains an NDIS_PROTOCOL_PAUSE_PARAMETERS structure.
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.
Note If the buffer is NULL, the restart attributes have not changed since the previous restart.
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.
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).
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.
The Buffer member is NULL.
The Buffer member is NULL.
The Buffer member is NULL.
The buffer contains an NDIS_BIND_FAILED_NOTIFICATION structure.
The buffer contents are NULL.
The buffer contents are NULL.
The buffer contents are NULL.
The buffer contents are NULL.
The buffer contents are NULL.
BufferLengthThe number of bytes of event-specific information at Buffer.
NdisReservedAn area reserved for used by NDIS.
TransportReservedAn area reserved for used by the transport driver.
TdiReservedAn area reserved for used by TDI.
TdiClientReservedAn area reserved for used by a TDI client.
The buffer contents are NULL.
The buffer contents are NULL.
The buffer contains an NDIS_BIND_FAILED_NOTIFICATION structure.
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.
The buffer contents are NULL.
The buffer contents are NULL.
The Buffer member is NULL.
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.
The buffer contents are NULL.
The Buffer member is NULL.
The Buffer member is NULL.
The buffer contains an NDIS_PROTOCOL_PAUSE_PARAMETERS structure.
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.
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.
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).
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).
The buffer contents are NULL.
The buffer can contain protocol-specific data. The protocol driver is responsible for validating this data.
The buffer contents are NULL.
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.
Note If the buffer is NULL, the restart attributes have not changed since the previous restart.
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:
The network device does not support power management.
The fully powered state, in which the device delivers full functionality and performance.
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.
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.
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.
The buffer contents are NULL.
An asynchronous event that reverses the effects of NetEventInhibitBindsAbove. The usage rules are below.
This event is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
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 is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
Indicates that a binding event failure has occurred.
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.
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.
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.
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).
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.
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.
This event is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
Indicates that NDK is currently disabled.
Indicates that Network Direct Kernel (NDK) is currently enabled.
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.
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.)
Indicates the activation of a list of ports that are associated with the specified binding.
Indicates the deactivation of a list of ports that are associated with the specified binding.
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.
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.
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.
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.
This event is available starting with NDIS version 6.50 and must be used with V2 or later version of NET_PNP_EVENT. This event can optionally be issued by a miniport driver. Protocols and filters cannot receive this event or issue it.
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.
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.
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.
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 NetEvent member in the NET_PNP_EVENT structure identifies the type of Plug and Play or power management event. The Buffer contains information that is specific to the type of event.
NDIS_PROTOCOL_PAUSE_PARAMETERS
NDIS_PROTOCOL_RESTART_PARAMETERS
NdisIMInitializeDeviceInstanceEx
Querying the Hyper-V Extensible Switch Configuration