ClientPnPPowerChange routine
The ClientPnPPowerChange routine is called by TDI as a consequence of a transport's call to TdiPnPPowerRequest or, for a user-initiated network reconfiguration, as a consequence of a call by NDIS.
Syntax
NTSTATUS ClientPnPPowerChange(
_In_ PUNICODE_STRING DeviceName,
_In_ PNET_PNP_EVENT PowerEvent,
_In_ PTDI_PNP_CONTEXT Context1,
_In_ PTDI_PNP_CONTEXT Context2
);
Parameters
DeviceName [in]
Pointer to a buffered Unicode string that typically identifies the transport-created device object representing the target for a client's network I/O through a particular transport or transport-to-NIC binding.PowerEvent [in]
Pointer to a NET_PNP_EVENT-type structure indicating the type of notification, which can be either of the following types of notifications:The NetEvent member of this structure has been set by the underlying transport to NetEventSetPower, NetEventQueryPower, NetEventQueryRemoveDevice, or NetEventCancelRemoveDevice (subsequent to the failure of a NetEventQueryRemoveDevice).
The NetEvent member of this structure has been set by NDIS to NetEventBindList or NetEventReconfigure. That is, a run-time call to ClientPnPPowerChange from TDI can occur as a consequence of an end-user-initiated change in the Connections folder.
Context1 [in]
Pointer to protocol-determined context associated with this notification if the underlying transport called TdiPnPPowerRequest. For example, TCP/IP passes a pointer to a list of addresses associated with the context of this notification.Otherwise, this points to a context supplied by NDIS to TDI as a result of a user-initiated change in the network configuration. For example, when the user reconfigures the network in the Connections folder, thereby requesting a change in existing network bindings, NDIS must notify all currently registered TDI clients affected by such a binding change to give them the opportunity to register or deregister their ClientPnPXxx handlers.
Context2 [in]
Pointer to protocol-determined context associated with this notification. For example, TCP/IP returns a pointer to the PDO of the physical device on which this notification was generated.Otherwise, this points to a context supplied by NDIS to TDI as a result of a user-initiated change in the network configuration, such as a pointer to the PDO of the underlying NIC to be reconfigured.
Return value
ClientPnPPowerChange can return STATUS_PENDING if the client must notify its own clients of a power-state, query-device-removal, or device-removal event. Otherwise, it should return either STATUS_SUCCESS or a client-determined failure status, such as STATUS_FILES_OPEN or STATUS_UNSUCCESSFUL, to reject a NetEventSetPowerDevice-type or NetEventQueryRemoveDevice-type request if one of its own clients currently is depending on the underlying NIC in question.
ClientPnPPowerChange can return STATUS_SUCCESS when it is called with NetEventBindList or NetEventReconfigure notifications, because these are inherently synchronous operations.
Remarks
A client must register its ClientPnPPowerChange routine with a call to TdiRegisterPnPHandlers to begin receiving these notifications whenever any PnP-supporting transport or NDIS calls TdiPnPPowerRequest. That is, ClientPnPPowerChange can be called with a DeviceName pointer supplied by any transport, even a transport to which it is not bound. Consequently, ClientPnPPowerChange should return control promptly if the client does not recognize the transport identified at DeviceName or, when notified about a user-initiated network reconfiguration, if the client determines that it has no reason to establish a new or release an existing transport-to-NIC binding.
On the other hand, if the client decides to register or deregister its PnP handlers on a transport as the consequence of a NetEventBindingList or NetEventReconfigure notification from NDIS, the given transport will subsequently be called to bind itself to a new NIC or even to unbind itself from a NIC to which it is currently bound. That is, NDIS calls the ProtocolBindAdapter or ProtocolUnbindAdapter function at the lower edge of the transport stack on behalf of this client. The transport's subsequent call to TdiRegisterDeviceObject or TdiDeregisterDeviceObject, in turn, causes a call to the ClientPnPBindingChange function of the client.
If ClientPnPPowerChange returns STATUS_SUCCESS for a call with the input PowerEvent of type NetEventQueryRemoveDevice, the client can expect a subsequent call to its ClientPnPBindingChange routine with the PnPOpcode TDI_PNP_OP_DEL if all other clients bound to the same transport-to-NIC stack also succeed this notification. Otherwise, the client can expect another call to ClientPnPPowerChange with the input PowerEvent of type NetEventCancelRemoveDevice.
In general, ClientPnPPowerChange must decide whether to notify its own clients when it receives NetEventQueryPowerDevice and NetEventSetPowerDevice notifications. For example, on set-power notifications that indicate the underlying NIC might be powered down into a hibernating state, ClientPnPPowerChange might return STATUS_PENDING in order to check with its own clients about their anticipated needs to carry out network I/O operations on the given binding. However, the NetEventSetPowerDevice-type of notification occurs after a system-determined period of no network I/O demand on a particular NIC, so the client usually can assume that its own clients have no need for notifications of this type.
If ClientPnPPowerChange returns STATUS_PENDING, the client must call TdiPnPPowerComplete as soon as it has complete the operations it initiated at this notification.
A reciprocal call to TdiDeregisterPnPHandlers disables subsequent calls to ClientPnPPowerChange.
TDI calls ClientPnPPowerChange at IRQL < DISPATCH_LEVEL.
Note The TDI feature is deprecated and will be removed in future versions of Microsoft Windows. Depending on how you use TDI, use either the Winsock Kernel (WSK) or Windows Filtering Platform (WFP). For more information about WFP and WSK, see Windows Filtering Platform and Winsock Kernel. For a Windows Core Networking blog entry about WSK and TDI, see Introduction to Winsock Kernel (WSK).
Requirements
Target platform |
Desktop |
Header |
Tdikrnl.h (include TdiKrnl.h) |
IRQL |
< DISPATCH_LEVEL (see Remarks section) |
See also