TdiRegisterNetAddress function

The TdiRegisterNetAddress function notifies a transport's clients that it has just established a connection to a remote node with a particular network address or that the transport has just created a new network address for the computer on which it is running.

Syntax

NTSTATUS TdiRegisterNetAddress(
  _In_  PTA_ADDRESS      Address,
  _In_  PUNICODE_STRING  DeviceName,
  _In_  PTDI_PNP_CONTEXT Context,
  _Out_ HANDLE           *AddrRegistrationHandle
);

Parameters

• Address [in]
  Pointer to a caller-allocated buffer, formatted as a TA_ADDRESS structure, that contains the protocol-type-specific TDI_ADDRESS_XXX address specification.

• 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 when it called TdiRegisterDeviceObject. In effect, this string identifies the transport-to-NIC binding on which this network address is being registered.

• Context [in]
  Pointer to a transport-determined context associated with this address.

  For example, TCP/IP returns a pointer to the PDO of the physical device on which this address arrived.

• AddrRegistrationHandle [out]
  Specifies the caller-supplied location of a variable in which TdiRegisterNetAddress returns an opaque handle if this call succeeds.

Return value

TdiRegisterNetAddress returns STATUS_SUCCESS when it has notified all the transport's clients of the registration. Otherwise, it can return STATUS_INSUFFICIENT_RESOURCES. (Because the availability of system resources is dynamic, a subsequent call from the same transport can succeed.)

Remarks

Before it calls TdiRegisterNetAddress, the transport allocates a buffer, which can be pageable, to contain the specification of the new network address. The transport should zero-initialize this buffer first and then set up the members of the TA_ADDRESS structure. When it makes this call, a transport must provide only the new network address in the remainder of the buffer starting at Address. That is, if any additional members are defined for collateral information in the transport's protocol-type-specific TDI_ADDRESS_XXX substructure, those members should be zero when the transport calls TdiRegisterNetAddress.

TdiRegisterNetAddress makes copies of the transport-supplied device name and context data, but it makes no attempt to interpret this caller-supplied information. At the discretion of the transport developer, the input Context pointer can be NULL, or it can be used to pass any additional protocol-specific information about each newly registered network address from the transport to its clients. When it notifies each client, TdiRegisterNetAddress calls each registered ClientPnPAddNetAddress function with pointers to its copied device name and context information.

Each ClientPnPAddNetAddress function can use whatever context information the underlying transport supplied at Context and, possibly, the device name, to determine whether the new address is of interest to that client. The input Context pointer remains valid until the transport calls TdiDeregisterNetAddress, thereby causing a call to the ClientPnpDelNetAddress routine. The input DeviceName pointer remains valid until the transport calls TdiDeregisterDeviceObject, thereby causing a call to the ClientPnPBindingChange routine with the PnPOpcode TDI_PNP_OP_DEL. However, every client must treat this TDI state as read-only information.

A successful caller of TdiRegisterNetAddress should save the returned value at *AddrRegistrationHandle for a subsequent and reciprocal call to TdiDeregisterNetAddress.

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

ClientPnPAddNetAddress

TA_ADDRESS

TdiDeregisterDeviceObject

TdiDeregisterNetAddress

TDI_PNP_CONTEXT

Send comments about this topic to Microsoft