TdiPnPPowerRequest function

Article
06/19/2017

The TdiPnPPowerRequest function forwards a power-state change notification from the transport to all its clients on a particular transport-to-NIC binding.

Syntax

NTSTATUS TdiPnPPowerRequest(
  _In_ PUNICODE_STRING          DeviceName,
  _In_ PNET_PNP_EVENT           PowerEvent,
  _In_ PTDI_PNP_CONTEXT         Context1,
  _In_ PTDI_PNP_CONTEXT         Context2,
  _In_ ProviderPnPPowerComplete ProtocolCompletionHandler
);

Parameters

DeviceName [in]
Pointer to a caller-supplied buffered Unicode string identifying the transport-created device object that represents this transport-to-NIC binding. The transport previously registered this device object with TDI, using this name, when it called TdiRegisterDeviceObject.
PowerEvent [in]
Pointer to a NET_PNP_EVENT structure, supplied by NDIS when it indicated this power-state event to the ProtocolPnPEvent function of the (monolithic) transport or of the lowest driver in the (multidriver) transport stack. The NetEvent member of this structure is set to one of the following NDIS-defined NET_PNP_EVENT_CODE values:

NetEventSetPower

NetEventQueryPower

NetEventQueryRemoveDevice

NetEventCancelRemoveDevice

Context1 [in]

Pointer to a transport-determined context associated with this type of power-state indication. This transport-supplied context information is protocol-specific in nature and intended to give clients a hint about how to interpret and handle the indication.

For example, TCP/IP passes a pointer to a list of addresses associated with the context of this notification.

Context2 [in]

Pointer to a transport-determined context associated with this type of power-state indication.

For example, TCP/IP passes a pointer to the PDO representing the physical device on which or for which this notification was generated.

ProtocolCompletionHandler [in]

Specifies the entry point of the transport-supplied completion routine, which TDI calls if any client handles this notification asynchronously and later returns something other than STATUS_SUCCESS for this indication. This TDI-defined handler can be declared as follows:

VOID
    MyPnPPowerCompletionCallback(
        IN PNET_PNP_EVENT  NetEvent,
        IN NTSTATUS  FinalStatus
        );

Return value

TdiPnPPowerRequest returns STATUS_SUCCESS if all notified clients both handled this notification synchronously and returned STATUS_SUCCESS to indicate their acceptance of the power-state change. Otherwise, it can return one of the following:

Return code	Description
STATUS_PENDING	At least one client will handle this notification asynchronously. TDI will call the transport-supplied routine at ProtocolCompletionHandler when all clients have completed their processing of this notification.
STATUS_INSUFFICIENT_RESOURCES	TDI currently cannot allocate sufficient resources to notify all clients of this power-state change. Because the availability of system resources is dynamic, a subsequent call from the same transport can succeed.

Remarks

When NDIS notifies a transport of a power-state-change event with a call to the ProtocolPnPEvent function at the lower edge of the transport driver or transport stack, the transport is responsible for notifying its higher level clients of any power-state changes that might affect their current network operations with a call to TdiPnPPowerRequest.

Note that the transport does not make this call with certain PnP-type events, in particular the NDIS-defined types NetEventReconfigure and NetEventBindingList. Instead, NDIS calls TDI with these notifications and TDI, in turn, calls the registered ClientPnPBindingChange functions of all TDI clients. Depending on the status returned by each client, NDIS calls the ProtocolBindAdapter or ProtocolUnbindAdapter functions of those transports affected by such a PnP event notification.

Such a transport might call other TdiXxx routines as a consequence of these notifications from NDIS through TDI to registered clients. For example, the transport might call TdiRegisterDeviceObject and TdiRegisterNetAddress as a consequence of a NetEventBindingList notification, which originates with a change by the end user in the Connections folder.

A transport calls TdiProviderReady during system setup as a consequence of the NetEventBindsComplete-type notification from NDIS to the ProtocolBindAdapter function at the lower edge of the transport stack.

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	Universal
Header	Tdikrnl.h (include TdiKrnl.h)
Library	Tdi.lib
IRQL	< DISPATCH_LEVEL

Share via