NET_PNP_EVENT (Compact 2013)

3/26/2014

This 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.
    • 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.
    • 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 sending 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 network adapters that it can bind to. NDIS will not indicate any more network adapters to the protocol unless a PnP network adapter is plugged into the system.
    • NetEventPnPCapabilities
      Indicates whether the wake-up capabilities of the network adapter on the specified binding have changed. (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 resembles 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.
  • Buffer
    The address of a buffer that contains information that is specific to the event that is 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 that is 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 could generate a wake-up signal.
      • NdisDeviceStateD2
        A low-power state that resembles 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 network adapter is fully powered and is available for usual 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 contains a ULONG that contains the NdisDeviceWakeUpEnable flag. When set to 1, this flag indicates that the wake-up capabilities of the network adapter on the specified binding are enabled. (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.
    • NetEventPortActivation
      The buffer contains the first entry in a list of NDIS_PORT structures that identify the ports that NDIS will start. 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.
  • BufferLength
    The number of bytes of event-specific information at Buffer.
  • NdisReserved
    An area reserved for used by NDIS.
  • TransportReserved
    An area reserved for used by the transport driver.
  • TdiReserved
    An area reserved for used by TDI.
  • TdiClientReserved
    An area reserved for used by a TDI client.

Remarks

In NDIS 6.0, 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.

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.

Requirements

Header

ndis.h

See Also

Reference

NDIS Protocol Driver Structures
FilterNetPnPEvent
NDIS_PROTOCOL_PAUSE_PARAMETERS
NDIS_PROTOCOL_RESTART_PARAMETERS
NDIS_RESTART_ATTRIBUTES
NdisCompleteNetPnPEvent
NdisIMInitializeDeviceInstanceEx
NET_PNP_EVENT_NOTIFICATION
ProtocolBindAdapterEx
ProtocolNetPnPEvent
NDIS TCP/IP Offload Structures