TdiPnPPowerRequest function

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:

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

See also

ClientPnPPowerChange

NET_PNP_EVENT for Protocol Drivers

ProtocolBindAdapter

ProtocolPnPEvent

ProtocolUnbindAdapter

TdiPnPPowerComplete

TdiProviderReady

TdiRegisterDeviceObject

TdiRegisterNetAddress

Send comments about this topic to Microsoft