ClientPnPAddNetAddress routine

Article
06/19/2017

The ClientPnPAddNetAddress routine is initially called by TDI as a consequence of the client's own call to TdiRegisterPnPHandlers. Subsequently, TDI calls ClientPnPAddNetAddress as a consequence of any transport's call to TdiRegisterNetAddress or, possibly but very rarely, as the consequences of the client's own call to TdiEnumerateAddresses.

Syntax

VOID ClientPnPAddNetAddress(
  _In_ PTA_ADDRESS      Address,
  _In_ PUNICODE_STRING  DeviceName,
  _In_ PTDI_PNP_CONTEXT Context
);

Parameters

Address [in]
Pointer to a buffered network address, formatted as a TA_ADDRESS structure. The contents and layout of this buffer are protocol-specific in nature with the information supplied at Address dependent on the AddressType and AddressLength members as set by the underlying transport.
DeviceName [in]
Pointer to a buffered Unicode string, which effectively identifies the transport on which the given network address is being registered with TDI. Typically, this is the name of the transport-created device object originally passed in to the ClientPnPBindingChange routine when the client was offered this binding.
Context [in]
Pointer to a transport-supplied context associated with this address.

For example, TCP/IP passes in a pointer to the PDO representing the device on which this new address has just arrived.

Return value

None

Remarks

A client must register its ClientPnPAddNetAddress routine with a call to TdiRegisterPnPHandlers to be called to initialize whatever state the client maintains about currently registered network addresses. For maximum performance, the client should set up and maintain an internal list of valid network addresses for any transport to which it binds itself with a call to ZwCreateFile.

Subsequent to the sequence of system-startup-time calls to ClientPnPAddNetAddress, TDI calls this routine whenever a PnP-supporting transport registers a new network address with TDI. That is, ClientPnPAddNetAddress can be called at run time with a new address supplied by any transport, even a transport to which it is not bound. Consequently, ClientPnPAddNetAddress should return control promptly if the client does not recognize the protocol-specific type of the input address. A check on the AddressType member of the TA_ADDRESS structure is more efficient than doing a string comparison on the buffered contents at DeviceName.

The format and contents of the buffer at Address depend on the value of the AddressType member in the TA_ADDRESS structure. The underlying transport is responsible for providing only the specification of the new network address. If the TA_ADDRESS structure of a particular type also contains a Socket identifier or any other such collateral member(s), those member(s) should be ignored by ClientPnPAddNetAddress.

For the input Context parameter, the value of the ContextType member in the TDI_PNP_CONTEXT structure provides a hint about how to interpret this transport-supplied and protocol-determined context information. The Context pointer can be NULL if the underlying transport does not provide context information when it calls TdiRegisterNetAddress.

A reciprocal call to TdiDeregisterPnPHandlers disables calls to ClientPnPAddNetAddress.

A client's call to TdiEnumerateAddresses causes a sequence of calls to its ClientPnPAddNetAddress routine, one for each currently valid network address that a particular transport to which the client is bound has already registered with TDI. Consequently, most clients never call TdiEnumerateAddresses to avoid incurring the performance penalty of the resulting sequence of calls to ClientPnPAddNetAddress. However, a client could make this call to restore the integrity of its internal list of binding-specific valid network addresses if that list might have become corrupted.

TDI calls ClientPnPAddNetAddress 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)

Share via