TdiRegisterPnPHandlers function

Article
06/19/2017

The TdiRegisterPnPHandlers function registers a set of client-supplied ClientPnPXxx routines to receive subsequent notifications of dynamic PnP events, such as the discovery of a new NIC in the machine or the removal of an existing NIC from the machine, system power-state changes, and/or the arrival and departure of network addresses registered and deregistered by the underlying transports.

Syntax

NTSTATUS TdiRegisterPnPHandlers(
  _In_  PTDI_CLIENT_INTERFACE_INFO ClientInterfaceInfo,
  _In_  ULONG                      InterfaceInfoSize,
  _Out_ HANDLE                     *BindingHandle
);

Parameters

ClientInterfaceInfo [in]
Pointer to a caller-allocated and zero-initialized buffer, formatted as follows, or to this structure on the stack:

typedef struct _TDI20_CLIENT_INTERFACE_INFO {
    union {
        struct {
            UCHAR MajorTdiVersion; // currently 2
            UCHAR MinorTdiVersion; // currently 0
        };
        // do not use following (obsolete transports)
        USHORT TdiVersion; 
    };
    USHORT Unused;
    PUNICODE_STRING ClientName;
    TDI_PNP_POWER_HANDLER  PnPPowerHandler;
    union {
        TDI_BINDING_HANDLER BindingHandler;
        // do not use following (obsolete transports)
        struct {
            TDI_BIND_HANDLER BindHandler;
            TDI_UNBIND_HANDLER UnBindHandler;
        };
    };
    union {
        struct {
            TDI_ADD_ADDRESS_HANDLER_V2 AddAddressHandlerV2;
            TDI_DEL_ADDRESS_HANDLER_V2 DelAddressHandlerV2;
        };
        // do not use following (obsolete transports)
        struct {
            TDI_ADD_ADDRESS_HANDLER AddAddressHandler;
            TDI_DEL_ADDRESS_HANDLER DelAddressHandler;
        };
    };
} TDI20_CLIENT_INTERFACE_INFO, *PTDI20_CLIENT_INTERFACE_INFO;

typedef TDI20_CLIENT_INTERFACE_INFO TDI_CLIENT_INTERFACE_INFO;

InterfaceInfoSize [in]
Specifies the size in bytes of the buffer at ClientInterfaceInfo.
BindingHandle [out]
Specifies the address of a caller-supplied variable in which TdiRegisterPnPHandlers returns a TDI-supplied opaque handle if the call succeeds. The caller should save this handle for a subsequent call TdiDeregisterPnPHandlers or, possibly but very rarely, to TdiEnumerateAddresses.

Return value

TdiRegisterPnPHandlers returns STATUS_SUCCESS if the supplied ClientPnPXxx routines will be notified of subsequent PnP and power-state-change events. Otherwise, it can return one of the following:

Return code	Description
TDI_STATUS_BAD_VERSION	If the caller set the version members in the structure at ClientInterfaceInfo to something greater than TDI_CURRENT_VERSION. The caller should not propagate this return value to higher level network components.
TDI_STATUS_BAD_CHARACTERISTICS	The given InterfaceInfoSize value is less than sizeof(TDI_CLIENT_INTERFACE_INFO). The caller should not propagate this return value to higher level network components.
STATUS_INSUFFICIENT_RESOURCES	TDI could not allocate the buffers it needed to maintain state for this client's notifications or, perhaps, other resources necessary to process this registration request. (Possibly, a subsequent call to TdiRegisterPnPHandlers will not fail for this reason if resources currently in use are released.)

Remarks

The caller must supply the following information at ClientInterfaceInfo to receive subsequent notifications of PnP/power-state changes, binding changes, and network address changes:

MajorTdiVersion set to 2 or TDI_CURRENT_MAJOR_VERSION.
MinorTdiVersion set to 0 or TDI_CURRENT_MINOR_VERSION.
ClientName set to the address of a buffered Unicode string specifying the client's named key in the registry HKLM\System\CCS\Services tree.
PnPPowerHandler set to the entry point of the caller's ClientPnPPowerChange routine.
BindingHandler set to the entry point of the caller's ClientPnPBindingChange routine.
AddAddressHandlerV2 set to the entry point of the caller's ClientPnPAddNetAddress routine.
DelAddressHandlerV2 set to the entry point of the caller's ClientPnPDelNetAddress routine.

On return from a successful call to TdiRegisterPnPHandlers, the ClientPnPBindingChange and ClientPnPAddNetAddress routines have been called one or more times with all the system-setup-time information currently available to TDI about transports and their already registered network addresses. That is, TDI has made the following initialization-time calls to the client's just registered PnP routines:

ClientPnPBindingChange has been called one or more times with the PnPOpcode TDI_PNP_OP_ADD and the buffered name of a device object created to represent an established transport-to-NIC binding by any transport already registered with TDI. ClientPnPBindingChange also could have been called one or more times with the PnPOpcode TDI_PNP_OP_PROVIDERREADY and the buffered name of any TDI transport driver that has declared itself ready to carry out network I/O operations on its respective transport-to-NIC bindings.

At each call to ClientPnPBindingChange with the PnPOpcode TDI_PNP_OP_ADD, this routine determines whether to bind itself to the underlying transport-to-NIC binding with a call to ZwCreateFile.
ClientPnPAddNetAddress has been called one or more times with each network address that these transports have already registered on their established bindings with calls to TdiRegisterNetworkAddress.

At each such call to ClientPnPAddNetAddress, this routine examines the AddressType member of the structure at the input Address to determine whether it recognizes this network protocol and returns control promptly if it does not. Otherwise, ClientPnPAddNetAddress examines the buffered string at DeviceName to determine whether the client has already bound itself to this transport. If so, ClientPnpAddNetAddress uses the input protocol-specific address information to add entries to the client-allocated internal list of valid and registered network addresses. The client might use such a registered network address for subsequent network I/O requests after opening it, again with a call to ZwCreateFile.

Note that ClientPnPBindingChange can be called with the PnPOpcode TDI_PNP_OP_ADD and TDI_PNP_OP_PROVIDERREADY subsequently during system startup if another transport-to-NIC binding is established and the transport makes successful calls to TdiRegisterDeviceObject, possibly also to TdiRegisterNetworkAddress (thereby causing one or more calls to ClientPnPAddNetAddress), and to TdiProviderReady.

In addition, when TDI determines that all possible transport-to-NIC bindings configured for the computer have been established and that every transport has indicated its readiness to transfer network data, TDI calls every registered ClientPnPBindingChange routine once more with the PnPOpcode TDI_PNP_OP_NETREADY and a NULLDeviceName pointer. This last initialization-time call to ClientPnPBindingChange indicates that the system initialization phase of setting up network communications is now done.

Following system startup, TDI makes dynamic calls to these registered ClientPnPXxx routines as the transports to which the client is bound make run-time calls to TdiRegisterDeviceObject, TdiDeregisterDeviceObject, TdiRegisterNetAddress, TdiDeregisterNetAddress, and TdiPnPPowerRequest until the client makes a reciprocal call to TdiDeregisterPnPHandlers with the returned handle at *BindingHandle.

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